AGENTS.md and CLAUDE.md Explained: Instruction Files for Coding Agents

Every coding agent starts a session knowing nothing about your project. Instruction files fix that: a Markdown file in the repository that the agent reads automatically, containing what a new team member would need on day one. Two names dominate in 2026: AGENTS.md, an open convention used across many tools, and CLAUDE.md, used by Anthropic's Claude Code. This guide explains both and how to manage them together.

What an instruction file does

An instruction file is loaded into the agent's context when it works in your repository. It does not change the model; it changes what the model knows about your project. Done well, it removes the most common failure modes: using the wrong package manager, running the wrong test command, ignoring house conventions, or editing files that should never be touched.

Think of it as the README for agents. A README explains the project to humans browsing it; an instruction file tells an agent how to work on it.

AGENTS.md vs. CLAUDE.md at a glance

Other tools have their own variants, such as GitHub Copilot's repository custom instructions, Cursor's project rules and Gemini CLI's GEMINI.md. Several of them can also read AGENTS.md, which is why many teams treat it as the shared base.

What to put in the file

A practical template, in priority order:

1. Project summary: one or two sentences on what the software does and its main stack.
2. Setup and commands: install, build, run, test (all and single), lint, type-check, format.
3. Repository map: the five to ten directories that matter and what lives in each.
4. Conventions: only those that differ from common practice or that agents frequently get wrong.
5. Boundaries: generated code, vendored libraries, migrations, infrastructure – what not to edit, or only with a specific process.
6. Definition of done: the checks that must pass before a task is considered finished.
7. Pull request expectations: commit message style, how to describe changes, what to include for reviewers.

Example of a compact section:

Testing
Run all tests: pnpm test. Run one file: pnpm test path/to/file.test.ts.
Every bug fix needs a test that fails before the fix.
Do not mock the database layer in integration tests.

Keeping one source of truth

If your team uses several agents, duplicated instruction files drift apart within weeks. Three workable patterns:

• Import: keep everything shared in AGENTS.md and have CLAUDE.md import it with an @AGENTS.md line, followed by Claude-specific notes such as preferred subagents or hook behavior.
• Symlink: make CLAUDE.md a symbolic link to AGENTS.md. Simple, but leaves no room for tool-specific additions and can cause trouble on some Windows setups.
• Generate: maintain one source file and generate tool-specific variants in a pre-commit hook. Only worth it for large organizations with many repositories.

Whichever you choose, document it at the top of the file so humans do not edit the wrong copy.

Instruction files in monorepos

Large repositories benefit from layering. Keep the root file short and general: tooling, shared conventions, how to run checks across the whole repository. Put package-specific details – framework quirks, test commands, owners – in nested files inside each package. This keeps context relevant: an agent working on the mobile app does not need the data pipeline's rules, and vice versa.

Common mistakes

• Too long. Instruction files consume context on every request. Hundreds of lines of generic advice (“write clean code”) bury the rules that matter.
• Stale commands. An outdated test command causes more damage than none, because the agent trusts it. Review the file when tooling changes.
• Secrets or internal URLs. The file is part of the repository; treat it as public within your organization.
• Vague prohibitions. “Be careful with the payment module” helps nobody. Say what to do: “Changes in payments/ require tests in payments/__tests__/ and must not change public function signatures.”
• Using it for enforcement. Instructions can be ignored. For hard guarantees, use hooks, permission rules, CI checks or branch protection.

Iterating on the file

The best instruction files grow from observed failures. When an agent makes the same mistake twice, add a one-line rule. When a rule no longer applies, delete it. Some teams review the file monthly alongside the pull requests agents produced, which keeps it honest. Agents can draft a first version by analyzing the repository, but a human should cut it down and verify every command.

Instruction files are one part of a broader discipline covered in context engineering for coding agents. Tool-specific detail is in Claude Code best practices and the Codex CLI guide, and the two agents are compared in Claude Code vs. OpenAI Codex.

Writing a good first instruction file together is one of the most productive hours a team can spend in a workshop. neooutput builds its agentic coding trainings around such hands-on steps, using the team's own repository.