AGENTS.md as onboarding for a teammate who forgets everything

Treat AGENTS.md as onboarding for coding agents. Keep commands, conventions and project decisions current so each new session starts with useful context.

By Subash Adhikari · 10 November 2026 · 4 min read

• AI
• Leadership

Share on XCopy link

Toward the end of How I Run a Team of Bots, I compared this setup to a small team that never sleeps and forgets everything you didn't write down. That comparison still holds for coding agents, especially at the start of a fresh session that may not carry yesterday's conversation.

Treat that session like a new hire on their first day. Tools can hold memory, and agents can ask questions. Even so, a lot of useful context never makes it into either of those places unless someone writes it down.

A folder called legacy might still be in use. A project might have a fast test command that isn't obvious from the package scripts. A fresh session needs somewhere to find those details.

An AGENTS.md (or a CLAUDE.md, or a rules file, depending on the tool) is one way to leave that context. It only helps if it describes the project as it is now.

The file is the onboarding#

When a human joins the team, we put real effort into onboarding. Someone walks them through the architecture, explains the weird bits, and tells them which commands to run and which ones to avoid. Over the first few weeks they pick up the unwritten rules by working alongside people.

A fresh agent session doesn't have those weeks of working alongside the team. It has the code, the instructions, whatever memory the tools keep, and whatever it can ask or infer.

So when an agent does something that makes you groan, like adding a new date library when you already have one, or writing tests in a style nobody uses anymore, the first question I ask isn't "why did the model miss that?" It's "did we ever tell it?"

Often we didn't.

A stale file worries me more than a missing one#

A missing file leaves the agent to guess. A stale one can send it in the wrong direction with confidence.

Say the file still tells people to run npm test, but the project moved to pnpm months ago. Or it describes a folder structure from before a refactor. Or it points at a pattern the team has since decided to leave behind.

A human or an agent might catch the mismatch. They might also waste time following instructions that look authoritative. Outdated guidance doesn't just fail to help. It can push the work somewhere you no longer want it to go.

What actually belongs in it#

I try to keep the file short and boring.

Put the exact commands to build, test and lint, including the fast way to run a single test. That alone saves a lot of wasted cycles. Add a few lines on where things live, enough that the agent looks in the right place first, not a full map of the repo.

Write down the decisions that aren't obvious from the code. For example, a project might need a rule saying money values are stored as integers in cents, or a note to stop adding usages of a library being phased out. A new hire might otherwise only learn those rules by getting them wrong in review.

Say what not to touch, whether that's generated files, vendored code, or migrations that have already run in production. And say what done looks like. That might mean tests passing, type checks passing, and no new warnings. If you expect a certain kind of PR description, say so.

I leave out formatting rules the linter already enforces, architecture that doesn't exist yet, and explanations the agent can get by reading a single file.

Treat it like code, not like a wiki page#

The biggest shift for me was treating this file as part of the codebase rather than documentation that sits beside it.

Update it in the same PR as the change. If you switch package managers, the instructions change in the same commit, the same way you'd update a test. When someone edits it, review it with the same attention as any other change, because it shapes the context for later sessions.

When an agent makes the same mistake twice, don't just correct the code. Write down the underlying rule, and check that the file doesn't already say something that contradicts it. That reduces avoidable repetition. It doesn't guarantee the next session will get it right.

The file doesn't replace tests, review, or judgement. Instructions can be missed or misunderstood, even when they're up to date.

And every so often, read the file top to bottom and delete what's no longer true. A shorter file is easier to check and keep current.

It's not really about agents#

Almost everything that makes a good AGENTS.md also makes good onboarding for people. Clear commands. Honest notes about the messy parts. The decisions and the reasons behind them.

Agents can ask questions too, but repeating the same onboarding each session is work. Writing the useful context down saves that repetition and gives the next person who joins somewhere to start.

If an agent keeps getting the same thing wrong, I check the instructions as well as the output. They may still describe the codebase as it used to be.

Thanks for reading. You can also follow along on X or with RSS.