Instruction files
Claude Code instruction files are context, not configuration. Every file that loads is concatenated into the conversation; nothing overrides anything, conflicts are resolved arbitrarily, and nothing in prose is enforced. The work is to keep the fewest, truest, most concrete lines in the place that loads exactly when they are needed, to cut what Claude would do anyway, and to move what must never bend into hooks, permission rules or settings.
Loader details (what loads when, glob bases, size limits, AGENTS.md interplay) change between releases and differ from most blog posts and generators. They are in references/loading-semantics.md, checked against the docs and changelog through Claude Code v2.1.312 on 2026-10-28. Read it before stating how loading works; when claude --version is newer, check the changelog for CLAUDE.md, rules and paths entries after v2.1.312. Never answer loader questions from memory.
Standing behavior: read, understand, act, surface
This applies to every request, from "add one line" to a full audit, and it is what the user relies on this skill for. They should never have to ask for it.
- Read the effective set first. Every file that loads alongside the one in question (user scope, ancestors, root, CLAUDE.local.md, always-on and relevant scoped rules, nested files, imports, AGENTS.md), plus the repository facts the instructions talk about. Run the checker.
- Understand it as one document. Compare across files by subject: contradictions, semantic duplicates, diverging details, ambiguity, scope mismatches, stale facts, procedures, fought-over lines, lines that change nothing because Claude already behaves that way, and instructions that sit at the wrong level (personal rules in a project, a project rule repeating a user-level rule, team rules copied across repositories that a shared linked rules directory or a plugin would serve better).
- Do what was asked, in the right place and without creating a duplicate or contradiction.
- Surface what you found, even outside the request, in a short "Noticed while doing this" section: each item with its evidence and a recommendation. Offer the fix; do not apply changes the user did not ask for. The user has the last word, especially on deletions.
- Route every finding through its reference before you write it. This summary is not enough to recommend a fix: the references carry the caveats a correct recommendation depends on (which procedures must be user-invoked only, why a rule with
paths linked from outside the working directory never loads, why a deny rule would also block new migrations, which lines Claude Code already makes redundant). Open the reference for each kind of finding the first time it appears, even when the finding itself seems obvious (list under "How to use these references").
Scale the depth: a one-line addition gets a focused read of the subjects it touches and a short noticed list (with an offer of a full audit when the set looks unhealthy); a review or audit gets the full cross-file analysis.
Core facts to hold in every task
- Load timing: CLAUDE.md and CLAUDE.local.md in the working directory and above,
~/.claude/CLAUDE.md, unscoped rules in the .claude/rules/ of the launch directory and of every directory above it, and in ~/.claude/rules/, and all their @imports load at launch. Subdirectory CLAUDE.md files, rules in a subdirectory's own .claude/rules/, and rules with paths load on demand when Claude reads, writes or edits a matching file. Most subagents receive the same files. Explore and Plan start with none of them, managed policy files and project rules included; agents with omitClaudeMd keep only the managed policy files. In all three, a subdirectory's CLAUDE.md and matching scoped rules still load when they touch files there. Rules with paths also load on a single-file Bash read (cat, nl, bat, batcat, head, tail, sed -n 'X,Yp', grep, egrep, fgrep or rg on one file, with no pipes or redirects).
- Rules frontmatter:
paths is the only field read. Other keys (globs, alwaysApply, description, priority) are ignored silently. Invalid YAML makes the rule load in every session; an unquoted glob starting with *, { or [ is a common cause, so quote globs. Folder names do not scope rules. .md backups inside .claude/rules/ load too.
- Glob base: project rule patterns are relative to the directory holding the rule's
.claude folder; user rule patterns to the session's working directory. A pattern with no / matches at any depth (*.md), a leading / anchors it to the base (/*.md, /package.json), and a pattern with a / inside is relative to the base (src/components/*.tsx).
- Size: under 200 lines per CLAUDE.md is guidance, not truncation; on-demand files (and their imports) are cut at 40,000 characters on a 200K window (150,000 on current 1M-window models); a CLAUDE.md over 4 MiB is skipped. Imports never save context.
- Placement by applicability: conventions for one area or file type belong in a rule with
paths, however short, so they load with the files they govern; what is needed in most tasks or before files are chosen stays in CLAUDE.md.
- Enforcement: a zero-exception rule belongs in a hook (a
command hook blocks with exit 2) or a permissions.deny rule; prose only informs, and emphasis does not enforce.
Route the request
| Situation |
Read and follow |
| Any write or edit, including "add this to CLAUDE.md" or "remember X" |
references/writing-guide.md: the pre-write protocol at the top, then the writing rules |
| Deciding where something belongs; what Claude would do anyway |
references/placement.md |
| Review or audit of CLAUDE.md and/or rules |
references/audit-and-refactor.md, references/cross-file-analysis.md and references/rules-architecture.md (where each instruction belongs, always-on versus paths) |
Saturated CLAUDE.md, refactor, CLAUDE.md vs rules, organizing rules, always-on vs paths, sharing rules across projects (user-level rules, symlinked shared rules, plugins) |
references/rules-architecture.md |
| "Claude keeps doing X", "make sure this doesn't happen again", persisting a correction |
references/escalation.md |
| Steps, runbooks, checklists or repeated workflows in instruction files |
references/procedures-to-skills.md |
| Layout (bullets, numbered steps, tables, prose), imports versus pointers, pointers between rules, brace globs |
references/format-and-links.md |
| How or when something loads; debugging a rule that doesn't apply |
references/loading-semantics.md |
Most real requests touch several rows; read each that applies.
How to use these references
- Read a reference in full (each is under 200 lines) the first time its situation applies, and before you write the part of the answer that depends on it. Do not read it in fragments or rely on its title.
- Do not read every reference up front. Start with the rows the request names, then re-route as evidence appears: a contradiction or duplicate found while writing sends you to cross-file-analysis.md; a numbered procedure to procedures-to-skills.md; a fought-over or zero-exception rule to escalation.md; a loader question (frontmatter, globs, timing, size) to loading-semantics.md; a saturated file or a CLAUDE.md-versus-rules decision to rules-architecture.md.
- Keep going after the first finding. The analysis is complete when every file in the comparison set has been read and every kind of problem you report has gone through its reference.
- The checker ends its report with the references its findings need ("Read before reporting"); read those before you write about the findings.
- Before sending the reply, check each kind of finding in it against this list and read any reference you have not read in this session; then revise the finding with what it says (the references hold the fix patterns, the caveats and what to ask the user):
- contradiction, duplicate, ambiguity, scope mismatch, no-op line → cross-file-analysis.md and placement.md;
- procedure, checklist, repeated workflow → procedures-to-skills.md;
- repeated misbehavior, emphasis, enforcement → escalation.md;
- what stays in CLAUDE.md, rules organization, always-on vs
paths, sharing across repositories → rules-architecture.md;
- imports, pointers between files, tables and list formats, brace globs → format-and-links.md;
- frontmatter, globs, load timing, size → loading-semantics.md.
- For a large set or a substantial refactor, a fresh-context review by the
instruction-engineering:reviewer agent (when available) checks your result without inheriting your reasoning.
Workflow
1. Identify the operation and the scope
Operation: write, edit, review or audit (read-only until approved), debug, reorganize, refactor, persist a correction. Scope: user (~/.claude/ or $CLAUDE_CONFIG_DIR; affects every repository; get explicit approval and keep a copy before changing it), project (shared through git), local (CLAUDE.local.md), subtree, file type. If the deliverable is truly ambiguous (report vs edited files, which scope), ask once; otherwise proceed and state the interpretation.
2. Gather the effective set and the ground truth
Run the checker for a deterministic inventory and findings (read-only; python3 3.12+):
python3 "${CLAUDE_SKILL_DIR}/scripts/check_instructions.py" --project <repo root>
${CLAUDE_SKILL_DIR} is the directory that contains this SKILL.md. --match <file> ... lists which scoped rules would load for given files (positive and negative scope tests); --json gives structured output; --no-user skips ~/.claude; --user-dir <dir> points at another configuration directory. Errors are loader facts; warnings and the heuristic findings (near-duplicates, conflicting choices, procedures, scope candidates, generic lines, layout trees, style lines a formatter config already enforces, prohibitions without an alternative) are leads to confirm by reading. The checker cannot judge meaning: the cross-file analysis is yours.
3. Decide placement before wording
Apply the admission test in placement.md, starting with the counterfactual (would Claude act differently without this line?). Open the classification rubric in rules-architecture.md when the home is not obvious from placement.md, or when the change is structural. A procedure goes to a skill, a zero-exception rule to a hook or deny rule (proposed), personal content to CLAUDE.local.md or user scope, and no-op content nowhere.
4. Write, reorganize or refactor
Follow the pre-write protocol and writing rules in writing-guide.md. For structural work, present the target structure, the keep / migrate / delete table and the always-loaded footprint before and after (rules-architecture.md section 5); apply directly only when the user asked for the change itself. Every rule file gets a quoted paths list or a deliberate decision to stay always-on, and each glob is checked with --match against a file that should load it and one that should not.
Files under .claude/ (all rules) are protected paths. In default and acceptEdits modes each write prompts (the prompt offers to allow the folder for the session); in auto mode the classifier decides; in dontAsk the write is denied; allow rules do not pre-approve it. Group rule writes so the user can approve the folder once. When a write is denied, do not route around it (no shell redirection, no copies elsewhere): deliver the target structure plus every new or changed file's complete content, ready to apply, and say that nothing under .claude/ changed.
5. Verify and report
- Re-run the checker on the final set after any change; explain any remaining error. Re-read each changed file in full.
- Give the session checks the tools here cannot run:
/context after a fresh launch, a Loaded line or an InstructionsLoaded hook for scoped rules, claude --debug for parse errors, optionally /doctor prompt-audit (v2.1.283+).
- Report: what changed and why; what was kept, moved, merged or removed (traceability); checker result before and after; what was verified and how, and what was not; recommended mechanism changes not applied (skills, hooks, deny rules, settings); and "Noticed while doing this".
- Never claim an instruction "will be followed" or "is loaded" without evidence; say what would show it.
Boundaries
- Do not change settings, hooks, permissions, skills or source code as a side effect. Recommend them with the reason and an exact sketch; create them only when asked or approved.
- Do not delete instructions the user did not ask to remove; recommend it with the reason.
- Do not put secrets, credentials or customer data in any instruction file, including CLAUDE.local.md.
- Do not adopt a generator's score, line cap or invented frontmatter as a requirement; the official loader behavior and the user's tasks decide.
- When a request is weaker than an alternative (a stack mandate in user scope, an IMPORTANT line for a rule that keeps being broken, a duplicate of a rule that already exists), say so in one sentence, recommend the stronger option, then do what was asked unless it would add a contradiction or duplicate or leak private content into a shared file.
1---2name: claude-md-and-rules3description: Required before creating or changing any Claude Code instruction file (CLAUDE.md, CLAUDE.local.md, ~/.claude/CLAUDE.md, .claude/rules/**/*.md), even a one-line addition, because every change must be checked against the whole instruction set first. Also use it to review, audit, debug, reorganize or refactor these files; whenever the user wants a behavior persisted ("remember this", "make sure this doesn't happen again", "Claude keeps doing X", "make it stop"), including before configuring a hook for it, to find why the written instruction failed; when a rule is ignored or not loading; or when they mention project or global instructions or memory files. Finds contradictions, semantic duplicates, ambiguity, no-op and misplaced lines and procedures that should be skills; decides CLAUDE.md vs always-on or path-scoped rules vs skill vs hook; includes a read-only checker. Not for writing skills, hooks, settings, READMEs or one-off prompts, except to recommend them.4compatibility: Claude Code or Cowork. The checker needs python3 3.12+; git is optional.5metadata:6 source: https://skillmd.com/skills/nerymurillohnd/claude-md-and-rules7---89# Instruction files1011Claude Code instruction files are context, not configuration. Every file that loads is concatenated into the conversation; nothing overrides anything, conflicts are resolved arbitrarily, and nothing in prose is enforced. The work is to keep the fewest, truest, most concrete lines in the place that loads exactly when they are needed, to cut what Claude would do anyway, and to move what must never bend into hooks, permission rules or settings.1213Loader details (what loads when, glob bases, size limits, AGENTS.md interplay) change between releases and differ from most blog posts and generators. They are in [references/loading-semantics.md](references/loading-semantics.md), checked against the docs and changelog through Claude Code v2.1.312 on 2026-10-28. Read it before stating how loading works; when `claude --version` is newer, check the changelog for `CLAUDE.md`, `rules` and `paths` entries after v2.1.312. Never answer loader questions from memory.1415## Standing behavior: read, understand, act, surface1617This applies to every request, from "add one line" to a full audit, and it is what the user relies on this skill for. They should never have to ask for it.18191. **Read the effective set first.** Every file that loads alongside the one in question (user scope, ancestors, root, CLAUDE.local.md, always-on and relevant scoped rules, nested files, imports, AGENTS.md), plus the repository facts the instructions talk about. Run the checker.202. **Understand it as one document.** Compare across files by subject: contradictions, semantic duplicates, diverging details, ambiguity, scope mismatches, stale facts, procedures, fought-over lines, lines that change nothing because Claude already behaves that way, and instructions that sit at the wrong level (personal rules in a project, a project rule repeating a user-level rule, team rules copied across repositories that a shared linked rules directory or a plugin would serve better).213. **Do what was asked**, in the right place and without creating a duplicate or contradiction.224. **Surface what you found**, even outside the request, in a short "Noticed while doing this" section: each item with its evidence and a recommendation. Offer the fix; do not apply changes the user did not ask for. The user has the last word, especially on deletions.235. **Route every finding through its reference before you write it.** This summary is not enough to recommend a fix: the references carry the caveats a correct recommendation depends on (which procedures must be user-invoked only, why a rule with `paths` linked from outside the working directory never loads, why a deny rule would also block new migrations, which lines Claude Code already makes redundant). Open the reference for each kind of finding the first time it appears, even when the finding itself seems obvious (list under "How to use these references").2425Scale the depth: a one-line addition gets a focused read of the subjects it touches and a short noticed list (with an offer of a full audit when the set looks unhealthy); a review or audit gets the full cross-file analysis.2627## Core facts to hold in every task2829- **Load timing**: CLAUDE.md and CLAUDE.local.md in the working directory and above, `~/.claude/CLAUDE.md`, unscoped rules in the `.claude/rules/` of the launch directory and of every directory above it, and in `~/.claude/rules/`, and all their `@imports` load at launch. Subdirectory CLAUDE.md files, rules in a subdirectory's own `.claude/rules/`, and rules with `paths` load on demand when Claude reads, writes or edits a matching file. Most subagents receive the same files. Explore and Plan start with none of them, managed policy files and project rules included; agents with `omitClaudeMd` keep only the managed policy files. In all three, a subdirectory's CLAUDE.md and matching scoped rules still load when they touch files there. Rules with `paths` also load on a single-file Bash read (`cat`, `nl`, `bat`, `batcat`, `head`, `tail`, `sed -n 'X,Yp'`, `grep`, `egrep`, `fgrep` or `rg` on one file, with no pipes or redirects).30- **Rules frontmatter**: `paths` is the only field read. Other keys (`globs`, `alwaysApply`, `description`, `priority`) are ignored silently. Invalid YAML makes the rule load in every session; an unquoted glob starting with `*`, `{` or `[` is a common cause, so quote globs. Folder names do not scope rules. `.md` backups inside `.claude/rules/` load too.31- **Glob base**: project rule patterns are relative to the directory holding the rule's `.claude` folder; user rule patterns to the session's working directory. A pattern with no `/` matches at any depth (`*.md`), a leading `/` anchors it to the base (`/*.md`, `/package.json`), and a pattern with a `/` inside is relative to the base (`src/components/*.tsx`).32- **Size**: under 200 lines per CLAUDE.md is guidance, not truncation; on-demand files (and their imports) are cut at 40,000 characters on a 200K window (150,000 on current 1M-window models); a CLAUDE.md over 4 MiB is skipped. Imports never save context.33- **Placement by applicability**: conventions for one area or file type belong in a rule with `paths`, however short, so they load with the files they govern; what is needed in most tasks or before files are chosen stays in CLAUDE.md.34- **Enforcement**: a zero-exception rule belongs in a hook (a `command` hook blocks with exit 2) or a `permissions.deny` rule; prose only informs, and emphasis does not enforce.3536## Route the request3738| Situation | Read and follow |39| :-- | :-- |40| Any write or edit, including "add this to CLAUDE.md" or "remember X" | [references/writing-guide.md](references/writing-guide.md): the pre-write protocol at the top, then the writing rules |41| Deciding where something belongs; what Claude would do anyway | [references/placement.md](references/placement.md) |42| Review or audit of CLAUDE.md and/or rules | [references/audit-and-refactor.md](references/audit-and-refactor.md), [references/cross-file-analysis.md](references/cross-file-analysis.md) and [references/rules-architecture.md](references/rules-architecture.md) (where each instruction belongs, always-on versus `paths`) |43| Saturated CLAUDE.md, refactor, CLAUDE.md vs rules, organizing rules, always-on vs `paths`, sharing rules across projects (user-level rules, symlinked shared rules, plugins) | [references/rules-architecture.md](references/rules-architecture.md) |44| "Claude keeps doing X", "make sure this doesn't happen again", persisting a correction | [references/escalation.md](references/escalation.md) |45| Steps, runbooks, checklists or repeated workflows in instruction files | [references/procedures-to-skills.md](references/procedures-to-skills.md) |46| Layout (bullets, numbered steps, tables, prose), imports versus pointers, pointers between rules, brace globs | [references/format-and-links.md](references/format-and-links.md) |47| How or when something loads; debugging a rule that doesn't apply | [references/loading-semantics.md](references/loading-semantics.md) |4849Most real requests touch several rows; read each that applies.5051### How to use these references5253- Read a reference in full (each is under 200 lines) the first time its situation applies, and before you write the part of the answer that depends on it. Do not read it in fragments or rely on its title.54- Do not read every reference up front. Start with the rows the request names, then re-route as evidence appears: a contradiction or duplicate found while writing sends you to cross-file-analysis.md; a numbered procedure to procedures-to-skills.md; a fought-over or zero-exception rule to escalation.md; a loader question (frontmatter, globs, timing, size) to loading-semantics.md; a saturated file or a CLAUDE.md-versus-rules decision to rules-architecture.md.55- Keep going after the first finding. The analysis is complete when every file in the comparison set has been read and every kind of problem you report has gone through its reference.56- The checker ends its report with the references its findings need ("Read before reporting"); read those before you write about the findings.57- Before sending the reply, check each kind of finding in it against this list and read any reference you have not read in this session; then revise the finding with what it says (the references hold the fix patterns, the caveats and what to ask the user):58 - contradiction, duplicate, ambiguity, scope mismatch, no-op line → cross-file-analysis.md and placement.md;59 - procedure, checklist, repeated workflow → procedures-to-skills.md;60 - repeated misbehavior, emphasis, enforcement → escalation.md;61 - what stays in CLAUDE.md, rules organization, always-on vs `paths`, sharing across repositories → rules-architecture.md;62 - imports, pointers between files, tables and list formats, brace globs → format-and-links.md;63 - frontmatter, globs, load timing, size → loading-semantics.md.64- For a large set or a substantial refactor, a fresh-context review by the `instruction-engineering:reviewer` agent (when available) checks your result without inheriting your reasoning.6566## Workflow6768### 1. Identify the operation and the scope6970Operation: write, edit, review or audit (read-only until approved), debug, reorganize, refactor, persist a correction. Scope: user (`~/.claude/` or `$CLAUDE_CONFIG_DIR`; affects every repository; get explicit approval and keep a copy before changing it), project (shared through git), local (CLAUDE.local.md), subtree, file type. If the deliverable is truly ambiguous (report vs edited files, which scope), ask once; otherwise proceed and state the interpretation.7172### 2. Gather the effective set and the ground truth7374Run the checker for a deterministic inventory and findings (read-only; python3 3.12+):7576```bash77python3 "${CLAUDE_SKILL_DIR}/scripts/check_instructions.py" --project <repo root>78```7980`${CLAUDE_SKILL_DIR}` is the directory that contains this SKILL.md. `--match <file> ...` lists which scoped rules would load for given files (positive and negative scope tests); `--json` gives structured output; `--no-user` skips `~/.claude`; `--user-dir <dir>` points at another configuration directory. Errors are loader facts; warnings and the heuristic findings (near-duplicates, conflicting choices, procedures, scope candidates, generic lines, layout trees, style lines a formatter config already enforces, prohibitions without an alternative) are leads to confirm by reading. The checker cannot judge meaning: the cross-file analysis is yours.8182### 3. Decide placement before wording8384Apply the admission test in placement.md, starting with the counterfactual (would Claude act differently without this line?). Open the classification rubric in rules-architecture.md when the home is not obvious from placement.md, or when the change is structural. A procedure goes to a skill, a zero-exception rule to a hook or deny rule (proposed), personal content to CLAUDE.local.md or user scope, and no-op content nowhere.8586### 4. Write, reorganize or refactor8788Follow the pre-write protocol and writing rules in writing-guide.md. For structural work, present the target structure, the keep / migrate / delete table and the always-loaded footprint before and after (rules-architecture.md section 5); apply directly only when the user asked for the change itself. Every rule file gets a quoted `paths` list or a deliberate decision to stay always-on, and each glob is checked with `--match` against a file that should load it and one that should not.8990Files under `.claude/` (all rules) are protected paths. In default and `acceptEdits` modes each write prompts (the prompt offers to allow the folder for the session); in auto mode the classifier decides; in `dontAsk` the write is denied; allow rules do not pre-approve it. Group rule writes so the user can approve the folder once. When a write is denied, do not route around it (no shell redirection, no copies elsewhere): deliver the target structure plus every new or changed file's complete content, ready to apply, and say that nothing under `.claude/` changed.9192### 5. Verify and report9394- Re-run the checker on the final set after any change; explain any remaining error. Re-read each changed file in full.95- Give the session checks the tools here cannot run: `/context` after a fresh launch, a `Loaded` line or an InstructionsLoaded hook for scoped rules, `claude --debug` for parse errors, optionally `/doctor prompt-audit` (v2.1.283+).96- Report: what changed and why; what was kept, moved, merged or removed (traceability); checker result before and after; what was verified and how, and what was not; recommended mechanism changes not applied (skills, hooks, deny rules, settings); and "Noticed while doing this".97- Never claim an instruction "will be followed" or "is loaded" without evidence; say what would show it.9899## Boundaries100101- Do not change settings, hooks, permissions, skills or source code as a side effect. Recommend them with the reason and an exact sketch; create them only when asked or approved.102- Do not delete instructions the user did not ask to remove; recommend it with the reason.103- Do not put secrets, credentials or customer data in any instruction file, including CLAUDE.local.md.104- Do not adopt a generator's score, line cap or invented frontmatter as a requirement; the official loader behavior and the user's tasks decide.105- When a request is weaker than an alternative (a stack mandate in user scope, an IMPORTANT line for a rule that keeps being broken, a duplicate of a rule that already exists), say so in one sentence, recommend the stronger option, then do what was asked unless it would add a contradiction or duplicate or leak private content into a shared file.