Ugrás a fő tartalomhoz

AGENTS.md, CLAUDE.md, and Rules

Basic

Applies to: every repository you work in with a coding agent, on day one of an engagement · Time to learn: 30 min reading + 15 min exercise · Lever: context

An agent starts every session knowing nothing about your client's repository. The project instruction file is the one place where you tell it, once, how to build, test, and behave there. This page covers the open-standard AGENTS.md, Claude Code's CLAUDE.md, and path-scoped rules, and how to keep all of them short enough to help.

TL;DR
  • Treat the file as onboarding for a new teammate: commands, conventions, boundaries. It is not a copy of the README.
  • Make AGENTS.md the source of truth (open standard, many tools) and add a CLAUDE.md that contains @AGENTS.md plus Claude-only notes.
  • Keep it short and specific: target under 200 lines. Recent studies found that long or generic context files add cost without measurable gains.
  • Put rules that only matter for some files into path-scoped rules, and nested files in monorepos.
  • Files are advisory. Anything that must happen every time belongs in a hook.

Why it matters in the AI age​

The core idea of this section: an agent is only as good as (1) the context it gets, (2) the feedback loop it can run, and (3) the guardrails around it. This page is about the first lever, the part of context you control permanently.

  • Each Claude Code session begins with a fresh context window, so nothing from yesterday carries over unless it is written down (memory docs).
  • The instruction file is loaded before you type anything, so every line costs tokens on every session (context window docs). See Context Engineering for why that budget matters.
  • In a client repository you did not write, the commands that are obvious to the team (which test runner, which lint target, which folders are generated) are exactly what the agent cannot guess. Writing them down is the fastest way to stop it guessing.

Core concepts​

What the file is for​

AGENTS.md is described as "a README for agents": a markdown file with no required fields (agents.md). The README explains the project to humans. The agent file tells the agent what it needs to act safely.

The recommended sections on agents.md are: project overview, build and test commands, code style, testing instructions, and security considerations. Commit and PR guidelines, deployment steps, and security gotchas are optional additions (agents.md).

The AGENTS.md open standard​

The format is stewarded by the Agentic AI Foundation (AAIF) under the Linux Foundation. AAIF was announced on 2025-12-09 with three founding projects: MCP, goose, and AGENTS.md (AAIF announcement). The site reports more than 60,000 open-source projects using it (agents.md).

Which tools read it (as of 2026-10):

ToolHow it uses AGENTS.md
OpenAI CodexWalks from the project root to the working directory, one file per directory (AGENTS.override.md, then AGENTS.md), concatenated root to leaf; stops at a byte limit (32 KiB default per the docs) (Codex docs)
CursorReads AGENTS.md in the root and subdirectories; more specific files take precedence (Cursor rules)
OpenCodeReads the project AGENTS.md (walking up from the working directory) and a global ~/.config/opencode/AGENTS.md; falls back to CLAUDE.md if there is no AGENTS.md (OpenCode rules)
GitHub CopilotReads AGENTS.md files anywhere in the repo (nearest wins), or a single root CLAUDE.md or GEMINI.md (GitHub docs)
Gemini CLIReads GEMINI.md by default; to use AGENTS.md, list it in context.fileName in settings.json (Gemini CLI docs)
Claude CodeReads it natively since v2.1.277, in place of CLAUDE.md (see next section) (memory docs)

The agents.md site lists many more tools (Zed, Warp, Devin, Junie, Amp, Windsurf, and others). Where a tool's own docs disagree with that list, as with Gemini CLI, trust the tool's docs.

The nearest file wins​

In every tool above, the file closest to the edited file takes precedence, and an explicit instruction in the chat overrides any AGENTS.md (agents.md). That is what makes nested files in monorepos work.

CLAUDE.md locations​

Claude Code loads these locations (memory docs):

ScopePathShare it?
Managed policy/etc/claude-code/CLAUDE.md (Linux and WSL; macOS and Windows have their own paths)Org-wide
User~/.claude/CLAUDE.mdJust you, all projects
Project./CLAUDE.md or ./.claude/CLAUDE.mdCommit it
Local./CLAUDE.local.mdJust you; add to .gitignore

CLAUDE.md files in the working directory and every parent directory load at launch. Files in subdirectories load on demand when Claude reads or edits a file there.

Imports​

Inside a CLAUDE.md, @path/to/file pulls another file in. Relative paths resolve from the importing file, imports can chain up to four hops, and imports inside code spans and fenced blocks are ignored. Imports do not save context: imported files load at launch (memory docs). OpenCode does not parse @file references inside AGENTS.md; it uses the instructions key instead (OpenCode rules).

How Claude Code relates to AGENTS.md​

Verified against the memory docs (as of 2026-10):

  • Claude Code reads AGENTS.md natively from v2.1.277 and later.
  • By default it reads AGENTS.md only when no CLAUDE.md, CLAUDE.local.md, or .claude/CLAUDE.md exists in the working directory or above. If any exists, Claude reads only the CLAUDE.md files.
  • The "Project instructions" setting (/config) can read both (claude-md-and-agents-md) or only CLAUDE.md (claude-md).
  • It does not read AGENTS.local.md, AGENTS.override.md, or anything under .agents/.
  • A CLAUDE.md that contains @AGENTS.md works everywhere, including setups where native AGENTS.md reading is unavailable (for example Bedrock sessions, or telemetry disabled before v2.1.281).
  • A symlink (ln -s AGENTS.md CLAUDE.md) also works, but Edit and Write refuse to write through it and Windows checkouts can break it.

Recommended setup: AGENTS.md is the source of truth for every tool; CLAUDE.md imports it and adds Claude-only notes.

Repository root
AGENTS.md # shared instructions, read by Codex, Cursor, OpenCode, Copilot
CLAUDE.md # @AGENTS.md + Claude Code specifics
.claude/rules/ # optional: path-scoped rules

Path-scoped rules​

When a rule applies only to some files, do not put it in the root file. Scope it.

ToolWhereHow scoping works
Claude Code.claude/rules/*.md (recursive)YAML frontmatter paths:; the rule loads when Claude reads, writes, or edits a matching file. Rules without paths load at launch (memory docs)
Cursor.cursor/rules/*.mdcFrontmatter description, globs, alwaysApply. Types: Always, Auto Attached (glob), Agent Requested, Manual. Plain .md files there are ignored (Cursor rules)
OpenCodeinstructions in opencode.jsonList of file paths, globs (such as packages/*/AGENTS.md), or URLs, combined with AGENTS.md (OpenCode rules)
GitHub Copilot.github/instructions/*.instructions.mdapplyTo globs (GitHub docs)

Compaction detail for Claude Code: root CLAUDE.md and unscoped rules are re-injected from disk after compaction; path-scoped rules and nested CLAUDE.md files reload on demand (context window docs). A rule that must always be present should drop its paths: or move to the root file.

What goes in, what stays out​

The test from Anthropic for each line: "Would removing this cause Claude to make mistakes?" (best practices).

Put inLeave out
Build, test, lint, and run commands the agent cannot guessAnything the agent can read from the code (language, obvious folder names)
Conventions that differ from the defaultsStandard language conventions it already follows
Boundaries: generated folders, protected files, forbidden commandsLong tutorials and architecture essays (link to docs/ instead)
How to verify a change (the exact commands, in order)A copy of the README
Pointers to deeper docs, one line eachSecrets, tokens, customer data
Known traps, such as "migrations are applied by CI, never run them locally"Rules that must be enforced every time (use a hook)
Commit and PR conventionsFrequently changing facts such as sprint goals

Size and evidence​

  • Claude Code docs: "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence" (memory docs). Anthropic's best practices say the same in fewer words: keep it short (best practices).
  • Gloaguen et al., "Evaluating AGENTS.md" (arXiv 2602.11988, 2026): repository-level context files do not generally improve task success, and they raise inference cost by over 20% on average (abstract).
  • Khatri, a two-agent ablation on real repositories (arXiv 2607.27250, 2026): 288 runs with Claude Code and Codex; the presence of a context file did not measurably move correctness (abstract).

What to take from this: do not generate a long file and forget it. A short file of commands and non-obvious conventions costs little and removes guesswork. Everything else you add must earn its tokens.

Rules versus hooks​

CLAUDE.md, AGENTS.md, and rules are context. Claude treats them as guidance, not enforced configuration. To block an action regardless of what the model decides, use a PreToolUse hook (memory docs). If one instruction keeps getting skipped, add emphasis such as "IMPORTANT" to that line alone (best practices), and if it still matters, move it to a hook. See Hooks, Pre-commit, and Quality Gates.


How to do it​

1. Start from /init, then cut​

In Claude Code, /init generates a starter CLAUDE.md from the codebase, and suggests improvements if one already exists (memory docs). Treat the output as a draft: delete every line that fails the "would removing this cause a mistake" test.

2. Create AGENTS.md as the source of truth​

Use the template below. Fill in real commands by running them yourself first.

3. Add CLAUDE.md that imports it​

CLAUDE.md
@AGENTS.md

## Claude Code
- Use plan mode for any change touching more than three files.
- When compacting, always preserve the list of modified files and the test commands.

The compaction line follows Anthropic's example of customizing compaction in CLAUDE.md (best practices).

4. Add nested files for monorepos​

Monorepo layout
AGENTS.md # repo-wide: tooling, git, verification
packages/api/AGENTS.md # Go service: go test, golangci-lint
packages/web/AGENTS.md # TypeScript app: pnpm, Biome
infra/AGENTS.md # OpenTofu: plan only, never apply

Keep the root file about what is common. Each nested file covers only its subtree. For Claude Code, nested CLAUDE.md files containing @AGENTS.md give the same layout.

5. Add a path-scoped rule when a subtree has special needs​

.claude/rules/migrations.md
---
paths:
- "db/migrations/**"
---

- Migrations are forward-only. Never edit an applied migration; add a new one.
- Name files `YYYYMMDDHHMM_short_description.sql`.
- Run `make migrate-check` before committing.

The Cursor equivalent is .cursor/rules/migrations.mdc with a globs: line. For OpenCode, add the file to instructions in opencode.json:

opencode.json
{
"instructions": ["docs/agent-rules/*.md", "packages/*/AGENTS.md"]
}

6. Check what actually loaded​

In Claude Code, run /context to see which instruction files loaded and what they cost, and /memory to open and edit them (context window docs).

Template: AGENTS.md for a typical client repository​

Copy it, replace the placeholders in square brackets, and delete sections that do not apply. The file below is about 50 lines.

AGENTS.md
# [Project name]

[One sentence: what the service does and who uses it.]

## Stack
- [Language and version], [framework], [database], deployed with [Docker / OpenTofu / Helm].
- Tools are pinned in `mise.toml`; run `mise install` first.

## Commands
- Install: `[pnpm install]`
- Build: `[make build]`
- Test all: `[make test]`
- Test one file: `[pytest tests/test_x.py -q]`
- Lint and format: `[make lint]` (must pass before commit)
- Run locally: `[docker compose up]`

## Layout
- `src/` application code. `src/api/` HTTP handlers, `src/domain/` business logic.
- `tests/` mirrors `src/`.
- `infra/` OpenTofu. `docs/` design notes and ADRs.
- `generated/` is produced by `[make codegen]`.

## Conventions
- [Errors are returned as typed results, not raised, in `src/domain/`.]
- [New endpoints need an OpenAPI entry in `api/openapi.yaml`.]
- Commits: `type(scope): summary` (Conventional Commits). One logical change per commit.
- Prefer small diffs. Do not reformat files you are not changing.

## Do not touch
- `generated/`, `vendor/`, and `*.lock` files (regenerate with the commands above).
- Applied migrations in `db/migrations/`. Add a new one instead.
- `.env*` files. Never print or commit secrets.
- Never run `tofu apply` or deploy commands. Plans only.

## Verify before you say done
1. Run `[make lint]` and `[make test]`; both must pass.
2. For API changes, run `[make e2e]` or the curl check in `docs/runbook.md`.
3. Show the commands you ran and their results in your summary.

## More context
- Architecture: `docs/architecture.md`
- Decisions: `docs/adr/`
- Active work and plans: `docs/plans/`

Best practices​

  • Write for a new teammate on day one. Commands first, then layout, then the traps.
  • Prefer pointers to prose. One line plus a link to docs/ keeps the file small and the detail loaded only when needed.
  • Make verification explicit. Anthropic's top recommendation is to give the agent a way to check its work: tests, a build, a linter (best practices). The "Verify" section is where that lives.
  • Use the strongest scope that fits. Home directory for personal habits, repo root for team facts, nested files or paths: rules for subtrees.
  • Keep Claude-only content out of AGENTS.md. Slash commands, plan-mode habits, and compaction notes belong in CLAUDE.md.
  • Use CLAUDE.local.md for your own preferences on a client repo (sandbox URLs, personal shortcuts) and keep it out of git.
  • Strip comments you do not want loaded. HTML block comments in CLAUDE.md are removed before injection (memory docs), so they are a free place for notes to humans.

Maintain it​

The file is a living document, not a one-time setup.

  1. Update it when the agent repeats a mistake. If you correct the same thing twice, add one line that would have prevented it. Anthropic suggests starting a fresh session with a better prompt after two failed corrections (best practices); put the lesson in the file so the next session starts right.
  2. Review it in PRs like code. A change to AGENTS.md should have a reason in the description, and reviewers should ask whether each added line passes the "would removing this cause a mistake" test.
  3. Prune on a schedule. When the build changes or a convention is enforced by a linter, delete the line.
  4. Keep it in sync. Because CLAUDE.md imports AGENTS.md, there is only one place to edit.

Pitfalls to design around​

  • Generate, then cut. Auto-generated files restate what the agent could read from the code. Remove everything it could discover itself.
  • Link instead of paste. Pasting the README, API docs, or style guide inflates every session. Link to the file and let the agent open it when needed.
  • Pick one source of truth. Maintaining separate, drifting AGENTS.md, CLAUDE.md, and Cursor rules costs more than importing one file from the others.
  • Remember the default precedence. If a repo already has a CLAUDE.md, Claude Code ignores AGENTS.md under the default setting. Add @AGENTS.md to that CLAUDE.md, or change the setting.
  • Avoid CLAUDE.local.md surprises. A CLAUDE.local.md in the directory also makes Claude skip AGENTS.md under the default setting (memory docs). Import @AGENTS.md there as well, or use the "both" setting.
  • Use hooks for must-happen rules. If skipping an instruction would be costly (secrets, destructive commands), enforce it with a hook rather than a stronger sentence.
  • Never put secrets in the file. It is committed, and it is sent to the model.
  • Check Windows and Bedrock. If your client uses either, prefer the @AGENTS.md import over a symlink.

Try it​

Lab (15 min)

  1. Pick a real repository you work in. Run /init in Claude Code (or write the file by hand) and save the result.
  2. Cut it to under 100 lines using the "would removing this cause a mistake" test.
  3. Move it to AGENTS.md, and create a CLAUDE.md with @AGENTS.md plus one Claude-only line.
  4. Start a new session, run /context, and confirm the file loaded and see what it costs.
  5. Ask the agent to run the tests and make a one-line change. Note anything it got wrong, and add one line to AGENTS.md that fixes it.
  6. Add one path-scoped rule under .claude/rules/ for a subtree, and confirm it loads only after the agent touches a matching file.

Checklist​

  • AGENTS.md exists at the repo root and is under 200 lines.
  • It lists build, test, lint, and run commands that were executed and work.
  • It names do-not-touch paths and forbidden commands.
  • It has a "verify before done" section.
  • CLAUDE.md contains @AGENTS.md and only Claude-specific extras.
  • Subtree-specific rules are in nested files or path-scoped rules, not the root.
  • No secrets, customer data, or README copy.
  • Anything that must be enforced is a hook, not a sentence.
  • The file is reviewed in PRs and updated when the agent repeats a mistake.

Sources​