Your Repo Is the Only Onboarding an Agent Gets
You give an agent a small, well-defined ticket. There's a failing test attached and clear steps to reproduce the bug, so this one should go well.
Instead it spends twenty tool calls working out how to run the test suite, builds on a helper you deprecated eight months ago, and opens a PR touching four files that had nothing to do with the bug.
The prompt wasn't the problem. Prompting is the layer everyone tunes, and I've written about that before. The layer underneath is what your repo handed the agent, and in that run it handed over nothing useful: no instructions to read, no fast way to check its own work, and no limit on what it could touch. Those three things decide most of what an agent does, and all three are committed to your codebase before you type a word.
The agent learns your conventions from whatever file it opens first
Every session starts cold. The agent has no memory of yesterday's work and no sense of the decisions that shaped the code it's about to edit, so it infers your conventions from whichever files it happens to read. That's how it ends up building on the pattern your team abandoned last spring, since the old pattern is still sitting in the repo and nothing marks it as retired.
A new hire hits the same wall and gets past it by asking someone. An agent doesn't ask, so it picks the most plausible answer and keeps moving.
Writing that context down is what closes the gap, and there's now a common place to put it. AGENTS.md is a plain markdown file at the repo root, adopted by more than 60,000 open-source projects and stewarded by the Agentic AI Foundation under the Linux Foundation. Nested files behave like .gitignore, where the file closest to the code being edited takes precedence, which is why the main OpenAI repo ships 88 of them.
Which file to write if your team uses different tools
Every tool used to ship its own filename, which is why repos accumulate .cursorrules, copilot-instructions.md, and CLAUDE.md all saying the same thing. AGENTS.md is the attempt to collapse that into one file, and about twenty tools read it directly. Claude Code is the exception people hit most: it reads CLAUDE.md, so add a one-line CLAUDE.md containing @AGENTS.md to point it at the shared file.
The Claude Code docs cover the setup.
A few things worth putting in yours:
- The exact install, run, and test commands, flags included. If your project uses pnpm and the agent assumes npm, everything downstream of that guess is wrong.
- Domain vocabulary, so the agent knows what your codebase means by an account and how that differs from an organization or a workspace.
- Generated directories and files that nobody should be hand-editing.
- Anywhere you diverge from the common pattern on purpose, along with the reason. Models reproduce whatever is statistically normal, so a deliberate exception either gets written down or gets quietly refactored away.
The risk is bloat, since every line competes for context with the work itself and the file drifts out of date the way documentation always has. A short file your team keeps current will do more for you than a thorough one describing the repo as it stood in March.
What bloat means here
The file loads at the start of every session, so every line spends tokens on tasks it has nothing to do with. Anthropic suggests keeping it under 200 lines and notes that longer files reduce how reliably instructions get followed, which means adding a rule can weaken the ones already there. Anything you need occasionally belongs in a
path-scoped rule that loads only when the agent touches matching files.
Name the command that proves the work is finished
A few weeks ago I wrote about pointing agents at work that has a check the agent can run on its own. That issue treated the supply of those tasks as fixed, as though your board either contains them or it doesn't. How many of your tasks come with a runnable check is mostly a property of the repo, so it's a number you can raise.
The mechanism is plain enough that the AGENTS.md spec spells it out. List your test commands and the agent will try to run them and fix what fails before it calls the work done, and leave them out and it falls back to reading its own diff and deciding it looks correct.
What counts as a check
Any command that comes back pass or fail without a person interpreting the output. A test suite, a typecheck, a linter, a build, or a script comparing output to a known-good file. Naming, design fit, and whether a screen looks right all need your judgment, so the agent has no way to tell whether it's getting closer. Most boards hold more of the second kind than people expect.
Speed matters more than coverage here, because a 40-minute suite gives an agent nothing to iterate against. It runs that suite once at the end, if at all, and spends the rest of the session guessing. A subset that finishes in seconds, alongside a typecheck and a linter, gives it something to push against on every turn.
Getting the project running at all belongs in the same bucket. When reaching a working local environment takes credentials from a teammate and three steps that live in someone's head, the agent can't verify anything it writes, and neither can the person who joined last week.
Without a check it can run, finished means the agent's own opinion of its own work, and you end up serving as the test suite while every task moves at the speed you can read a diff.
|
|
Where can AI save you time?
My friends at Big Creek Growth put together a quick survey to spot the repetitive work you can hand off to automation.
|
|
Your instructions are a suggestion
In July 2025, Jason Lemkin was nine days into building a product by directing Replit's agent in plain English. He had declared a code freeze and said so in the tool more than once, and the agent ran destructive commands against the production database anyway, wiping live records covering roughly 1,200 executives before telling him that rollback was impossible, which turned out to be wrong.
The useful part is the explanation it gave afterward. It said it panicked when it saw what looked like an empty database and judged that acting was safe. The freeze was sitting in its context the entire time, so it wasn't forgotten so much as outweighed by a more immediate read of the situation.
That's the pattern worth carrying into your own work. An instruction lives in the context window next to everything else the agent has seen, and when the two disagree, the instruction doesn't automatically win. Constraints in the execution path never enter that comparison at all, which is why Replit's own response was automatic separation between development and production databases rather than clearer wording or a wait for a smarter model.
Instructions versus enforcement
Anthropic's docs say CLAUDE.md is treated as context rather than enforced configuration, and that contradictory instructions may get resolved arbitrarily. Blocking something regardless of what the model decides takes a
hook, a permission setting, or a CI gate. Writing the instruction is cheap and worth doing, and it isn't the same thing as a boundary.
Worth answering about your own setup:
- What credentials the agent inherits from your shell, and how far those credentials reach.
- Whether it can run a migration, drop a table, or push to a shared branch without a person in between.
- Whether it's working in a container you can throw away, or on the laptop holding your SSH keys and a live production connection.
Most people who use agents seriously turn the approval prompts off, since approving every command defeats the point of handing over the work. That's a defensible trade as long as the boundary sits somewhere other than a dialog box.
Your codebase carries the other half of this. A change contained behind a narrow interface costs you a branch when it goes wrong, while a change that reaches through six modules costs you a weekend plus a revert that breaks something in a seventh.
A good prompt is personal, so it lives in your session history and leaves when you do.
An AGENTS.md file, a check that runs in seconds, and an environment scoped to the work are all committed, which means everyone who touches the repo afterward inherits them. That includes the engineer who has never used an agent and can't explain why hers behaves better here than it did at her last job.
The test of whether a codebase is ready for this is close to the test it has always been, which is whether someone new could ship something useful on their first day. What's changed is that your agent starts every session on its first day and never gets past it.