CLAUDE.md and AGENTS.md Templates for Claude Code and Codex CLI: What to Put In, What to Leave Out

Every coding agent starts each session with amnesia. You open Claude Code, it writes npm install when your repo is pnpm-only, touches the generated GraphQL client that must never be hand-edited, and adds a console.log that your lint rule has banned since 2023. You correct it. The session ends. Tomorrow it happens again.

Both major CLI agents solve this with a Markdown file at the repo root: CLAUDE.md for Claude Code, AGENTS.md for OpenAI's Codex CLI. The mechanism is identical — a file the harness reads before the first prompt — but the surrounding ecosystem has quietly become a stack decision. Which file you maintain, whether you maintain one or five, and which agent subscription you're paying for all interact. Here's a roundup of the options, when each earns its place, when it doesn't, and the pricing traps worth knowing before you commit.

图示：来源页预览图（仅作编辑上下文；版权归属原发布方） · 来源引用：dev.to

The file layer, mapped

Tool	Instruction file	Scope
Claude Code	CLAUDE.md	Repo root, nested dirs, ~/.claude/CLAUDE.md for global
Codex CLI	AGENTS.md	Repo root, nested dirs, ~/.codex/AGENTS.md
Cursor	.cursor/rules/*.mdc	Per-rule globs, always-on or agent-requested
GitHub Copilot	.github/copilot-instructions.md	Repo-wide, plus .instructions.md per path
Aider	CONVENTIONS.md	Explicitly loaded, not auto-discovered
Gemini CLI	GEMINI.md	Same shape as CLAUDE.md

The practical takeaway: AGENTS.md is becoming the closest thing to a lingua franca, and several tools now read it natively or via a symlink. If you only write one file, write AGENTS.md and symlink CLAUDE.md → AGENTS.md. It's one line of maintenance instead of two files drifting apart. The caveat is that tool-specific features (Claude Code's @path/to/file imports, for instance) won't survive the symlink in the other direction, so keep imports out of the shared file.

What actually belongs in the file

The failure mode is never "too short." It's a 400-line document the agent half-follows because it's competing with itself. Instruction files are a context budget, not documentation. Every line you add is a line the model spends attention on in every session, including sessions where it's irrelevant.

Put in:

1. Commands that aren't guessable. pnpm test:unit -- --watch=false. make db-reset before integration tests. The agent can infer npm test; it cannot infer your custom script names.
2. Hard prohibitions with a reason. "Never edit src/gen/** — regenerate with pnpm codegen." The reason matters: it lets the model generalize to a case you didn't anticipate.
3. Architecture in five lines, not fifty. "Hexagonal. Domain in src/core, adapters in src/adapters. No imports from adapters into core." That's a rule the agent can enforce while writing. A paragraph about your history of the migration is noise.
4. Style rules your linter can't catch. Naming conventions, error-handling philosophy, "prefer early returns," "no new dependencies without asking."
5. Pointers, not payloads. @docs/testing.md (Claude Code) or a plain "see docs/testing.md" rather than pasting the whole doc.

Leave out: dependency lists (the lockfile is authoritative and will go stale in your file), directory trees (the agent can ls), anything a formatter enforces, and anything phrased as aspiration — "write clean code" is not an instruction, it's a mood.

图示：HEXOPS 原创配图（受选题启发，非复制原文图片） · 来源引用：dev.to

A template that survives contact with reality, roughly 40 lines:

# <Project> — agent instructions

## Commands
- Install: `pnpm install`
- Test one file: `pnpm vitest run <path>`
- Typecheck: `pnpm tsc --noEmit` (must pass before you finish)

## Never
- Edit `src/gen/**` — run `pnpm codegen` instead.
- Add dependencies without asking.
- Commit `.env*` files.

## Architecture
- `src/core` = domain, zero I/O imports.
- `src/adapters` = DB/HTTP, implements ports in `src/core/ports`.
- Import direction: adapters → core, never the reverse.

## Style
- Errors: return `Result<T, E>`, do not throw in core.
- Prefer early returns over nesting.

Notice what's absent: no project description, no "about this codebase" paragraph. The agent figures that out in thirty seconds of reading files. Your instructions should cover what reading the files won't tell it.

When to use which

Claude Code earns its cost when you want deep, multi-file refactors and a plan-then-execute loop. Its CLAUDE.md supports @ imports, so you can split a large instruction set into modules and load them conditionally — useful in monorepos with per-package CLAUDE.md files. Skip it if your work is mostly single-file edits; you're paying a premium for orchestration you don't use.

Codex CLI is the better fit when you're already inside the OpenAI ecosystem, want a lighter-weight harness, or need the sandboxed-execution model. Its AGENTS.md discovery is hierarchical, which suits monorepos where each package needs different rules. Skip it if your team standardizes on Anthropic tooling — maintaining two instruction files for one repo is a tax with no payoff.

Cursor / Copilot are IDE-native and better for edit-in-place work than for agentic long-running tasks. Their rule systems are more expressive (globs, per-path activation), which is also their trap: teams write thirty rules, half of them conflicting, and the model silently picks. If you use them, keep the always-on set tiny and push the rest to path-scoped rules.

Aider is the odd one out: CONVENTIONS.md isn't auto-discovered, you pass it explicitly. That's a feature for reproducibility, a nuisance for onboarding.

Pricing caveats

This is where roundups usually mislead, so be careful:

• Agent CLIs are usually billed through a subscription, not per token, but not always. Claude Code historically ran on Pro/Max plans with usage limits, and on API credits for heavier users; Codex CLI runs against a ChatGPT plan or an API key. The same binary can cost you $20/month or $400/month depending on which auth path you choose. Check which one is actually configured before you benchmark.
• "Included" has limits. Subscription tiers have rolling usage windows. A heavy refactor day can hit them, and the fallback is either waiting or switching to metered API billing at rates that surprise people.
• Seat pricing compounds with the file layer. If you run Cursor ($20-ish/user), Copilot ($10-ish/user), and an agent CLI subscription, you're at $40–50 per developer per month before API overage. The instruction file costs nothing; the tools reading it do.
• Prices and plan names change quarterly. Treat any figure here as a shape, not a quote, and verify on the vendor's pricing page before you write it into a budget.

The one-file, two-tool setup

For most teams the pragmatic answer is: one AGENTS.md, symlinked to CLAUDE.md, roughly 40 lines, containing only commands, prohibitions, import direction, and style rules a linter can't enforce. Add a per-package AGENTS.md in a monorepo only where the rules genuinely differ. Review the file quarterly and delete anything that hasn't prevented a mistake — an instruction that never fires is just context tax.

The file earns its place when it stops you from repeating yourself. If you're still typing "use pnpm" in week three, the file is wrong, not the agent.

Sources

• Original story: CLAUDE.md and AGENTS.md Templates for Claude Code and Codex CLI
• Claude Code documentation — memory and CLAUDE.md imports: https://docs.anthropic.com/en/docs/claude-code/memory
• OpenAI Codex CLI repository and AGENTS.md conventions: https://github.com/openai/codex
• Cursor rules documentation: https://docs.cursor.com/context/rules
• GitHub Copilot custom instructions: https://docs.github.com/en/copilot/how-tos/configure-custom-instructions
• Aider conventions documentation: https://aider.chat/docs/usage/conventions.html
• Vendor pricing pages (verify current figures): https://www.anthropic.com/pricing, https://openai.com/chatgpt/pricing, https://cursor.com/pricing, https://github.com/features/copilot/plans