claude-md

What this skill does

# CLAUDE.md Instruction Quality

**CLAUDE.md is a prompt that persists across every session.** All prompt engineering principles apply, but the failure
modes are specific: instructions exist but get ignored, content drifts from reality, and the file grows until nothing
gets followed. The goal is not completeness — it's compliance. A short CLAUDE.md that Claude follows beats a full one it
ignores.

## Route to Reference

- **Scaffold, section ordering, creation workflow** — [`${CLAUDE_SKILL_DIR}/references/scaffold.md`] Canonical section
  order with examples (identity → structure → stack → conventions → verification → constraints), creation-from-scratch
  workflow, monorepo scaffold patterns

## What Belongs in CLAUDE.md

CLAUDE.md is for **project-specific instructions that change Claude's default behavior**. If removing an instruction
wouldn't change output quality, it doesn't belong.

**Include:**

- Project structure — key directories, module boundaries, entry points
- Tech stack and tooling — frameworks, test runners, package managers, build tools
- Coding conventions that differ from language defaults — naming, import style, error handling patterns
- Verification workflows — how to run tests, lint, build; what commands to use
- Critical constraints — "never modify X", "always do Y before Z"
- Non-obvious gotchas — things Claude would get wrong without being told

**Exclude:**

- Generic best practices Claude already knows ("write clean code", "use meaningful names", "follow SOLID")
- Language fundamentals ("use strict mode in TypeScript") — these belong in language skills
- Procedural workflows with strict ordering — these belong in skills
- Domain expertise — skills are the right artifact for behavioral rules tied to a specific domain
- Ephemeral state — current sprint goals, in-progress migrations, temporary flags (use memory or tasks)
- Automated behaviors — "whenever X happens, do Y" requires hooks in settings.json, not instructions

### The Layer Routing Decision

Content belongs in the layer where it's most effective:

- **CLAUDE.md** — project identity, structure, conventions, constraints. Read at session start, shapes all work.
- **`.claude/rules/`** — file-type-specific or path-scoped conventions. Lighter than skills (no SKILL.md ceremony),
  conditionally loaded via glob `paths` frontmatter. Rules without `paths` load unconditionally like CLAUDE.md; rules
  with `paths` load on-demand when Claude reads matching files. All rule files must live at the project root — no
  per-package directories in monorepos. Use for conventions that apply to specific file types or directories but don't
  warrant a full skill.
- **Skills** — domain expertise, procedural workflows, behavioral rules for specific task types. Loaded on demand.
- **Hooks** — automated enforcement, validation gates, triggered actions. Execute without Claude deciding.
- **Settings** — permissions, env vars, model config. Structural, not instructional.
- **Memory** — user preferences, cross-session context, project state. Recalled when relevant.

**The test:** If it's a rule Claude must follow in every task regardless of domain → CLAUDE.md. If it's a rule scoped to
specific file types or paths → `.claude/rules/`. If it's a rule for a specific type of work → skill. If it must happen
automatically without Claude's judgment → hook.

## Writing Effective Instructions

### Concrete Over Abstract

Every instruction must be specific enough that Claude can verify compliance.

- **Good:** `Use Vitest for all tests. Test files live in __tests__/ adjacent to source.`
- **Bad:** `Write comprehensive tests for all changes.`
- **Good:** `Run yarn lint && yarn test before committing. Fix all errors.`
- **Bad:** `Ensure code quality before committing.`
- **Good:** `API routes use kebab-case: /api/user-settings, not /api/userSettings.`
- **Bad:** `Follow consistent naming conventions.`

The test: could two different agents reading this instruction produce different behavior? If yes, it's too vague.

### Observable Over Aspirational

Instructions must describe behaviors Claude can actually perform, not qualities it should aspire to.

- **Observable:** `Every public function has a JSDoc comment with @param and @returns.`
- **Aspirational:** `Write thorough documentation.`
- **Observable:** `Prefer composition over inheritance. No class hierarchies deeper than 2.`
- **Aspirational:** `Use good object-oriented design.`

### Brevity = Compliance

Every token in CLAUDE.md competes for attention. Shorter CLAUDE.md files produce higher instruction adherence.

- State each rule once, in the section where it's contextually relevant
- Prefer bullet lists over prose paragraphs — they're faster to scan and harder to miss
- If a section exceeds 15-20 bullet points, it's likely mixing concerns — split by topic or move depth to a skill
- Delete rules that pass the deletion test (removing them doesn't change behavior)

### Prose vs Bullet Lists

**Prose (1-3 paragraphs) for project identity only.** A brief "what is this project and why does it exist" section at
the top orients Claude for edge cases where rules don't cover the situation. This is the one place where explaining
_why_ earns its tokens — understanding project intent helps the model make correct judgment calls.

**Bullet lists for all operational rules.** Conventions, constraints, commands, verification workflows — everything
Claude must _do_ goes in bullet lists. Research consistently shows:

- Bullet lists increase signal density — critical rules can't hide inside paragraphs
- Prose introduces rhetorical padding that competes for attention without changing behavior
- Adding "because..." rationale to individual rules is actively harmful — it doubles the token cost of each rule while
  the model rarely needs the justification to follow it
- When the model encounters conflicting prose-wrapped rules, it produces mediocre compromises instead of following
  either rule strictly

**The split:** Top 10-15% of the file can be explanatory prose (project context). The remaining 85-90% should be
structured bullet lists organized by topic.

**Exception:** If a rule is genuinely counterintuitive and Claude would resist following it without understanding why, a
one-sentence rationale after the rule is acceptable. This is rare — most rules don't need justification, they need
clarity.

### Placement Matters

Models follow a U-shaped attention curve: beginning and end are followed most reliably, middle content degrades.

- **Top:** Project identity, structure, tech stack — the "what is this" framing
- **Middle:** Conventions, detailed rules by topic
- **Bottom:** Critical constraints, verification workflow — the "don't forget" reinforcement

For rules that must be followed, state them early AND reinforce at the end with different phrasing.

## The Multi-Layer Hierarchy

CLAUDE.md files cascade: subdirectory > project root > user global. Later files override earlier ones on the same topic.

- **Global (`~/.claude/CLAUDE.md`)** — personal defaults: communication preferences, tool preferences, workflow habits
  that apply across all projects
- **Project root (`./CLAUDE.md`)** — repo-specific: structure, stack, conventions, constraints. This is the primary
  file. Checked into version control, shared by the team.
- **Subdirectory (`./packages/api/CLAUDE.md`)** — module-specific overrides. Use sparingly — only when a module has
  conventions that genuinely differ from the project root (e.g., a Python service in a mostly-TypeScript monorepo).

**Don't repeat.** If the project root says "use Vitest", don't restate it in every subdirectory. Subdirectory files
should contain only what differs from or adds to the root.

## Progressive Disclosure

When a CLAUDE.md exceeds ~500 lines, instruction compliance degrades — the model can't attend to everything equally.
Progressive disclosure moves depth out of CLAUDE.md while preserving access to it.

### The 4-Bucket Classificatio