claude-md

name	claude-md
description	CLAUDE.md instruction quality: writing effective project instructions, diagnosing why Claude ignores rules, routing content to the right layer, progressive disclosure, and systematic improvement. Invoke whenever task involves any interaction with CLAUDE.md files — creating, writing, reviewing, auditing, improving, optimizing, or debugging instruction compliance.

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 → capability map → 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. Two tests, both mandatory: if removing an instruction wouldn't change output quality, it doesn't belong; if Claude can infer it by reading the codebase, it doesn't belong either.

Include:

• Capability map — which module owns which functionality ("auth lives in internal/auth, billing in services/billing"), where new code of each kind goes. An ownership map, not a directory tree — trees are inferable from the filesystem
• Tech stack and tooling — frameworks, test runners, package managers, build tools
• Coding conventions that differ from language defaults — naming, import style, error handling patterns
• Decisions as present-tense rules — "IDs are UUIDs — prevents enumeration, enables offline generation." One causal clause of why; chronology never
• 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)
• Project history — changelogs, session logs, past-work records, migration narratives, abandoned approaches. History lives in git log, the tracker, and ADRs; a described abandoned approach reads as a current option and gets resurrected
• Directory trees and file listings — anything reproducible with ls; state ownership and boundaries, not structure
• 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.

Instructions are not enforcement. Models route around soft constraints stated as prose — working from a different directory to dodge a path restriction, rephrasing to dodge a wording rule. Anything that must never happen goes in permissions, sandbox config, or hooks; CLAUDE.md states working defaults.

Where the record goes instead. The urge to write "what we did" into CLAUDE.md routes elsewhere: past work → commit messages and the tracker; a lesson from a single incident → memory, promoted to a CLAUDE.md rule only on recurrence; a decision → one present-tense rule here, with any why longer than a clause → an ADR the rule links to.

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.

Present Tense Only

CLAUDE.md describes the current state of the project — it never narrates how the project got here. Decisions enter as present-tense rules; the path to them stays in git log and ADRs.

• Past-tense narration is a defect: "we migrated from REST to gRPC" → "services communicate over gRPC"
• Temporal markers rot silently: "recently", "new", "now uses", "as of March" — delete the marker or the whole line
• A described abandoned approach reads as an available option — name only what is true now

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
• Rationale padding on mechanical rules is waste — "run yarn lint before committing" needs no justification, and explaining it doubles the rule's token cost
• 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.

Decisions carry a one-clause why. For contestable choices — "IDs are UUIDs — prevents enumeration, enables offline generation" — the causal clause improves the model's judgment between equivalent approaches and stops it from "fixing" the decision. One clause, present tense, causal not chronological. A why that needs more than a clause goes to an ADR the rule links to.

Lists over tables. Commands, conventions, and capability maps are independent entries — KV bullet lists, not tables. A table earns its place only when rows are compared across columns, which CLAUDE.md content almost never needs. Numbered lists only where order is the content.

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 concatenate into one context: user global, then project root, then subdirectory. Load order is not precedence — when layers conflict, Claude may follow either rule. Reconcile conflicts across layers instead of relying on "later wins."

• 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 Classification

For each section or block in the file, classify:

• Keep — stays in CLAUDE.md. Content that is high-frequency (used in most sessions), safety-critical (omission causes harm), easy-to-violate (Claude routinely gets wrong without the reminder), or security-sensitive (access control, data handling, secret management).
• Move to .claude/rules/ — useful but not needed every session. Path-scoped conventions, file-type-specific patterns, module-specific rules. Offloading to rules with glob paths frontmatter means they load only when relevant, reducing baseline context cost.
• Extract to skill — reusable behavioral patterns, procedural workflows, domain expertise that activates for specific task types. If a block describes "when doing X, follow these steps" — it's a skill candidate.
• Remove — outdated content, rules Claude follows by default, duplicated instructions restated in different words, rationale paragraphs that don't change behavior.

Exception Criteria

Even infrequently used content stays in CLAUDE.md if it meets any exception:

• Safety-critical — violating it causes data loss, security breach, or broken production
• Easy-to-violate — Claude consistently gets it wrong without the instruction, regardless of frequency
• Security-sensitive — governs authentication, authorization, secret handling, or data exposure

The goal is to maximize LLM working efficiency, not minimize line count. A 600-line file where every instruction earns its place outperforms a 200-line file that moved critical rules to rarely-loaded references.

When to Apply

• CLAUDE.md exceeds ~500 lines
• Claude ignores rules that exist in the file (attention overload signal)
• Multiple unrelated domains share a single file (mixing concerns)
• A human can't skim the file in under 60 seconds

Creating a CLAUDE.md

When building a CLAUDE.md from scratch, follow the canonical section ordering: project identity (prose) → capability map → stack and tooling → conventions (bullets) → verification workflow → critical constraints. This ordering exploits the U-shaped attention curve — identity anchors the top, constraints anchor the bottom.

Start minimal (50-100 lines) and iterate from actual usage. A CLAUDE.md created from static analysis is a starting point — the real improvements come from observing where Claude gets things wrong during work.

Key principles for initial creation:

• Detect project signals from config files (package.json, go.mod, Makefile, CI configs, linter configs)
• Map capabilities to locations — which module owns what and where new code goes, not a directory tree
• Identify conventions that differ from language defaults — these are what Claude needs to be told
• Apply the deletion test before delivering — remove everything Claude does correctly without instruction
• For monorepos, shared conventions go in root CLAUDE.md; package-specific rules go in nested CLAUDE.md files or glob-scoped .claude/rules/

Full section ordering with examples, creation workflow, and monorepo scaffold patterns: see [${CLAUDE_SKILL_DIR}/references/scaffold.md].

Diagnosing Instruction Failures

When Claude ignores CLAUDE.md rules, the cause is almost always one of these:

Buried in Noise

The instruction exists but Claude doesn't follow it. The file is too long, the rule is buried in the middle after hundreds of tokens of context, and attention has decayed.

Diagnosis: The file is painful for a human to skim in under 60 seconds. Critical rules sit inside prose paragraphs rather than standalone bullets. Multiple sections restate the same thing in different words.

Fix: Ruthlessly prune. Move anything Claude already knows by default. Promote buried rules to the top or bottom. Convert prose to bullet lists.

Too Vague

Claude produces plausible but wrong output — right code style, wrong location; idiomatic patterns, wrong framework.

Diagnosis: Instructions use abstract language ("clean code", "good tests", "consistent naming") without repo-specific specifics. Architecture descriptions are slogans ("hexagonal architecture") without file paths.

Fix: Replace every abstract instruction with a concrete, verifiable directive. Add file paths, command names, and specific patterns.

Stale

Claude references files that don't exist, suggests deprecated patterns, or proposes tooling the team abandoned.

Diagnosis: CLAUDE.md mentions old frameworks, directory names, or commands. Major architecture shifts never made it into the file. No one updates it alongside code changes. Past-tense narration and temporal markers ("recently", "now uses") are the early warning.

Fix: Audit against the actual codebase. Remove dead references. Add a convention: update CLAUDE.md alongside architecture changes, not as a separate task.

Contradictory

Claude's behavior varies between sessions — sometimes adds tests, sometimes doesn't; sometimes uses one tool, sometimes another.

Diagnosis: Different sections disagree. Copy-paste over months introduced conflicting rules. CI scripts embed instructions that override CLAUDE.md.

Fix: Search for opposing directives on the same topic. Establish one canonical rule per concern. Audit hooks and CI for shadow instructions.

Wrong Artifact

An instruction is in CLAUDE.md but should be in a skill, hook, or settings. Claude follows it inconsistently because CLAUDE.md rules compete for attention across all tasks, while the rule only matters for specific work.

Diagnosis: Rules like "when writing tests, always..." or "when reviewing PRs, follow this checklist..." — these are domain-specific behavioral rules that belong in skills, where they load only when relevant.

Fix: Move domain-specific instructions to skills. Move automated behaviors to hooks. Keep only universal project rules in CLAUDE.md.

Improvement Workflow

When improving a CLAUDE.md, follow this sequence:

1. Read the file and the codebase it describes. Verify that every instruction matches reality — file paths exist, commands work, tools are current.
2. Apply the deletion test. For each instruction, ask: "If I remove this, would Claude's output quality change?" If not, delete it. Pay special attention to generic advice Claude already follows by default.
3. Check for contradictions. Search for opposing rules on the same topic. Search hooks and CI configs for shadow instructions that conflict.
4. Assess specificity. Replace abstract instructions with concrete, verifiable directives. If an instruction can't be made concrete, it probably doesn't belong.
5. Route misplaced content. Move domain-specific rules to skills, automated behaviors to hooks, ephemeral state to memory.
6. Restructure for attention. Put project identity at the top. Put critical constraints and verification at the bottom. Use bullet lists, not prose.
7. Verify the result. The improved file should be skimmable in under 60 seconds and every instruction should be something Claude would get wrong without it.

Critical Rules

• Deletion test is mandatory. Every instruction must measurably change Claude's behavior. Generic advice that restates defaults wastes tokens and reduces compliance with rules that actually matter.
• Concrete and verifiable. If two agents could interpret an instruction differently, it's too vague. Add file paths, command names, and specific patterns.
• Right layer for the content. Domain expertise → skills. Path-scoped conventions → .claude/rules/. Automated behaviors → hooks. Hard boundaries → permissions and hooks, never instructions. Project-universal rules → CLAUDE.md. Misplaced content degrades everything.
• Present tense, no history. CLAUDE.md states what is true now. Changelogs, session logs, migration narratives, and abandoned approaches go to git log, the tracker, or ADRs — never here.
• Progressive disclosure over monolithic growth. When CLAUDE.md exceeds ~500 lines, classify content into keep/move/extract/remove buckets. Safety-critical and easy-to-violate content stays regardless of frequency.
• Maintain alongside code. CLAUDE.md that drifts from reality is worse than no CLAUDE.md — it produces confidently wrong output. Update it when architecture, tooling, or conventions change.