writing-claude-md

What this skill does

# Writing CLAUDE.md

## Overview

**Writing CLAUDE.md IS establishing project memory that persists across sessions.**

CLAUDE.md is context, not enforced configuration. Claude treats it as high-priority guidance loaded every session. For deterministic enforcement, use hooks.

**Core principle:** Only include what Claude can't figure out from reading the code. Specific and verifiable > vague and aspirational.

**Violating the letter of the rules is violating the spirit of the rules.**

## Routing

**Pattern:** Skill Steps
**Handoff:** none
**Next:** none

## Task Initialization (MANDATORY)

Before ANY action, create task list using TaskCreate:

```
TaskCreate for EACH task below:
- Subject: "[writing-claude-md] Task N: <action>"
- ActiveForm: "<doing action>"
```

**Tasks:**
0. Fetch latest official memory/CLAUDE.md spec
1. Analyze current state
2. Identify documentation gaps
3. Design instruction structure
4. Write CLAUDE.md
5. Add project content
6. Validate structure
7. Review and optimize
8. Test with new session

Announce: "Created 9 tasks (0–8). Starting execution..."

**Execution rules:**
1. `TaskUpdate status="in_progress"` BEFORE starting each task
2. `TaskUpdate status="completed"` ONLY after verification passes
3. If task fails → stay in_progress, diagnose, retry
4. NEVER skip to next task until current is completed
5. At end, `TaskList` to confirm all completed

## Task 0: Fetch Latest Official Spec

**Goal:** Pull the current Anthropic CLAUDE.md / memory spec before designing — never trust cached memory.

**Action:**
```
Skill tool: fetching-claude-docs
  component: memory
  question: "CLAUDE.md location precedence (project/user/local), import syntax,
             auto-loading behavior, token cost, recommended structure"
```

**Verification:** Received YAML with `source: https://code.claude.com/docs/en/memory.md` and non-empty `spec_excerpt`. Use as authoritative reference; if any rule in this SKILL conflicts with the fetched spec, the fetched spec wins.

## Task 1: Analyze Current State

**Goal:** Understand what exists and what's needed.

**If CLAUDE.md exists:**
1. Read current content
2. Check length (target: < 200 lines)
3. Identify vague or unverifiable instructions
4. Check if content belongs elsewhere (rules, skills, hooks)

**If no CLAUDE.md:** Document what Claude would need to know that it can't learn from reading the code.

**Verification:** Can list specific instructions needed and why each can't be derived from code.

## Task 2: RED - Test Without Proper CLAUDE.md

**Goal:** Observe what Claude gets wrong without guidance.

**Process:**
1. Start session with weak/no CLAUDE.md
2. Ask Claude to perform common project tasks
3. Note where it uses wrong commands, wrong conventions, wrong paths
4. Document specific gaps (not vague "drift")

**What to look for:**
- Wrong build/test commands
- Incorrect assumptions about project structure
- Missing project-specific conventions
- Wrong language or communication style

**Verification:** Documented at least 2 specific things Claude got wrong.

## Task 3: GREEN - Write CLAUDE.md

**Goal:** Create specific, verifiable instructions addressing the gaps you documented.

**Before writing, walk through [prompt-design-principles.md](../../references/prompt-design-principles.md):**

- 5-skeleton framework — CLAUDE.md typically needs **Role** (what Claude does in this project), **Scope** (what's in/out), and **Standards** (concrete rules). Workflow and Completion usually live in skills / rules, not CLAUDE.md.
- Failure-mode reverse engineering — every `MUST` / `NEVER` line should trace to an observed or predicted failure (documented in Task 2 RED), not an aspirational wish.
- Conditional dispatch — avoid absolute rules that don't hold across all task variants.

### What to Include vs Exclude

**Filter every line through this question first:** "Can Claude derive this from reading the code, package.json, or running `ls`?" If yes, exclude — it's noise that pushes real signal out of attention budget.

The 2026 ETH Zürich study found that LLM-auto-generated CLAUDE.md files **reduced** task success by ~3% and increased cost ~20% precisely because they re-stated derivable content. The same study found that named tools/commands in CLAUDE.md are used ~160× more — confirming Claude reads it carefully, so every wasted line displaces a useful one.

**Three-axis frame (WHAT / WHY / HOW):**

- **WHAT** — non-obvious project identity Claude can't infer: monorepo layout, unusual subdirectory roles
- **WHY** — rationale for surprising choices: historical constraints, legal/compliance drivers, prior incidents
- **HOW** — non-default tooling and commands: `bun` not `npm`, `uv` not `pip`, custom build scripts, project-specific test filters

| Include (Claude can't guess) | Exclude (Claude already knows or can derive) |
|------------------------------|---------------------------------------------|
| Non-default tooling (`bun` not `npm`, `uv` not `pip`) | Standard language conventions |
| Build/test/deploy commands with project-specific flags | Things a linter or formatter enforces |
| Repo conventions (branch naming, PR format) | General programming practices |
| Why a surprising architecture exists (incident, constraint) | Big architecture overviews / directory listings (Claude can `ls`) |
| Environment quirks, gotchas, prior incidents | Detailed API docs (link instead) |
| Hidden invariants not visible in code | Restating what package.json / pyproject.toml already says |
| Anti-patterns previously caught in review | Aspirational "write clean code" / "follow best practices" |

### CLAUDE.md Structure

Sections: Code Style, Workflow, Architecture, Gotchas. See [references/examples.md](references/examples.md) for complete example.

### Writing Rules

Instructions MUST be **SPECIFIC**, **VERIFIABLE**, **NON-OBVIOUS**, and **ACTIONABLE**.

Use `MUST`/`NEVER`/`IMPORTANT` sparingly — if everything is critical, nothing is.

### When to Use Other Mechanisms Instead

| If the instruction is... | Use... |
|--------------------------|--------|
| A focused convention scoped to a directory or file glob | `.claude/rules/<name>.md` with `paths:` scope tag (still loads every session — split for budget, not for filtering) |
| A reusable multi-step workflow | A skill in `.claude/skills/` (loaded on-demand) |
| **Must NEVER be bypassed** (force-push protection, secret-commit block, destructive ops) | **A hook** with `exit 2` — text in CLAUDE.md is ~70% compliance, not 100%. Hard rules live in hooks. |
| Only relevant for certain tasks | A skill (loaded on-demand, saves tokens) |
| Specific to a subdirectory of a monorepo | A nested `CLAUDE.md` inside that subdirectory — Claude Code merges parent + child when working in that path |

### Conditional Dispatch (for instructions only relevant to specific tasks)

When a section only applies to certain task types (testing, deploying, migrating), wrap it in a conditional block instead of always-on prose. Claude reads the condition and skips the body when it doesn't apply, freeing attention budget for the rest of the file.

```markdown
<important if="writing or modifying tests">
- Use `createTestApp()` helper for integration tests
- Mock the database with `dbMock` (NEVER hit real DB in unit tests)
</important>

<important if="deploying to production">
- Run `bun build` locally first; CI does not auto-build
- Tag the release before pushing to main
</important>
```

Use this for: test setup, deploy steps, migration procedures, environment-specific gotchas. Do **not** wrap core identity (tech stack, build command, project layout) — those need to stay always-on.

### Nested CLAUDE.md (monorepos and multi-package repos)

Claude Code merges nested `CLAUDE.md` files: when working in `apps/api/handlers/foo.ts`, it loads root `CLAUDE.md` + `apps/CLAUDE.md` + `apps/api/CLAUDE.md` if they exist. Use this for monorepos:

- Root `CLAUDE.md`: project identity, top-level layout, shared commands
- `packag