Skip to content

Knowledge base

Agent instructions (CLAUDE.md, AGENTS.md)

What to put in CLAUDE.md or AGENTS.md and who should own it, for teams setting up the file their coding agents read every session.

Written by

Updated:

Glossary 33

Agent instructions are the Markdown files at the root of a repository, and sometimes in its subfolders, that a coding agent loads at the start of every session. They hold what the agent would otherwise guess: how to build and test, the conventions, the commands that are off limits. Claude Code reads CLAUDE.md. AGENTS.md is an open format read by many coding agents, and since version 2.1.277 Claude Code reads it too in a project with no CLAUDE.md.

What belongs in the file?

Only what applies to every task, because the file is in the context window of every session. A long instruction file costs context on each run and dilutes the rules that matter. Task-specific knowledge belongs in a skill or a priming command that loads when needed. See Context Engineering.

Who owns it?

The instructions are a team decision, so they need one owner and one file. A team where each developer uses a different agent tends to keep one file per tool, edited by whoever uses that tool. The files drift, and two agents then build the same feature two different ways. Merge them into one AGENTS.md, name its owner, and send changes through the same review and checks as code.

Resources

Documentation