/writing-claude-md

name: writing-claude-md
description: Creates or improves CLAUDE.md project configuration with token-efficient, actionable instructions. Use when creating CLAUDE.md, improving existing CLAUDE.md, or setting up project configuration. Use when user says "create CLAUDE.md", "setup project", "configure agent".

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.

Task Initialization (MANDATORY)

Follow [task initialization protocol](../../references/task-initialization.md).

**Tasks:** 0. Fetch latest official memory/CLAUDE.md spec 1. Analyze current state 2. RED - test without proper CLAUDE.md 3. GREEN - write CLAUDE.md 4. Add project content 5. Validate structure 6. REFACTOR - quality review 7. Test with new session

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

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:` — loads only when Claude reads a matching file, so it costs