{
  "id": 9867156,
  "title": "Your agent keeps guessing your conventions. Write the file it actually reads.",
  "url": "https://urgent.news/2026/09/26/your-agent-keeps-guessing-your-conventions-write-the-file-it-actually",
  "topic": "ai",
  "section": "AI",
  "published": "2026-09-26T00:06:23.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/lixingliangsy/your-agent-keeps-guessing-your-conventions-write-the-file-it-actually-reads-167n"
  },
  "original_language": "en",
  "account": "Every team using Cursor, Claude Code, or Codex encounters the same issue after two weeks of development. The agent generates plausible code that conflicts with the existing repository structure. It invents a test command and places components in the wrong directory. Sometimes, the agent even alters files that are auto-generated. The typical explanation given is that the model lacks sufficient intelligence. However, the root cause is far simpler. No one has explicitly outlined the conventions needed for the agent to function correctly.\n\nThese conventions exist in specific files for each AI tool: Cursor uses .cursorrules, Claude Code utilizes CLAUDE.md, and Codex and many other tools rely on AGENTS.md. Copilot reads instructions from .github/copilot-instructions.md. If these files are absent, the agent must resort to guessing, which often leads to incorrect assumptions. Writing a comprehensive set of instructions can take between 30 to 90 minutes per repository, and these guidelines quickly become outdated as the project evolves, especially when switching test runners.\n\nContextForge addresses this challenge by creating a snapshot of your repository, capturing the file tree and essential files like package.json. This tool then generates the necessary instruction files on your behalf. The key advantage lies in the pre-model phase, where deterministic parsing extracts facts about your project's structure and dependencies. The process involves three stages:\n\n1. Deterministic Parsing: A parser analyzes your repository's structure to extract critical information:\n- Package manager (identified from the lockfile)\n- Framework (Next.js, Vite, Angular, etc.)\n- Test runner (Vitest, Jest, Playwright, etc.)\n- CI system (GitHub Actions, GitLab CI, Jenkins, etc.)\n- Entry points (pages/index.tsx vs app/page.tsx in Next.js)\n\n2. Prose Generation: The extracted facts are transformed into readable conventions. This stage is allowed to refuse if it cannot confidently determine a fact and labels any guesses as such.\n\n3. Output Generation: The final draft is created with explicit provenance tags for each fact. Facts are marked as \"detected\" if they were directly provided, \"inferred\" if they were guessed from filenames, or \"unknown,\" which directs them to an Open questions section rather than being fabricated.\n\nThe output is comprehensive, detailing the project's languages, package manager, framework, test runner, CI system, and commands. For example, a generated output might look like this:\n\n## Project\n- **Languages:** TypeScript\n- **Package manager:** npm\n- **Framework:** Next.js\n- **Test runner:** Vitest\n- **CI:** GitHub Actions\n\n## Commands\n- **npm run build**\n- **npm run lint**\n\nIn this scenario, the test command remains undetermined, indicating that the tool acknowledged its limitation without inventing an answer. When the model is unavailable, ContextForge employs a rule-based draft that is not labeled as AI-generated, ensuring transparency. If the model fails, instead of concealing the issue, ContextForge explicitly states \"Model unavailable, rule-based draft\" or \"Live success\" when the model is functioning correctly. Each run returns a Context Score out of 100, which reflects the amount of evidence successfully gathered about your project. A score of 100 means all essential information was accurately determined, while a lower score provides a list of areas needing further input.\n\nContextForge does not require any connectors, OAuth, or GitHub Apps; users simply paste their repository tree. The tool retains no data, ensuring privacy and security. It does not claim to eliminate hallucinations, only to provide informed guidance based on available evidence. The output is a draft containing open questions, which require human review and resolution. The limitation regarding the fair-use quota is stored in serverless memory, requiring per-instance management. For a practical demonstration, paste the output of git ls-files into ContextForge to evaluate how the tool assesses your repository's structure. All example outputs are available on GitHub for reference. If the generated file contradicts your project's conventions, revise it and re-run ContextForge to obtain an accurate draft.",
  "summary": "Every team I have watched adopt Cursor, Claude Code or Codex hits the same wall in week two. The agent writes plausible code that does not fit the repo. It invents a test command. It puts a component in src/components/ when everything else lives in app/ui/ . It edits a file that is generated. The usual diagnosis is \"the model is not smart enough.\" It usually is not that. The agent was never told…",
  "key_points": [
    "Cursor, Claude Code, and Codex share same issue after two weeks",
    "Missing conventions file leads to agent's incorrect assumptions",
    "ContextForge creates snapshot to generate accurate instructions"
  ],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}