AGENTS.md vs CLAUDE.md

The setup we recommend

1. Put shared rules in AGENTS.md at the repo root and commit it.
2. Only if you need Claude-only rules, add a CLAUDE.md that starts with @AGENTS.md.
3. Point the tools that don't read AGENTS.md by default at it: Gemini CLI via context.fileName, Aider via read:.
4. Keep it short. Anthropic suggests under 200 lines per file; Codex stops reading at 32 KiB combined by default.

Who reads what

Copy-ready files

# AGENTS.md

## Commands
- Install: `npm ci`
- Test: `npm test` (run after any change in `src/`)
- Lint: `npm run lint`

## Rules
- Small, focused changes. One fix or feature at a time.
- Don't edit generated files in `dist/` or `vendor/`.
- Ask before adding a dependency or touching CI config.

## Layout
- `src/` app code · `tests/` mirrors `src/` · `docs/` user docs

@AGENTS.md

## Claude Code
- Use plan mode before multi-file refactors.

{
  "context": { "fileName": ["AGENTS.md", "GEMINI.md"] }
}

read: AGENTS.md

export CONTEXT_FILE_NAMES='["AGENTS.md", "CLAUDE.md", ".goosehints"]'

Imports and nesting

Claude Code expands @path imports in both CLAUDE.md and AGENTS.md, up to four hops deep. Imports inside code spans are ignored, so write `@README` to mention a file without loading it. Imports don't save context: imported files load at launch too.

Gemini CLI also supports @file.md imports in GEMINI.md. Codex and OpenCode 2 concatenate the files they find along the folder path instead, so put narrower rules in a subfolder's own AGENTS.md.

If you used a workaround before

Anthropic's docs list what to do with older setups now that Claude Code reads AGENTS.md itself: a CLAUDE.md containing @AGENTS.md can stay; a CLAUDE.md that only tells Claude to read AGENTS.md should become an import or be deleted; a symlink is fine; and a SessionStart hook that prints AGENTS.md should go, because it now adds a second copy.

Related