An AGENTS.md is a plain Markdown file you keep in your repo that tells an agent how your project works: build commands, test commands, conventions, and the gotchas you would otherwise repeat in every chat. The agent loads it into context at the start of a session, so the knowledge travels with the code instead of living in your head.
What goes in one
Keep it to what a competent new contributor would need on day one:
# Project conventions
- Build: `npm run build`
- Test: `npm test` (run before every commit)
- Never edit files in `src/generated/` by hand.
- Use the existing `logger`, not `console.log`.That is it. A few lines that steer the agent away from the mistakes it would otherwise make.
Why it beats the system prompt
The system prompt is set by the tool and is the same everywhere. An AGENTS.md is yours, it lives next to the code, and it is version controlled, so a convention you add today keeps working next month. It is the simplest memory system there is: durable project memory in git.
Resist the urge to dump everything in. A bloated file spends context and buries the rules that matter. Put the essentials here and use progressive disclosure for the rest, pointing at deeper docs the agent can open when it needs them.
Related terms
Memory system
A memory system is an external store the harness uses to persist facts across sessions and reload them into context. It is how a stateless model ends up behaving as if it remembers you and your project.
Read definition →System prompt
The system prompt is the standing instruction placed at the very start of the context that sets the model’s role, rules, and tone before the conversation begins. It shapes every reply without being part of the back-and-forth.
Read definition →Progressive disclosure
Progressive disclosure is revealing detail to the model only when it is needed, via pointers and on-demand loading, instead of putting everything into context up front. It saves window space and attention.
Read definition →