agent-config · diff
v1.4.3 to v2.0.1
108 added, 168 removed. Audit A to A.
---
name: agent-config
- description: "Create or update CLAUDE.md and AGENTS.md files following official best practices. Use when asked to create, audit, or improve agent config files (CLAUDE.md, AGENTS.md). Don't use for README/contributor docs or non-Claude IDE plugins."
+ description: "Create, update, or audit AGENTS.md (default) or CLAUDE.md agent instructions: set up, prune, add a rule, or merge CLAUDE.md or .cursorrules into one file Claude Code, Codex, and Cursor all read. Don't use for READMEs, skills, or subagents."
license: MIT
effort: medium
metadata:
- version: 1.4.3
+ version: 2.0.1
author: "Luong NGUYEN <luongnv89@gmail.com>"
---
## When to Use
- Use when the user asks to create, update, audit, or improve `CLAUDE.md` or `AGENTS.md`. Skip for generic README or contributor-doc work.
+ Create, update, or audit the instruction files coding agents load every session. **`AGENTS.md` is the default output**: it's the open standard that Claude Code (v2.1.277+), Codex, Cursor, Copilot, and others read. Produce `CLAUDE.md` as the output only on an **explicit request**, meaning the user asks for a CLAUDE.md to be written or edited ("create a CLAUDE.md", "add X to CLAUDE.md"). Naming it as a *source* doesn't count ("migrate our CLAUDE.md to AGENTS.md"), and neither does a CLAUDE.md that already exists on disk. Skip READMEs and contributor docs, skills (`skill-creator`), and subagent files under `.claude/agents/` (`subagent-creator`).
## Core Principle
- These files are **context, not enforced configuration**. They are loaded every session and the agent may still deviate.
+ These files are **context, not enforced configuration**. They load every session, and the agent may still deviate from them.
- - Short, specific, always-on facts go in the file.
- - Multi-step procedures go in a **skill**.
- - "Must never happen" goes in a `PreToolUse` **hook** plus permissions.
- - "Verify the work" goes in **tests or CI**, not a sentence.
+ - Short, always-on facts the agent cannot infer go in the file.
+ - Multi-step procedures go in a **skill**. Anything that must never happen goes in a `PreToolUse` **hook** plus permissions. Verification of the work goes in **tests or CI**.
+ - **Minimal beats complete.** Agents run every command the file lists and obey every rule, so each extra line costs steps and tokens on every task. LLM-generated files that restate the repo measured about 20% more cost with no success gain. This skill is an LLM writing such a file, so the prune pass in Step 3 is mandatory for new content.
- Write the constitution here; enforce the law somewhere else. Full rules and their sources: `references/official-standards.md`. Which layer owns a given instruction: `references/knowledge-routing.md`.
+ Which layer owns an instruction: `references/knowledge-routing.md`. Loading rules and sources: `references/official-standards.md`.
## Prerequisites
- - Run inside a git repo with `origin` set; the skill **requires** a clean tree before destructive edits.
- - Tools: `git`, file write access to the target path.
- - Confirm whether the user wants `CLAUDE.md`, `AGENTS.md`, or both before writing.
+ - A git repo with `origin` set, for anything that writes. `audit` only needs read access.
+ - Tools: `git`, and write access to the target path.
+ ## Mode Selector
+
+ ```text
+ $ARGUMENTS
+ ```
+
+ - **audit**: the user says `audit`, "review", or "check". Read-only.
+ - **write**: anything else (`create`, `update`, a specific change, or a path such as `packages/api/AGENTS.md`).
+
+ Every mode runs Step 1 first. After Step 1, a write run is a **targeted edit** when the user named a specific change to an existing file. Otherwise it's a **full pass**. Write runs continue with Steps 2–4; audit jumps to **Audit**.
+
## Repo Sync Before Edits (mandatory)
- Sync the current branch with remote before any create/update/delete. This is a destructive workflow — always **dry-run first** with `git fetch` (read-only) and inspect status before pulling.
+ Before a write run changes anything, sync with the remote. `audit` skips this. `git fetch` is the read-only dry run.
```bash
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin # dry-run: read-only preview
git status # validate clean tree
git pull --rebase origin "$branch" # only after confirmation
```
- If the working tree is dirty, **back up via stash** before syncing:
-
- ```bash
- git stash push -u -m "pre-sync-backup" # backup
- git fetch origin && git pull --rebase origin "$branch"
- git stash pop # restore
- ```
-
- If `origin` is missing, rebase conflicts occur, or stash pop fails, **stop and confirm** with the user before continuing. Never overwrite an existing `CLAUDE.md` / `AGENTS.md` without first reading it and showing a diff.
-
- ## User Input
-
- ```text
- $ARGUMENTS
- ```
-
- Recognised inputs: `create`, `update`, `audit`, or a path (e.g., `src/api/CLAUDE.md`).
-
- ## Step 1: Determine Target File
-
- If unspecified, ask which file:
-
- - **AGENTS.md** — the cross-agent source of truth, readable by any coding agent (Claude Code, Codex, others). A README *for agents*: setup, commands, layout, style deltas, tests, PR rules, security. Plain Markdown, no schema. Closest file wins, so nested copies override ancestors.
- - **CLAUDE.md** — Claude-specific context loaded each conversation. When `AGENTS.md` already exists, `CLAUDE.md` opens with `@AGENTS.md` and carries only Claude-only extras — never a second copy of the same rules.
+ If the tree is dirty, back it up with `git stash push -u -m "pre-sync-backup"`, sync, then run `git stash pop`. **Stop and confirm** with the user if any of these happen: the directory isn't a git repo, `origin` is missing, the HEAD is detached, the branch has no upstream, the pull or rebase fails, or the pop fails. Never overwrite an existing agent file without reading it and showing a diff.
- **Default when the user says "both":** write the content once into `AGENTS.md`, then a thin `CLAUDE.md` wrapper. Templates for both: `references/knowledge-routing.md`.
+ ## Step 1: Resolve the target (every mode)
- Subagent definition files (`.claude/agents/*.md`) are a different artifact and out of scope here — that is the `subagent-creator` skill's domain. Some repos, including this catalog, also keep subagent prompts inside their `AGENTS.md`; when the target file already uses that shape, preserve it and audit only the prose sections.
+ 1. The output is `AGENTS.md` in the repo root, or the path the user gave. It's `CLAUDE.md` only on an explicit request (see When to Use).
+ 2. **Shadow check.** By default, Claude Code reads `AGENTS.md` only when no `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` exists in the launch directory or any directory above it; `~/.claude/CLAUDE.md` doesn't count. A subdirectory's `AGENTS.md` loads only when that directory has no CLAUDE file of its own. Any file that counts *shadows* `AGENTS.md`. From the repo root, list CLAUDE files above the root and inside the repo:
- ## Content Guidelines (both files)
+ ```bash
+ root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"; d="$(dirname "$root")"
+ while :; do for f in CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md; do p="$d/$f"
+ { [ -e "$p" ] || [ -L "$p" ]; } && [ "$p" != "$HOME/.claude/CLAUDE.md" ] && echo "ABOVE-REPO $(ls -l "$p")"
+ done; [ "$d" = / ] && break; d="$(dirname "$d")"; done
+ find "$root" \( -name node_modules -o -name .git \) -prune -o \( -name CLAUDE.md -o -name CLAUDE.local.md -o -name AGENTS.md \) -print |
+ while read -r p; do ls -l "$p"; grep -qE '^@(\.\.?/)*AGENTS\.md' "$p" 2>/dev/null && echo " -> imports AGENTS.md" || true; done
+ ```
- These files give the agent persistent context **it cannot infer from code alone**.
+ 3. **Classify every CLAUDE file found. Each gets its own action**:
- **Size budget:** under **200 lines** per file (sweet spot 40–150); Codex's combined budget is 32 KiB. Past 200 lines, adherence measurably drops. When a file outgrows it: path-scope folder rules into `.claude/rules/*.md`, extract procedures into a skill, replace pasted docs with a pointer. Never use `@import` to save tokens.
+ | File | Action |
+ |---|---|
+ | Above the repo root (for example `~/CLAUDE.md`) | **Never edit it.** Warn that it blocks `AGENTS.md` in every repo below it, and suggest moving its content to `~/.claude/CLAUDE.md`, which doesn't count |
+ | `CLAUDE.local.md` | **Never edit it.** Warn that it stops Claude from reading `AGENTS.md` for its owner. Suggest `@AGENTS.md` as its first line, or `/config` → **Project instructions** → `claude-md-and-agents-md`. That setting is per-user and ignored in project settings |
+ | A symlink to `AGENTS.md` | Nothing to do. Write to the link's target, because Edit and Write refuse to write through symlinks |
+ | Already imports `AGENTS.md` | Keep it, holding only Claude-only lines |
+ | In the repo, no import | **Migrate**: move shared rules to `AGENTS.md`, and shrink the file to the import plus its Claude-only lines. Import paths are relative to the file, so `.claude/CLAUDE.md` uses `@../AGENTS.md` |
- ### Include vs Exclude
+ 4. **Pick the branch:**
+ - **wrapper**: the user asked for both files.
+ - **claude-only**: an explicit CLAUDE.md request and no `AGENTS.md`.
+ - **wrapper**: an explicit CLAUDE.md request, and `AGENTS.md` exists. Write the CLAUDE.md as the import plus Claude-only lines, and touch `AGENTS.md` only if asked.
+ - **migrate**: any in-repo CLAUDE file needs migrating.
+ - **agents-only**: everything else.
- | Include | Exclude |
- |-----------|-----------|
- | Bash commands Claude cannot guess | Anything Claude can figure out from code |
- | Code style rules that differ from defaults | Standard language conventions |
- | Testing instructions and preferred runners | Detailed API docs (link instead) |
- | Repository etiquette (branch naming, PRs) | Information that changes frequently |
- | Architectural decisions specific to project | Long explanations or tutorials |
- | Developer environment quirks (env vars) | File-by-file codebase descriptions |
- | Common gotchas or non-obvious behaviors | Self-evident practices like "write clean code" |
+ **Claude-only lines** name Claude Code features: plan mode, `/commands`, skills, hooks, subagents, or MCP tools. They stay in a CLAUDE file that already exists or was requested. Otherwise they go to `.claude/rules/<topic>.md`, which loads alongside `AGENTS.md` without shadowing it. Never create a `CLAUDE.md` just to hold them.
- Also pin what the model would otherwise guess wrong: the package manager (`pnpm`, not `npm`), the language version, the single-test command.
+ **When the user reports that `AGENTS.md` isn't loading and the shadow check is clean**, check the environment before rewriting any content: `claude --version` (v2.1.277+), the **Project instructions** value in `/config`, and whether the `agents-md` plugin is enabled (`official-standards.md` → Claude Code).
- See `references/anti-patterns.md` for the full quality test and failure modes, and `references/claude-md-checklist.md` for the structural audit checklist (length budget, routing, enforceability, 5 required sections, drift).
+ Done when the output path(s), the branch, each CLAUDE file's action, and the raw shadow-check output are shown.
- ### Example Format
+ ## Step 2: Analyze the project (full pass)
- ```markdown
- # Code style
- - Use ES modules (import/export), not CommonJS (require)
- - Destructure imports when possible
+ Collect only what an agent would otherwise get wrong:
- # Workflow
- - Typecheck after a series of code changes
- - Prefer single-test runs over the full suite for performance
- ```
+ - **Commands** from manifests and CI (`package.json` scripts, `pyproject.toml`, `Makefile`, `.github/workflows/*`): install, dev, test all **and** one, lint, and typecheck, with the flags CI uses.
+ - **Pins**: the package manager and runtime version, wherever a guess would fail (`pnpm`, not `npm`).
+ - **Boundaries**: generated, vendored, and secret paths, and actions that need a human first.
+ - **Existing rules** in agent files, `.cursor/rules/`, `.cursorrules`, and `.github/copilot-instructions.md`. Keep what is still true, and leave those files in place.
- ### File Locations
+ Done when every command you will write was read from a file. If no manifest or CI defines a command, write none for it and ask the user; never guess one.
- - `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md` — personal defaults, all sessions. The user owns these; never rewrite one from a repo-scoped run.
- - `./CLAUDE.md`, `./AGENTS.md` — checked into git, shared with the team, reviewed like code.
- - `CLAUDE.local.md` / `AGENTS.override.md` — gitignored personal overrides.
- - `.claude/rules/*.md` with a `paths:` key — load only when matching files are touched.
- - Nested per-package files in monorepos; closest file wins.
+ ## Step 3: Draft
- ### Imports and Emphasis
+ For a **targeted edit**, make the requested change, add the token-efficiency block if it's missing, and change nothing else. List other prune candidates in the report, but don't apply them. For a **full pass**, read `references/agents-md-writing.md` first. It holds the template, the writing rules, and the evidence behind them. Then:
- `@README.md`-style imports organize files but **do not shrink context** — imported files still load at launch. Reach for a path-scoped rule when the goal is fewer tokens.
+ 1. **Fill the template.** **Commands**, **Constraints** (*Never* and *Ask first*), and **Done when** are required. Project, Layout, Conventions, and Read when needed appear only when they hold a fact the agent cannot infer.
+ 2. **Prune pass.** Delete every line that fails the deletion test: *"would removing this cause a specific mistake?"* Also delete any overview, directory tree, dependency list, or restatement of the README. Move Claude-only lines to the place Step 1 names.
+ 3. Add opt-in blocks from `references/optional-blocks.md` only when the user asks for them.
+ 4. **Append the token-efficiency block** (see below) last.
- Add **IMPORTANT** or **YOU MUST** only to true hard rules. Scattering them trains the model to ignore the markers.
+ Done when every remaining line is a command, a pin, a constraint, or a pointer.
- ## AGENTS.md Guidelines
+ ## Step 4: Write and verify
- `AGENTS.md` is the shared, agent-agnostic contract. Use this section order:
+ - **Show before writing.** For a new file, show the draft. For an existing file, show the diff. Write once the user approves, or right away if the request already said to apply the change.
+ - **Verify**:
+ - `wc -l` is under 200 for each file.
+ - `grep -c '^## Token Efficiency'` returns 1 in the source of truth and 0 everywhere else.
+ - Each wrapper's first line is the `AGENTS.md` import.
+ - Re-running the shadow check shows no in-repo CLAUDE file shadowing `AGENTS.md`.
+ - **Report how to confirm the load.** In Claude Code v2.1.280+, `/memory` lists `AGENTS.md`. In Codex, run `codex --ask-for-approval never "Summarize the current instructions."`. Clients that cannot read `AGENTS.md` need a one-line `CLAUDE.md` holding `@AGENTS.md`: Claude Code before v2.1.277, and some Bedrock or telemetry-off sessions before v2.1.281. Offer that file, but don't create it unasked.
- ```markdown
- ## Project — 2–4 sentences: what it is, invariants that must not break
- ## Commands — install, dev, test (all / one), lint, types, adding a dep
- ## Layout — package map, what may be edited, where tests live
- ## Conventions — deltas from defaults only, one short example if needed
- ## Constraints — never edit generated/, don't push to main unless asked
- ## Done when — the exact lint/type/test commands that define completion
- ## Read when needed — pointers: billing → `docs/billing.md`
- ```
+ ## Audit (read-only)
- Every bullet must be a command, a pin, a constraint, or a pointer. One idea per bullet; no two bullets may contradict. Full templates, writing rules, and the maintenance feedback loop: `references/knowledge-routing.md`.
+ 1. Read these together, because shadowing and drift only show up across the set:
+ - `AGENTS.md`
+ - every file the shadow check found
+ - any `AGENTS.override.md`
+ - `.claude/settings.json` and `.claude/settings.local.json`, for hooks
+ 2. Walk `references/agents-md-checklist.md`, and report every item as pass, fail, or N/A with a one-line reason. Its loading section catches CLAUDE files that shadow without importing, prose telling Claude to "read AGENTS.md", a `SessionStart` hook that prints `AGENTS.md`, and an `AGENTS.override.md` that Codex reads instead.
+ 3. Cross-check `references/anti-patterns.md`.
+ 4. **Route and enforce.** For every failing line, name its home from `references/knowledge-routing.md`. A rule a machine can check gets its gate **and** loses its prose.
+ 5. Modify nothing; `git status` must be unchanged. End with the overall verdict. Suggest `/memory` to see what loaded, and `/doctor prompt-audit` (v2.1.283+) for a second pass.
## Token Efficiency Block (always inject)
- **Always** append the block from `references/token-efficiency-block.md` once into the source-of-truth file — `AGENTS.md` when writing both (or when `AGENTS.md` already exists), otherwise the single target. Do **not** copy it into the `CLAUDE.md` wrapper; the wrapper opens with `@AGENTS.md` and inherits the block. This is non-negotiable — it protects the agent's context window and budget.
-
- It is the one deliberate exception to "no general advice": these are always-on rules about how the agent works, not about the code, so the source-of-truth file is the layer that owns them.
-
- ## Optional Blocks (only when requested)
-
- If the user asks for orchestration rigor or stricter coding rules, copy verbatim the relevant block from `references/optional-blocks.md` (Workflow Orchestration / Mandatory Coding Discipline). Do not inject blindly.
-
- ## Execution Flow
-
- ### `create` (default)
-
- 1. Ask which file type if unspecified.
- 2. Analyze project: existing files, stack, README, package manifests.
- 3. Draft following guidelines + inject the token-efficiency block once into the source of truth.
- 4. If user said "apply now", write directly; otherwise present draft.
- 5. Finalize at the right path.
-
- ### `update`
-
- 1. Read existing file (do not skip — used to compute diff).
- 2. Audit against guidelines.
- 3. Identify content to remove, condense, or add.
- 4. Apply if asked, else show diff.
-
- ### `audit`
-
- 1. Read existing file. If both `AGENTS.md` and `CLAUDE.md` exist, read both — drift is only visible across the pair.
- 2. Walk every item in `references/claude-md-checklist.md` (length budget, content quality, routing, enforceability, 5 required sections, drift, final checks). Report each as pass / fail / N/A with a one-line reason.
- 3. Cross-check against `references/anti-patterns.md`.
- 4. **Route and enforce.** For every failing line, name where it belongs: a skill (procedure), a `.claude/rules/*.md` path-scoped file (folder-only), a `PreToolUse` hook plus permissions (must-never-happen), a test or CI (verification), or the user-level file (personal taste). A machine-checkable rule gets the gate **and** loses its prose.
- 5. Report: checklist results, anti-patterns found, routing recommendations, duplicated or contradicting rules, top recommendations.
- 6. **Do NOT modify the file** — report only. Suggest `/context` to confirm the file loads and `/doctor` to prune what the agent can infer.
+ Append the fenced block from `references/token-efficiency-block.md` once, as the last section of the source-of-truth file. The source of truth is the root `AGENTS.md`, or `CLAUDE.md` on the claude-only branch. Never add the block to a wrapper, a nested package file, or a `.claude/rules/` file: those load alongside the root file, and a second copy would double it. It is the one deliberate exception to "no general advice": these are always-on rules for how the agent spends its context window. Non-negotiable: add it on every write run where the source of truth lacks it, including a targeted edit, and say so in the report. The one exception is the wrapper branch: don't edit an `AGENTS.md` that already exists just to add the block; report that it's missing instead.
## Step Completion Reports
- After each major step, output:
+ After each step, output:
```
◆ [Step Name] ([step N of M])
··································································
[Check 1]: √ pass
[Check 2]: × fail — [reason]
[Criteria]: √ N/M met
____________________________
Result: PASS | FAIL | PARTIAL
```
- Use `√` for pass, `×` for fail. Adapt check names per step.
+ Use `√` for pass and `×` for fail. Adapt the check names to each step.
## Acceptance Criteria
- A run passes when **all** of the following are true:
-
- - [ ] Target file path confirmed (CLAUDE.md, AGENTS.md, or explicit path).
- - [ ] Repo synced clean OR user explicitly authorised proceeding without sync.
- - [ ] Token-efficiency block present in the source-of-truth file — `AGENTS.md` when both exist, otherwise the single target (verify by grep `## Token Efficiency`). Absent from the `CLAUDE.md` wrapper.
- - [ ] No anti-pattern from `references/anti-patterns.md` appears in the new content. **Prose standing in for a gate** is audit-time only — constitution Constraints pins do not fail create/update.
- - [ ] For `create` / `update`: result passes checklist sections 1–3 and 5–7 of `references/claude-md-checklist.md` (length budget, content quality, routing, 5 required sections, drift, final checks). Section 4 (enforceability) is reported on `audit` and does not fail a create/update run.
- - [ ] Generated/updated file is under 200 lines (verify with `wc -l`).
- - [ ] No rule appears in both `AGENTS.md` and `CLAUDE.md`; when both exist, `CLAUDE.md` opens with `@AGENTS.md`.
- - [ ] For `audit`: every checklist item is reported with pass / fail / N/A, each failing line carries a routing recommendation, and no file was modified (verify with `git diff --stat`).
- - [ ] Final step-completion report emitted with `Result: PASS`.
+ - [ ] The branch, each CLAUDE file's action, and the shadow-check output are shown.
+ - [ ] Without an explicit CLAUDE.md request, no new `CLAUDE.md` was created.
+ - [ ] After the run, every in-repo CLAUDE file either imports `AGENTS.md` or is a symlink to it. Files above the repo and `CLAUDE.local.md` were left unedited, and the user was warned about them.
+ - [ ] The repo was synced, or the user explicitly authorised skipping the sync.
+ - [ ] The token-efficiency block appears exactly once, in the source of truth, unless the wrapper branch reported it missing.
+ - [ ] The source-of-truth file is under 200 lines and passes sections 1–3 and 5–7 of `references/agents-md-checklist.md`. Wrappers and rules files pass sections 1–3 and 6.
+ - [ ] No rule appears in both `AGENTS.md` and a CLAUDE file.
+ - [ ] New content has no anti-pattern from `references/anti-patterns.md`.
+ - [ ] Write runs end with `Result: PASS`. Audit runs report every checklist item, give each failing line a routing recommendation, leave `git status` unchanged, and end with the overall verdict.
## Expected Output
- **For `create` / `update`:** writes the chosen target; when the user said "both", writes two files (`AGENTS.md` plus a thin `CLAUDE.md` wrapper that opens with `@AGENTS.md` and does not copy the token block). Example tail of the source-of-truth file:
-
- ```markdown
- ## Token Efficiency
- - Never re-read files you just wrote or edited. You know the contents.
- - Never re-run commands to "verify" unless the outcome was uncertain.
- ... (rest of token-efficiency block)
- ```
-
- Followed by a step-completion report ending in `Result: PASS`.
-
- **For `audit`:** prints a markdown report (no file writes) covering every checklist section, e.g.:
+ | Branch | Files after the run |
+ |---|---|
+ | agents-only | `AGENTS.md`: Commands, Constraints, Done when, any optional sections, then `## Token Efficiency` |
+ | migrate / wrapper | `AGENTS.md` as above, plus each CLAUDE file reduced to the `@AGENTS.md` import and its Claude-only lines |
+ | claude-only | `CLAUDE.md` with the full content and the token block |
+ | audit | no writes; a checklist report with routing, ending `Result: PASS`, `PARTIAL`, or `FAIL` |
- ```
- ◆ Audit (step 1 of 1)
- Length budget: √ pass — 64 lines
- Content quality: × fail — 3 fluff lines ("be a senior engineer", motivational)
- Routing: × fail — 12-line deploy runbook belongs in a skill
- Enforceability: × fail — "never commit .env" has no PreToolUse hook
- 5 required sections: × fail — missing "Constraints" and "Done when"
- Drift: × fail — 2 rules duplicated in AGENTS.md
- Anti-patterns: × fail — found 2 (generic style rules)
- Token block: × fail — missing
- Result: PARTIAL
- ```
+ A sample file is in `references/agents-md-writing.md`. A sample audit report is in `references/agents-md-checklist.md`.
## Edge Cases
- - **No existing CLAUDE.md and `update` requested** → fall back to `create`, confirm with user first.
- - **Both root and child `CLAUDE.md` exist** → ask which scope to edit; never silently overwrite both.
- - **Dirty working tree** → stash backup before sync; if `stash pop` conflicts, stop and ask.
- - **Missing `origin`** → skip sync, warn user, require explicit confirmation to proceed.
- - **User pastes raw `$ARGUMENTS`** with no recognised verb → ask which mode (create/update/audit).
- - **AGENTS.md already exists and user asks for CLAUDE.md** → write the wrapper (`@AGENTS.md` + Claude-only extras), never a duplicate of the shared rules.
- - **Target is a personal file (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`)** → audit and propose only; never rewrite a user's personal file from a repo-scoped run.
- - **Monorepo** → propose nested per-package files rather than growing the root file.
- - **Requested content is a multi-step procedure** → decline to inline it; propose a skill and leave a one-line pointer.
- - **Generated file would exceed 200 lines** → reject; path-scope, extract to a skill, or link out instead.
-
- ## Anti-Patterns to Avoid
-
- See `references/anti-patterns.md` for the full list (style rules linters cover, generic advice, file-by-file dumps, etc.).
+ - **Monorepo**: prefer one `AGENTS.md` per package over a growing root file. Codex and most agents give priority to the closest file. Claude reads the root file plus each subdirectory's file on demand, and a CLAUDE file shadows the `AGENTS.md` in its own directory. Ask which scope to edit.
+ - **A CLAUDE file that tells Claude in prose to read `AGENTS.md`, or holds a pasted copy of it** (from `/init` or `/import`): it lacks the import, so migrate it.
+ - **A request for `AGENTS.override.md` or `AGENTS.local.md`**: Codex reads `AGENTS.override.md` *instead of* that directory's `AGENTS.md`, and Claude reads neither. Say so before writing one.
+ - **Personal files** (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`): audit and propose only. Never rewrite a personal file from a repo-scoped run.
+ - **A multi-step procedure**: don't inline it. Propose a skill, and leave a one-line pointer.
+ - **A draft over 200 lines**: path-scope rules, extract procedures to a skill, or link out before writing.