How to Make Your Codebase Work for AI Coding Agents (Without Better Prompts)

A developer community consensus has emerged that AI coding agent effectiveness depends more on repository architecture than prompt engineering. Teams are adopting a standardized `AGENTS.md` file at the repo root—a plain-text convention readable by Copilot, Claude Code, Cursor, and Codex—that documents exact commands, directory structure, conventions, and protected files in under 15 minutes of setup time. The approach shifts the burden from re-explaining project context in every session to making the codebase itself serve as a complete interface for agent execution.

Your agent wrote valid code. It still missed the point. Wrong package manager. Tests run with a flag your pipeline never uses. Business logic landed in a route handler because the model found a similar file three folders away. You pasted more context, tightened the prompt, ran again. Same failure on the next task. That is not a model problem. It is a repo problem. A wave of posts in early 2026 Medeiros, Fabisevich, Marmelab, Sourcegraph, Vstorm, and others converged on the same idea: agent productivity is architectural . Tools matter. Structure and feedback loops matter more. This post is a practical distillation. No tool worship. What to add to your repository so Copilot, Claude Code, Cursor, Codex, or whatever you use next month can ship without you re-explaining the project every session. Humans absorb tribal knowledge. Half-documented setup scripts. "Ask Priya about auth." Agents do not ask Priya. They pattern-match on what is in the tree and what they can grep. Hélio Medeiros https://blog.heliomedeiros.com/posts/2025-08-07-agent-friendly-codebase/ frames the repository as an interface. InfoWorld's "Coding for agents" https://www.infoworld.com/article/4142019/coding-for-agents.html goes further: context is infrastructure. Test commands, boundaries, and "do not touch" paths are part of how work runs when the worker is an agent. The litmus test use this before you blame the model : If the agent cannot finish using only committed files, you are still carrying the load. The agent is typing. That test takes ten minutes. It tells you exactly where to invest next. Teams that retrofit for agents report the same wins: Vstorm's guide https://oss.vstorm.co/blog/agents-md-ai-friendly-codebase/ and community writeups on AGENTS.md https://cobusgreyling.substack.com/p/what-is-agentsmd put the setup time at roughly 15 minutes for a first version. The payback shows up in the first week of review loops you do not have to run. You are not building for robots. You are writing down what a good senior engineer would need on day one. Agents just force the issue because they never attend onboarding. AGENTS.md at the repo root A year ago every tool wanted its own rules file. .cursorrules , CLAUDE.md , .github/copilot-instructions.md , tool-specific Gemini configs. Same conventions copied four times, drifting within weeks. AGENTS.md is the convention that stuck: one Markdown file at the root that multiple agents read. Plain text. No JSON schema. Works across Copilot, Codex, Claude Code, Cursor, and others see Keep tool-specific extras if you want CLAUDE.md for Claude-only workflow . AGENTS.md should stand alone. If an agent reads one file, it should still know how to work here. Copy this skeleton and fill in the blanks: AGENTS.md Project overview Name . One line: what it does . Stack: language, framework, database, package manager . Commands Install exact command Dev exact command Test exact command Lint / format exact command Structure key directories only, 10-15 lines max - src/api/ : HTTP handlers - src/domain/ : business rules - ... Conventions - Where new endpoints go - How you name tests - Patterns agents get wrong: e.g. flush in repo, not commit Do not modify - generated migrations - lockfiles - .env - auto-generated docs More context - docs/architecture.md - CONTRIBUTING.md The sections that prevent the most damage: | Section | What it stops | |---|---| | Commands | pip vs uv , npm vs pnpm , wrong test runner | | Structure | Logic dropped in main.ts or the wrong package | | Conventions | Architecturally "valid" code that violates your patterns | | Do not modify | Ruined migrations, committed secrets, reformatted lockfiles | Do not paste your entire README. OpenAI's harness engineering notes https://www.infoworld.com/article/4142019/coding-for-agents.html summarized widely in 2026 argue that one giant agent manual goes stale. Use AGENTS.md as a map , not an encyclopedia. llms.txt if agents need a wider map Joe Fabisevich's Recap 2.0 writeup https://build.ms/2026/3/11/small-steps-for-agent-friendly-codebases/ describes a small llms.txt that points agents at the right docs without dumping the whole repo into context. Use it for pointers, not rules: llms.txt /docs/architecture.md /docs/api.md /CONTRIBUTING.md Put operational rules in AGENTS.md . Put "where to look next" in llms.txt or public/llms.txt for web projects. Medeiros recommends stable entrypoints, often wrapped in Make: make bootstrap make test make lint make run Your implementation can be npm scripts, pnpm, mise, or a Taskfile. The agent does not care about the wrapper. It cares that one string always works on a clean clone and that CI runs the same string . Bad state: local npm test , CI pnpm test --filter=api . The agent optimizes for whatever just ran in the terminal. You merge green locally and red in the pipeline. Good state: "scripts": { "test": "vitest run", "lint": "eslint ." } …and the workflow file calls pnpm test and pnpm lint , not a different incantation. When verification is slow or flaky, the agent becomes a diff machine and you become the test runner. Fast unit tests on pure domain code where you have any shorten the loop more than swapping to a frontier model. You do not need hexagonal architecture on every side project. You do need obvious boundaries . Medeiros and others recommend ports-and-adapters style layouts because they make violations visible: domain code cannot import the database driver, so the build fails when an agent takes a shortcut. Transferable pattern for any stack: core/ , lib/domain/ . main , app/ , composition root .For a feature-folder Next.js app, that might mean: routes in app/ , product logic in features/ / , shared MDX paths documented in AGENTS.md so "add a blog post" does not create data/blog/ and features/blog/data/posts/ on the same day. Add a one-paragraph README in folders agents confuse often src/billing/ , packages/api/ . Agents frequently read folder READMEs when they list a directory. Marmelab's agent experience post https://marmelab.com/blog/2026/01/21/agent-experience.html is long. The habit worth stealing is simple: Every time an agent does something stupid, ask if the repository should have prevented it. | Agent mistake | Repo fix | |---|---| | Wrong test command | Add to AGENTS.md Commands | | Reinvented helper | Add convention: search before creating | | Same formatting nit on every PR | Pre-commit hook or agent hook | | Broke auth on a "small" change | Document blast radius; list related paths in AGENTS.md | Tooling and MCP servers come last in their ordering. Most teams still fail on missing context, not missing plugins. Sourcegraph's agentic coding guide https://sourcegraph.com/blog/agentic-coding names a pattern teams recognize: the agent finishes the visible 80%. Tests pass in the files it touched. Days later, CI fails elsewhere because middleware, DTOs, audit logs, or a sibling service still expect the old contract. That is incomplete context, not stupidity. On a single app, blast radius is smaller. Still run this before you call a task done: grep for every symbol the agent renamed or exported. Open files it never touched. If something depends on the old shape, the task is not done. On large or multi-repo codebases, you need deterministic cross-repo search and explicit scoping before merge. The fix scales up; the diagnosis stays the same. Do this on the repo you use agents on most: AGENTS.md using the skeleton above 15 minutes . AGENTS.md for anything the agent had to be told in chat.Start on a small project if you are learning the pattern. Fabisevich's advice https://build.ms/2026/3/11/small-steps-for-agent-friendly-codebases/ is to practice on something bounded, then port the habits to the big codebase. Reading about agent-friendly repos does nothing until a file lands in git. The litmus test is the scoreboard. Primary sources behind this post: