{"slug": "why-does-your-ai-keep-guessing-about-your-project", "title": "Why Does Your AI Keep Guessing About Your Project?", "summary": "A developer writing the Code Meet AI newsletter outlined a four-file setup for making code projects \"agent-ready\" so coding agents like Claude Code, Codex and Cursor stop re-guessing project context each session. The approach builds on ICM (Interpretable Context Methodology), which uses small files that point to the next file so an agent reads only what a task needs, and centers on an AGENTS.md front door that Claude Code pulls in via a single @AGENTS.md import line. The setup also designates a single source of truth for facts and places written fences around high-risk areas like payments and database schemas, requiring the agent to stop and show a plan before changing them.", "body_md": "**TL;DR**\n\nI write [Code Meet AI](https://codemeetai.substack.com/p/how-to-stop-your-coding-agent-guessing?utm_source=devto&utm_medium=referral&utm_campaign=agent-ready-projects), the newsletter where I document how I actually use AI to ship real products, receipts included. New guides land there first.\n\nIf you run Claude Code, Codex or Cursor on a project most days, this is the setup that saves you the same correction every session. The last piece, [How to brief an AI agent in six lines](https://codemeetai.substack.com/p/how-to-brief-an-ai-agent-in-six-lines?utm_source=devto&utm_medium=referral&utm_campaign=agent-ready-projects), gave every task six questions to answer before an agent starts: context, owner, effects, evidence, continuity and learning. This one moves most of those answers into the project itself, so you write them once.\n\nEvery session starts from zero. A project that is ready for an agent writes the answers down where the agent looks first: what the project is, how to prove a change works, what is off limits, and where each fact lives.\n\nThe method behind this is ICM, the Interpretable Context Methodology: small files point to the next file, so the agent reads only what the task needs. Jake Van Clief and David McDermott wrote it up ([arXiv:2603.16021](https://arxiv.org/abs/2603.16021?utm_source=devto&utm_medium=referral&utm_campaign=agent-ready-projects)). My own second brain runs on it, and here it moves from a folder of notes to a code project.\n\nSay you have a small app. It keeps its data in Supabase and takes payments with Stripe. Four files make it agent-ready.\n\nThe main file follows an open format called AGENTS.md, \"used by over 60k open-source projects\" according to [its site](https://agents.md/?utm_source=devto&utm_medium=referral&utm_campaign=agent-ready-projects). Recent versions of Claude Code read it when a project has no CLAUDE.md of its own, and when it has one, a single import line pulls it in ([Claude Code docs](https://code.claude.com/docs/en/memory?utm_source=devto&utm_medium=referral&utm_campaign=agent-ready-projects)).\n\nOne front door saves every agent the search. My own second brain's Claude file holds exactly one line, and so does the one in Spec Harness, my open-source kit for code projects:\n\n```\n@AGENTS.md\n```\n\nAnything only Claude needs goes below the import. Say the only Claude habit you want is a planning step before changes to the payments folder. The whole file then reads:\n\n```\n@AGENTS.md\n\nBefore you change anything in the payments folder, show me a plan first.\n```\n\nLooking after it takes almost no work. Every rule that all agents need goes in the main file, and the Claude file gains a line only when a habit applies to Claude alone. When it grows past a few lines, move the extra lines into the main file. Keep the main file short. The same Claude Code docs say \"target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.\"\n\nTwo prices in two files is one price too many. The agent picks one, and you find out which in review. Name the one home, and tell the agent to check any copy against it.\n\n```\nFacts live in docs/facts.md. If you find a value anywhere else, check it against that file and tell me.\n```\n\nSome parts of a project fail without noise: the payment webhook, the database schema, anything that emails your users. Put a written fence around them, and a rule that says stop and ask. The line below does three jobs. The two names are the places where a mistake costs the most and shows up latest. \"Without my yes\" makes you the gate. \"Stop and show me the plan\" makes the agent list what it would change before it touches anything, so you review a plan and skip the diff afterwards.\n\n```\nNever change the payments folder or the database schema without my yes. Stop and show me the plan.\n```\n\nSwap in your own folders, such as auth, migrations or billing settings, and keep the list short, because a long list gets skimmed. Say the agent is fixing a bug and finds a payment helper that looks wrong. With the fence it stops and asks you first.\n\nThe agents.md site says how a second file works: \"The closest AGENTS.md to the edited file wins.\" So the file inside the payments folder can be stricter than the main one. One catch for Claude Code. The docs say \"By default, Claude reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it\", and this project has one. I tested it: with a CLAUDE.md at the root, Claude read a file in the payments folder and never loaded that folder's AGENTS.md. The fix is a one-line CLAUDE.md in the payments folder, and then both files load when Claude works there.\n\nThe payments folder holds two files. The first is the stricter rule:\n\n```\npayments/AGENTS.md\nNever change a webhook handler or a price ID. Show me the plan and wait for my yes.\n```\n\nThe second is the one-line import that makes Claude Code load it:\n\n```\npayments/CLAUDE.md\n@AGENTS.md\n```\n\nAn agent that guesses the test command runs the wrong one, or none, and reports done. Write the exact commands and what done looks like.\n\n```\nDone means: the tests pass and the app starts. Run both commands from the Commands section and paste their last lines.\n```\n\nThe next session starts blind again. One short file with the work in progress and the open questions lets the next agent pick up where this one stopped.\n\n```\nBefore you stop, update docs/now.md: what changed, what is left, what is waiting for me.\n```\n\nCorrecting the agent in chat fixes one session. When the same mistake comes back, write the fix into the file, with the date and the reason. My own global file has one from 3 August: read the project's own rules before you touch it. It started as one line, added after a real violation.\n\n```\nWhen a mistake repeats, add one dated rule to this file with the reason. Leave one-off mistakes out.\n```\n\nSpec Harness is what I use for coding with agents. It is spec-driven development wrapped in a harness: the spec comes first, and every step after it leaves a record the next session can read. It is free and open source.\n\nSix roles do the core work, one job each. The repo holds more agent files for other jobs. The split exists because the agent that writes the code should never be the one that checks it.\n\nThe researcher and planner prepare the work, the implementer and tester build and run it, and the reviewer checks style and scope. The verifier matters most. It is a separate agent that did not write the code, it checks the result against the goal, and its only answer is PASS or FAIL. A FAIL sends the work back to the implementer.\n\nThe files from this article sit around those roles. Rules only tighten, and a failure does not become policy automatically: when something breaks, the cause is logged first.\n\nThe four files cover the first four of the six answers: context, owner, effects and evidence. Continuity and learning need a place to write too, and a growing project needs a map of where everything lives. Spec Harness installs all of that in a code project, using other file names for the same jobs.\n\nInstall it and you get the same front door and a rules index that says where each kind of fact lives. It also adds a memory folder whose active file every session reads, and a learning log for misses. Its [own AGENTS.md](https://github.com/chohra-med/spec-harness-oss/blob/main/AGENTS.md?utm_source=devto&utm_medium=referral&utm_campaign=agent-ready-projects) states that it adds no dependency and never edits your application code during install. Every rule stays marked PENDING, which means not yet written from your own code and checked, until that work is done.\n\n```\nyour-project/\n├── CLAUDE.md               @AGENTS.md, then the startup order\n├── AGENTS.md               hard limits, and what done means\n├── RULES.md                rules for one folder; the nearest one wins\n├── ai_rules/\n│   ├── globalRules.md      where each kind of fact lives\n│   ├── context_map.md      the real modules, mapped after install\n│   └── rules/frequent_rules.md\n├── .memory/\n│   ├── 40-active.md        what is in flight, read every session\n│   ├── 50-progress.md\n│   └── 60-decisions.md     one home for each decision\n└── learning/NOTES.md       misses, before they become rules\n```\n\nOne line from the main file it installs is worth copying into any project, harness or not:\n\nNever invent an import, function, type, or component. Confirm it exists (grep/Read/index) before you call it.\n\nSay you ask for a button that lets users register with Gmail. You first write the goal as checks that are either true or false: tapping the button opens Google sign-in, a new user gets an account, an existing user is signed in, and a cancelled sign-in changes nothing.\n\nThe researcher finds where sign-up lives and sees that the auth folder is fenced, so the work will stop and ask. The planner splits the goal into tasks: add the button, connect Google sign-in, create or find the user, handle a cancelled sign-in.\n\nThe implementer writes the button with its tests, one task at a time, and the tester runs the suite.\n\nThe verifier goes through the four checks. If a cancelled sign-in still creates an account, that check fails and the work returns to the implementer.\n\nThe reviewer checks that the change touches sign-up and nothing else, and the cause of any miss goes into the learning log. A failure does not become policy automatically.\n\nThe fair objection: your README already explains the project. It does, for a person who can ask a colleague when a step is unclear. An agent acts on what it reads first. So its file is shorter and gives orders: run this, never touch that, stop here. Keep both, and let the agent file point to the README for the long story.\n\nA hook is a small script the tool runs before or after an action. The [Claude Code docs](https://code.claude.com/docs/en/memory?utm_source=devto&utm_medium=referral&utm_campaign=agent-ready-projects) put the limit plainly: \"To block an action regardless of what Claude decides, use a PreToolUse hook.\" So write the rule in the file, and if breaking it would cost you money or data, add a hook as well.\n\nA file asks nicely. A hook just says no.\n\nPick the project you open most often with an agent, then:\n\nThe free [Second Brain Starter](https://github.com/chohra-med/second-brain-starter?utm_source=devto&utm_medium=referral&utm_campaign=agent-ready-projects) gives you the main file, the Claude import and a facts file for each project. [Builder AI OS](https://choumed.gumroad.com/l/builder-ai-os?utm_source=devto&utm_medium=referral&utm_campaign=agent-ready-projects) is the paid layer for later, once one project runs well.\n\nStart of the series: [How to scale a Second Brain into a Company Brain](https://codemeetai.substack.com/p/how-to-scale-a-second-brain-into?utm_source=devto&utm_medium=referral&utm_campaign=agent-ready-projects).\n\nThe full series lives in [Code Meet AI](https://codemeetai.substack.com/p/how-to-stop-your-coding-agent-guessing?utm_source=devto&utm_medium=referral&utm_campaign=agent-ready-projects), my newsletter. The next piece goes there first.", "url": "https://wpnews.pro/news/why-does-your-ai-keep-guessing-about-your-project", "canonical_source": "https://dev.to/malik_chohra/why-does-your-ai-keep-guessing-about-your-project-321b", "published_at": "2026-11-11 18:07:42+00:00", "updated_at": "2026-11-11 18:23:00.203842+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "agent-protocols"], "entities": ["Claude Code", "Codex", "Cursor", "Supabase", "Stripe", "Jake Van Clief", "David McDermott"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/why-does-your-ai-keep-guessing-about-your-project", "markdown": "https://wpnews.pro/news/why-does-your-ai-keep-guessing-about-your-project.md", "text": "https://wpnews.pro/news/why-does-your-ai-keep-guessing-about-your-project.txt", "jsonld": "https://wpnews.pro/news/why-does-your-ai-keep-guessing-about-your-project.jsonld"}}