AGENTS.md and CLAUDE.md: Writing Instructions Coding Agents Follow

Every new colleague asks the same questions: how do I build this, how do I run the tests, where does the code for X live and what must I never touch? A coding agent needs the same answers, and it starts every session without remembering the last one. Instruction files solve this. AGENTS.md is a convention several tools read, and CLAUDE.md is the file Claude Code reads for project guidance. Tools differ in how they load and merge these files, so check each vendor's current documentation.

What belongs in the file

• Commands. How to install, build, lint and test, including how to run a single test.
• Structure. A short map of important folders and what lives there.
• Conventions. Naming, error handling, state management and style choices that are not obvious from the linter.
• Boundaries. Files and actions that need approval: migrations, generated code, secrets, dependency changes.
• Definition of done. What must pass before a change is ready for review.
• Gotchas. Known traps, such as a flaky test or a tricky build step.

What to leave out

Skip long essays about company values, anything the code already makes obvious and rules the tooling enforces automatically. Do not paste whole style guides. Agents have limited attention, and a bloated file buries the important rules. Never store secrets, tokens or personal data in these files, because they are committed and shared.

A compact template

1. Project in one paragraph. What the app does and who uses it.
2. Commands. Build, test, lint, run, with exact syntax.
3. Architecture. Three to six bullets on structure and patterns.
4. Rules. Short imperative sentences, such as "Add or update tests with every behavior change."
5. Do not. A short list of forbidden actions.
6. Review notes. What reviewers will look for.

Writing style that works

Be specific and imperative. "Use the repository pattern in src/data" beats "keep code clean". Prefer positive instructions with a reason, since a reason helps the agent generalize. Show one example of a good file rather than describing it at length. Where rules conflict, say which wins. Avoid emphasis tricks; if a rule truly matters, enforce it with a test, a linter rule or a required review rather than hoping a sentence in a file will always be obeyed.

Keeping it alive

• Treat the file as code: change it through pull requests.
• When an agent repeats a mistake, add one line that prevents it, and remove lines that no longer help.
• Review it quarterly or after major refactors.
• In a monorepo, place smaller files near the code they describe, if your tools support nested instruction files.

Signs your file needs work

• The agent keeps asking for commands that are already documented.
• Reviewers repeat the same comments on every agent-written pull request.
• The file contradicts the linter, the wiki or itself.
• Nobody remembers who last edited it.

Each sign points to a small fix: add the missing command, turn the repeated review comment into a rule, delete the contradiction and assign an owner.

One file or several?

If your team uses more than one agent, keep the shared guidance in one file and reference it from tool-specific files, so you do not maintain two versions that drift apart. This also helps when comparing tools; see Claude Code vs. Codex.

Instruction files are not a security boundary

A written rule can be ignored, forgotten or overridden by text the agent reads elsewhere. For anything that must never happen, such as touching production credentials, use technical controls: permissions, sandboxes, scoped tokens and required review. Our guide on MCP servers for coding agents covers related safeguards.

How apprat.io uses them

Our AI Code Engineers maintain instruction files in every agent-assisted project, so the agent starts each session with the same context a new human colleague would receive. The files raise the quality of the first draft, but they do not replace review: a person reads every change, tests on real devices and remains accountable. To learn this practice with your own team, ask about an agentic coding workshop or book a call for free.