CLAUDE.md and AGENTS.md are the two files that tell an AI coding agent how your project works and where it must not go. If you build with Claude Code, Codex, Cursor or Gemini CLI, they’re the difference between an agent that follows your conventions from the first prompt and one that guesses.
This post covers what the files are, why a new project needs one before the first real commit, what belongs in it, and a short example you can copy.
What CLAUDE.md and AGENTS.md are
CLAUDE.md is the project instruction file for Claude Code. AGENTS.md is the cross-tool standard that does the same job for other agents. Both are plain Markdown files in the root of your repository, read automatically when a session starts.
Claude Code loads CLAUDE.md into its context at the start of every session, so anything in it shapes every answer without you repeating it. It also reads CLAUDE.md files in parent directories and subdirectories, which is useful in a monorepo.
AGENTS.md is an open format, published in 2025 and now stewarded under the Linux Foundation, that Codex, Cursor, Gemini CLI, GitHub Copilot and a growing list of other tools read in the same way. Same idea, tool-neutral name.
Most projects end up with both. If you only ever use Claude Code, CLAUDE.md alone is fine. If you switch tools or work with people who do, keep both and make sure they agree. More on that below.
Why a new project needs one from the first commit
An agent with no rules file will infer your conventions from whatever it sees first, and whatever it sees first in a new project is nothing. The rules file fixes that by stating the things the code can’t show yet.
On day one, a repo has a README, maybe a package manifest, and a lot of empty space. Ask an agent to “add the login page” and it has to guess the framework, the test runner, the folder layout, where secrets come from, and whether main deploys to production. It will guess confidently. Some of the guesses will be wrong, and you’ll spend the afternoon un-guessing them.
Write the rules file before the first feature and every session starts with the same ground truth. This matters most for the rules that have consequences: which commands are destructive, which branch deploys where, and which environment is production. Those belong in the file before there’s any production to damage. There’s a fuller argument for structural limits in guardrails for AI coding agents.
What to put in it
Put in the things an agent can’t infer from the code and would get wrong by guessing: how to build, test and run, how the repo is laid out, the conventions you care about, and what’s off limits.
A good rules file answers five questions:
- What is this? One or two sentences. What the project does and who it’s for.
- How do I run it? The exact commands for install, dev server, tests, lint, build. Agents run commands; give them the real ones.
- Where does everything live? The folder layout and what goes where. Three to eight lines.
- What are the conventions? Only the ones you’d correct in a code review: naming, formatting, error handling, how to write a test.
- What must it never do? Production, secrets, destructive commands, force pushes, and which branch deploys where.
Here’s a compact example for a small web project with dev and prod environments and GitHub Actions deploys:
# Project rules
Marketing site and API for Example. Astro front end, Lambda API, deployed with CDK.
## Commands
- Install: `npm ci`
- Dev server: `npm run dev`
- Tests: `npm test` (must pass before any commit)
- Lint: `npm run lint`
- Deploy to dev: push to any branch; CI deploys to the dev account
- Deploy to prod: merge to `main`; CI deploys to the prod account. Never deploy prod from a laptop.
## Layout
- `src/pages/` Astro pages
- `src/api/` Lambda handlers, one file per route
- `infra/` CDK stacks
- `test/` Jest tests, mirrors `src/`
## Conventions
- TypeScript strict mode, no `any`
- Every API handler has a test
- No em dashes in user-facing copy
## Never
- Never run commands against the prod AWS account. Dev credentials are the only ones on this machine.
- Never commit secrets. Config comes from environment variables listed in `.env.example`.
- Never run `git push --force`, `aws s3 rm`, `cdk destroy` or `DROP TABLE` without asking first.
- Never edit `infra/prod-*.ts` without a human reviewing the diff.That’s about 30 lines and it covers everything an agent needs on day one. Notice the “Never” section is specific and checkable. “Be careful with production” is a wish. “Never run commands against the prod AWS account” is a rule the agent can follow.
A sentence on TigerSoup, since it’s relevant: TigerSoup writes both CLAUDE.md and AGENTS.md into every project it sets up, pre-filled with the project’s layout, deploy path and the production rule, so the agent knows the boundaries from the first prompt.
What to leave out
Leave out anything the agent can read from the code, anything that belongs in documentation for humans, and anything you’d be embarrassed to pay for in context tokens every single session.
Common mistakes:
- Long prose. The file is loaded every session. A 600-line essay costs tokens and attention, and agents follow long files worse, not better. Keep it well under 200 lines.
- Duplicated docs. Don’t paste the architecture document in. Link to it, or name the file and let the agent read it when it needs to.
- Generic advice. “Write clean code” and “follow best practices” change nothing. If a rule wouldn’t change the agent’s behaviour, cut it.
- Contradictions. If one line says “use tabs” and another says “use the Prettier config” and Prettier says spaces, the agent will pick one at random. Say it once.
- Secrets. The file is committed to git. Nothing in it should be sensitive.
A useful test: read each line and ask “would the agent do something different without this?” If not, delete it.
Keeping CLAUDE.md and AGENTS.md in sync
If you have both files, make one the source of truth and have the other point to it. Two copies of the same rules drift apart within a month.
The simplest pattern is to write the rules in AGENTS.md, since it’s the tool-neutral one, and make CLAUDE.md a one-line file that includes it. Claude Code supports an @ import syntax for exactly this:
@AGENTS.mdAny Claude-specific additions, such as which custom commands exist, go below that line. Every other tool reads AGENTS.md directly and sees the same rules.
If you’d rather keep two full files, add a line at the top of each that says the other must be updated at the same time, and treat a mismatch as a bug in code review. The import approach is less work.
A rules file is a cheap guardrail, not the only one
A rules file is the soft layer. It makes an agent far more likely to do the right thing, and it’s the fastest way to encode your conventions. It is not a security control. An agent can misread it, a session can start without it, and a determined mistake will go around it.
The hard layer is structural: dev credentials that can’t see production, prod deploys that only happen from main through CI with short-lived credentials, and separate accounts for dev and prod. Put both layers in place and an eager agent becomes a fast colleague instead of a liability. The complete day-one list is in the new project setup checklist.
TigerSoup sets up both layers for each new project: separate accounts, gated production, and CLAUDE.md and AGENTS.md written and ready. It’s a free Mac app, and it opens the finished project straight in Claude Code, Codex or Gemini so the first prompt starts with the rules already in place.
