Agent workflow

AGENTS.md vs CLAUDE.md: Rules Agents Can Actually Use

Choose project instruction files for Codex, Claude Code, Cursor, and mixed-agent repositories, with a practical content template.

Short answer

Use the instruction file your agent reads by default. In a mixed-agent repository, keep shared facts in AGENTS.md and tool-specific behavior in the relevant file. Include commands, architecture boundaries, review rules, and verifiable constraints, not a long style manifesto.

Who this is for

Developers and teams that repeatedly explain repository commands, conventions, and safety boundaries to coding agents.

What is changing now

Instruction files are becoming part of the agent harness. Their value comes from reducing rediscovery and making behavior repeatable across tasks, tools, and contributors.

Problems this guide solves

Agents guess build commands and repository structure on every task.
Rules files grow into stale documentation that conflicts with the code.
Different agent tools receive different safety and review expectations.

Step 1

Choose the file structure

Keep shared repository truth separate from optional tool behavior.

Use AGENTS.md for shared commands, architecture, conventions, and boundaries in a mixed-agent repo.
Use CLAUDE.md for Claude Code-specific instructions that should not apply everywhere.
Add nested instruction files only when a subdirectory has genuinely different commands or ownership.
Do not duplicate the same rule in several files unless the tools cannot share it.

Step 2

Write rules that can be checked

Good instructions help an agent decide or run a command.

List install, development, test, lint, build, and formatting commands.
Name important modules, generated directories, and files that should not be edited.
State when approval is needed for dependencies, migrations, secrets, deploys, and destructive actions.
Define completion as tests, diff review, and a concise handoff.

Step 3

Keep the file alive

A short current file beats a comprehensive stale one.

Review instructions when commands, architecture, or CI changes.
Remove preferences that are already enforced by a formatter or linter.
Turn repeated agent mistakes into one clear rule or automated check.
Ask a new contributor to follow the file and report unclear steps.

Final checklist

The agent's default instruction file is known.
Shared and tool-specific rules are separated.
Core commands can be copied and run.
Protected areas and approval boundaries are explicit.
Rules do not duplicate automated formatting or lint checks.
The file has an owner and changes with the repository.

Common questions

Should I use both AGENTS.md and CLAUDE.md?

Use both only when you have shared rules plus Claude-specific behavior. Avoid copying the full same document into both files because they will drift.

How long should an instruction file be?

There is no ideal word count. Keep it short enough to scan and specific enough to run the project safely. Move detailed background into linked documentation.

What should never go in the file?

Do not put secrets, temporary workarounds presented as permanent rules, or vague demands such as 'write perfect code' that cannot guide a decision or check.

Use this on one real task

Apply the checklist before changing tools again. A useful setup should make the result easier to prove, review, and recover.