A Codebase Documented for AI Agents Onboards the Next Engineer in Days

"Claude Code is enough for us." We hear some version of that in sales conversations, from founders whose teams ship faster than they did a year ago.

When the team is two or three people with a coding agent and a product with no production load yet, we agree. There is often nowhere useful to put another engineer, and we say so.

For a company of 11 to 50 people with a live product, we ask one more question. What happens if one of you is out for three weeks?

In July we wrote about how the engineers who work with us use AI day to day. That post describes how we work. This one is about what a client gets out of it. A codebase with a current AGENTS.md, the file a coding agent reads before it starts work, is also one a new person can pick up quickly, and that changes what it costs when someone leaves.

Since 2019 we have joined product teams partway through, and at this size the system usually lives in one or two heads. One senior knows why a nightly job runs in two steps and which old migration must never be rerun. Nobody wrote it down, because the person who knows it never needed to read it.

Knowledge transfer when an engineer leaves used to mean a handover call and a wiki page that was out of date before the call ended. We have seen capable engineers spend most of their first month after that asking how things work and where to find them, because the only index of the system was the person who had just left.

During that month the roadmap slows down, and the senior who stayed spends their days answering questions. The usual name for this is the bus factor. In a team of 20 it is often one, and everyone in the room knows who it is.

AGENTS.md is an open format for instructions to coding agents. OpenAI released it in August 2025, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation, which says more than 60,000 open source projects use it. The agents.md site calls it "a README for agents".

Since version 2.1.277, released on 18 September 2026, Claude Code reads a project's AGENTS.md when the project has no CLAUDE.md. If both files exist, Claude Code reads CLAUDE.md by default, and a CLAUDE.md can pull the other file in with one line, @AGENTS.md. A team that uses several coding tools can now keep one instruction file, and Claude Code reads it too.

We write that file so a person can use it as well. An agent needs to know how to build the project, how to run the tests, where things live and what to leave alone. A new engineer needs the same things in their first week, and they rarely find them on one page. The agent gives a team a reason to write down what nobody had time to write for people, and developer onboarding is where that pays off.

One senior engineer in our pool described his setup to us this summer. He keeps a project instruction file (a CLAUDE.md in his case, and an AGENTS.md does the same job) that explains how the project works and how the folders are laid out, so the model does not spend tokens searching for things he could have told it. He uses codebase indexing, and he points the agent at current library documentation through the Context7 MCP server. The first work he hands the model is unit and end-to-end tests, because it is good at edge cases. That is where we use AI in general, and a senior owns the architecture and the final call.

The sections we recommend are close to what the agents.md site itself suggests.

A short project overview. What the product does, which services it talks to, and where the code for each part lives.

Build and test commands, exactly as you type them, including the seeded database or environment variable the tests need.

Code conventions, such as where business logic goes, how things are named and what a pull request needs before review.

A list of what not to touch, each item with what to do instead. Payments: no change in behavior without a feature flag and a test that covers the old path. Migrations: never edit one that has already run; add a new migration and flag it in the PR. Authorization: any change to who can see what goes to the senior who owns that code, with the reasoning written in the PR description.

How the code is indexed, and where an agent or a new engineer should start reading.

Pairing each prohibition with an alternative matters. Augment Code measured this on its own codebase and found that documentation made only of warnings did worse than documentation that offered an alternative for each one. Files with 15 or more "don'ts" and no "dos" made the agent explore too much, stay cautious and do less work.

In Augment's tests, the worst AGENTS.md files made the agent's output worse than having no file at all. We see two ways to end up there.

The first is one giant file. In the same tests, files of 100 to 150 lines performed best, the gains started reversing once the main file grew past that, and huge files at the repository root did worse than module-level files. Anthropic's advice for CLAUDE.md is similar: target under 200 lines, because longer files consume more context and the model follows them less consistently.

The second is a stale file. A file that describes last year's folder structure sends the agent and the new engineer to the wrong place, and both of them trust it. Anthropic's documentation tells teams to review these files periodically and remove outdated or conflicting instructions, and agents.md calls the file living documentation.

Our rule is that the file is updated in the same pull request as the code it describes. If a PR moves a module, renames a command or changes what is safe to touch, the reviewer checks the file the same way they check the tests.

The file also answers a point our CTO made in our CEO and CTO post. The tool does what it was asked to do, and nobody asks for tests or structure unless someone writes that down. An instruction file is one way a senior does that, and writing it still takes someone who knows when the output is wrong.

"We have our own team" is the other thing we hear, and it is usually true. The risk is that two seniors hold all of the system between them.

Continuity is still the best outcome. Venn, a Norwegian social app, has worked with us since November 2021. Their founder and CEO, Jesper Algaard, is quoted on our case page saying that New Wave Devs "has supplied us with a senior iOS developer since then."

People still get ill or leave, and a contract with us does not lock you in when they do. You interview the engineer before you sign. The engagement runs month to month, and the rate is fixed for the length of the contract. The engineer is contracted and paid through us for the length of the engagement. If the engineer is not the right fit within the first 7 days, we replace them at no cost. Billing and other common questions are answered on our questions and answers page.

Those terms depend on the codebase. Month to month only helps if the next engineer, whether we introduce them or you hire them yourself, can pick the work up quickly. With a current instruction file, their first week goes into reading one page, running the commands on it and asking about the list of what not to touch. That is how the next engineer gets up to speed in days instead of a month. We have not measured this, so we will not put a number on it.

Before you decide whether you need anyone from outside, put these to your own engineers.

If one of your seniors were out for three weeks starting Monday, who would answer the questions only they can answer today?

Is there a file in the repository that tells a newcomer how to build the project and run the tests, and has it changed since the code last did?

Which part of the system would you not hand to an agent? Whatever the answer is, that is the first section of your AGENTS.md, and it is the part of your product that needs a senior most.

When someone gets that part wrong, does the file get updated in the same pull request that corrects it?

What did your last new engineer spend their first month looking for?

If every answer comes quickly, you may not need us. If one of them started an argument in the room, that is a good place to begin a first call.

We place senior engineers inside product teams, working on your codebase and inside your review process. 70,000+ hours of work, clients in 6 countries, 50+ specialists.

You interview the engineer before you sign, the engagement runs month to month with the rate fixed for the length of the contract, and if the fit is wrong in the first 7 days we replace the engineer at no cost.

We work mainly in Ruby on Rails, React, Next.js, JavaScript, Java, Golang, iOS, Flutter and Rust, and we also place engineers who build AI features into products.

Talk to us about a senior engineer