How do you write instructions for AI coding agents?

What are AGENTS.md and CLAUDE.md?

Both are plain Markdown files that a coding agent loads as standing instructions for a project. AGENTS.md is an open format read by many coding agents, including OpenAI's Codex; it is described at agents.md. CLAUDE.md is the file Claude Code reads; it can live in the project, in a subfolder for instructions that only apply there, or in your home folder for rules that apply everywhere. Anthropic documents how Claude Code loads it in its memory guide.

The content is the same kind of thing either way, so many teams keep one file and point the other at it.

What should go in the file?

• How to build, test and run. The exact commands, so the agent can check its own work before it says it's done.
• How changes ship. For example: branch from main, open a pull request, let the automated checks pass, never push to main.
• Rules the code can't show. Naming, where secrets live, which files are generated and must not be edited by hand.
• Who decides what. The actions that need a person's yes, such as spending money, deleting data or changing anything customers see.
• How to report back. What changed, the pull request, proof it works, and anything that needs a person.

What should stay out of it?

Anything the agent can read from the code itself, long background essays, and anything secret. Keys and passwords belong in a secrets manager, never in a file the agent reads and might repeat. Leave out instructions that only matter for one task, too; put those in the request for that task instead.

Keep it short. Every line is read on every run, and a file full of rarely relevant detail buries the few rules that matter. If a rule keeps being broken, make it clearer or move it higher rather than adding more words around it.

How does North Bay Ventures use instructions like these?

The studio's agents work under written rules that read much like a good instructions file. Every change goes through a pull request with automated checks. Only Jon approves money, legal terms, DNS, deletions and launches, and an approval passed along by another agent counts only if it quotes his words. Every report says what changed, links the pull request and shows proof that it's live. Read how the studio uses agents and how we build companies for the details.

How do you give many agents the same instructions?

Commit the file to the repository, so every agent that checks out the code reads the same rules. When agents run on their own machines, put the files in the image they start from. In a Sandboxer sandbox, coding agents read their usual config files, such as CLAUDE.md, AGENTS.md, MCP server configs and settings, so you can bake them into a named snapshot and start every sandbox from it. For running several agents side by side, see running many coding agents in parallel.