CLAUDE.md · AGENTS.md · the rule-file pattern

As AI coding assistants multiplied, the convention "write the project rules and context in a single file" took root. Tools differ slightly in name and location, but the intent is similar.

1. About rule files

File	Tool / ecosystem
CLAUDE.md	Anthropic Claude Code.
AGENTS.md	Adopted by OpenAI Codex and many others.
.cursorrules / .cursor/rules/*.mdc	Cursor (old and new formats coexist).
.github/copilot-instructions.md	GitHub Copilot.
.windsurf/rules/*	Windsurf.
CONVENTIONS.md	Bound explicitly in aider and others.
.continue/*.md	Continue.
.zed/*	Zed.

The same place (project rules and context) is handled, but each tool has different load rules and precedence.

The rise of AGENTS.md — it's mentioned because it started as an OpenAI Codex-style adoption, and its tool-neutral name appeals; other tools either read it or support it as an alias. It's not a single standard.

2. Per-location precedence

Layer	Location	Meaning
Global	~/.claude/CLAUDE.md	Common to all projects.
Project	<repo>/CLAUDE.md	Shareable with the team.
Directory	<repo>/<subdir>/CLAUDE.md	One module of a monorepo.
User local	<repo>/CLAUDE.local.md	Git-ignored, personal.

When working in a subdirectory, that directory's rule file is also merged in — that's the common shape. Precedence and merging follow the tool's docs.

3. Multi-tool environments

A repository where Claude Code · Cursor · Copilot are all used:

• Single source of truth in one file — write in one of AGENTS.md or CLAUDE.md, and keep the other tool's rule files as short pointers to that file.
• Aliases (symlinks) — create one file and symlink to other names.
• Write each separately — independent per tool. Drift risk.

The frequently seen shape is consolidating to one place and keeping the rest brief.

4. Merging mechanism

Tools usually inject rules into model context in one of these ways:

• Concatenate all matching files plainly.
• Insert matching files into a fixed slot in the system prompt.
• Attach invisibly to user input.

A long file uses tokens by itself and affects model inference.

5. Other paths

Strands besides rule files for delivering rules and context to the model:

• Write the system prompt directly — sent on every API call.
• Skills · Custom Modes — bundle rules and tools per work.
• MCP Prompts — tool-neutral standard prompts.
• Part of README — keep human-facing and model-facing docs together.
• External docs + index — put rules in a docs/ directory and keep the rule file as a short router.

6. The grain of a good rule file

• Short — so the model reads to the end.
• Clear units — separate "absolute rules" from "recommendations" visually.
• Examples — short code or command examples over abstract phrasing.
• Links — push the details to external docs.
• Version and date — make change times visible.

Common items:

• One paragraph of project overview.
• Folder structure essentials.
• Build, test, run commands.
• Code style and naming rules.
• Frequent dependencies and tools.
• Security and secrets policy.
• Documentation rules (language, tone).
• Explicit "don'ts" for tools and the model.

7. Monorepo pattern

Split into a short root router + per-service detailed rules:

/CLAUDE.md            ← service map · global rules · work-start procedure
/services/web/CLAUDE.md
/services/api/CLAUDE.md

When the root file gets too long the essentials get skipped, so keep it routing-centric.

Global rules — ~/.claude/CLAUDE.md holds general rules about using the tool itself (language preference, response tone, file-creation policy). Project files hold domain rules. Mixing the two places causes conflict and omission.

8. Antipatterns

Too long to read — hundreds of lines of rules cause the model to ignore parts and the human to miss updates. Start with 10–30 essential lines and branch out to external docs as needed.

The same rule duplicated in many places — when README.md, CONTRIBUTING.md, CLAUDE.md each repeat the same rule, drift sets in. Make one place SSOT and reference from others.

Contradictory rules — collisions like "answer in Korean" + "use English for technical terms". Specify precedence and exceptions.

Pasting tool commands as-is — they break when tool versions change. Abstract commands into scripts where possible.

Including secrets — rule files are committed. Examples of credentials and internal URLs leaking are out there.

Forcing the model to brag — self-amplifying instructions like "always answer with full confidence" encourage the model to give wrong answers confidently. Restraint and honesty are safer.

9. Short template

# Project X

> One-line summary. Service map if monorepo.

## When starting work

1. Read this file.
2. Read the `CLAUDE.md` of the directory you'll change.
3. If needed, read §1~§N of `docs/RULES.md`.

## Absolute rules

- Answer in Korean.
- Don't propose `.env*` or key files as commit candidates.
- Irreversible commands (`rm -rf` · `DROP TABLE`) require user confirmation.

## Commands

- Build: `pnpm build`
- Test: `pnpm test`
- Dev server: `pnpm dev`

## Directories

- `apps/`: apps.
- `packages/`: shared.
- `docs/`: docs.

Use the grain above as a starting point and expand incrementally.

10. Common pitfalls

Multi-tool rule drift — per-tool files grow separately and give different answers. SSOT and a router.

Language mixing — mixing Korean and English in the same paragraph shakes the model's tone. Specify the standard.

Per-model behavior differences — the same file produces different reactions in different models. Lean on abstractions and examples.

Expecting all answers from CLAUDE.md alone — docs, tests, and the codebase are the real source. The rule file is for routing and summary.

Missing change history — policy changes but the file stays. Date and change records.

Subdirectory omission — when a monorepo lacks per-module rules, general rules apply and domain-specific traits get ignored.

Mixing with the permission model — rule files are advice, permission gates are settings. Don't mix them.

Closing thoughts

Rule files work best when kept short and routing-centric. When they get long, both the model and the human skip parts. SSOT in one place + per-service split + cross-reference — these three places become the operations standard.

Next

• ai-coding-ides
• ai-cli-tools

We refer to Claude Code Memory · Cursor Rules · Copilot Custom Instructions · aider CONVENTIONS · OpenAI Codex · Awesome Cursor Rules.