{"slug": "your-agent-keeps-guessing-your-conventions-write-the-file-it-actually-reads", "title": "Your agent keeps guessing your conventions. Write the file it actually reads.", "summary": "A developer built ContextForge, a tool that snapshots a repository's file tree and key files to draft agent instruction files such as .cursorrules, CLAUDE.md, AGENTS.md and .github/copilot-instructions.md. The tool runs a deterministic parser before any model call to extract facts like framework, test runner and CI configuration, then tags each statement with provenance (detected, inferred or unknown) so the agent is never given a confidently wrong convention. It returns a Context Score out of 100 and uses explicit HTTP status codes and source labels so rule-based drafts are never presented as AI output.", "body_md": "Every team I have watched adopt Cursor, Claude Code or Codex hits the same wall in week two.\n\nThe agent writes plausible code that does not fit the repo. It invents a test command. It puts a\n\ncomponent in `src/components/` when everything else lives in `app/ui/`. It edits a file that is\n\ngenerated.\n\nThe usual diagnosis is \"the model is not smart enough.\" It usually is not that. The agent was never\n\ntold the rules — because nobody wrote them down.\n\nThere is a file for this. Cursor reads `.cursorrules`. Claude Code reads `CLAUDE.md`. Codex and most\n\nharnesses read `AGENTS.md`. Copilot reads `.github/copilot-instructions.md`. If those files do not\n\nexist, the agent improvises, and improvising means guessing.\n\nSo: write the file. The problem is that writing a good one takes 30–90 minutes per repo, and it rots\n\nthe moment you switch test runners.\n\n[ContextForge](https://contextforge.lxsaihub.com) takes a snapshot of your repo — a file tree, plus\n\noptionally one or two key files like `package.json` — and drafts those instruction files for you.\n\nThe interesting part is not that it calls a model. Everything calls a model. The interesting part is\n\n**what runs before the model.**\n\nBefore any model is involved, a parser reads your tree and extracts facts:\n\n`next.config.*`, `vite.config.*`, `angular.json`…)` vitest.config.*`, `jest.config.*`, `playwright.config.*`…)`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`…)` pages/index.tsx` and `app/page.tsx` are both Next.js entry\npoints, but they are different routers, and a naive regex misses both`scripts` in your `package.json`\nNone of that needs a model. Which means none of it can fail because a model is down.\n\nThe model-assisted pass writes readable conventions from those facts. Its prompt forbids invention:\n\nit may only restate what was supplied, and anything marked as a guess has to be written as a question.\n\nWhich brings me to the part I care about most.\n\nThis is the failure mode nobody warns you about. If your `AGENTS.md` confidently states a convention\n\nyour repo does not follow, the agent trusts the instruction **over the code**. An empty file makes the\n\nagent cautious. A wrong file makes it confidently wrong.\n\nSo every fact carries a provenance tag:\n\n`detected``\"scripts.test\": \"vitest run\"` is a fact.`inferred`\nHere is a slice of real output:\n\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\nnpm run build\nnpm run lint\n- Test command is undetermined\n```\n\nThat last line is the product working correctly. It did not know, so it said so.\n\nThis is where most AI products quietly cheat, so here is the whole behaviour table:\n\n| Situation | Response | \n|---|---|\n| Fair-use quota exhausted | `429` — checked*before* the model call | \n| No API key configured | `503 AI_NOT_CONFIGURED` | \n| Upstream model call fails | `502 AI_UPSTREAM_FAILED` | \n| You explicitly asked for a demo | `200` +`demo: true` + \"Demo mode — not live AI\" | \n| Live success | `200` +`source: Model-assisted` | \n| Model unavailable, rule-based draft | `200` +`source: Rule-based` | \n\nThe last two rows are the point. A rule-based draft is **never** labelled as AI output, and a failed\n\nmodel call is **never** disguised as a successful one. If the tool cannot tell you something, it says\n\nso rather than filling the gap with something plausible.\n\n(While building this I actually caught myself violating the fourth row: an explicit demo request was\n\nrouting through the model, so an upstream outage turned a demo into a 502. A demo must always\n\nsucceed. Fixed.)\n\nEvery run returns a **Context Score** out of 100, built from what it could actually determine — build\n\ncommand, test command, lint command, entry points, stack, directory conventions, forbidden paths.\n\nA repo where it found everything scores 100. A repo where you pasted three files scores 40 and hands\n\nyou a list of what to fill in. The score is not a quality judgement about your project; it is a\n\nstatement about how much evidence the tool had.\n\nThe honest limitation I would want to know as a user: the fair-use quota is stored in serverless\n\nmemory, so it is per-instance rather than a true global limit. A hard global limit needs shared\n\nstorage (KV or Edge Config) and that is not shipped yet.\n\nPaste the output of `git ls-files` into [ContextForge](https://contextforge.lxsaihub.com) and see what\n\nit makes of your repo. The five example outputs are on\n\n[GitHub](https://github.com/lixingliangsy/contextforge) if you want to judge the format before\n\nhanding over a tree.\n\nAnd if the generated file says something your repo does not do — fix it, then re-run. That is the\n\nwhole workflow.", "url": "https://wpnews.pro/news/your-agent-keeps-guessing-your-conventions-write-the-file-it-actually-reads", "canonical_source": "https://dev.to/lixingliangsy/your-agent-keeps-guessing-your-conventions-write-the-file-it-actually-reads-167n", "published_at": "2026-09-26 00:06:23+00:00", "updated_at": "2026-09-26 00:30:50.575609+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "agent-protocols"], "entities": ["ContextForge", "Cursor", "Claude Code", "Codex", "GitHub Copilot", "Next.js", "Vitest", "GitHub Actions"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/your-agent-keeps-guessing-your-conventions-write-the-file-it-actually-reads", "markdown": "https://wpnews.pro/news/your-agent-keeps-guessing-your-conventions-write-the-file-it-actually-reads.md", "text": "https://wpnews.pro/news/your-agent-keeps-guessing-your-conventions-write-the-file-it-actually-reads.txt", "jsonld": "https://wpnews.pro/news/your-agent-keeps-guessing-your-conventions-write-the-file-it-actually-reads.jsonld"}}