claude-md-writer

CLAUDE.md Writer

Write CLAUDE.md files that Claude Code actually follows. Every line must earn its place — CLAUDE.md loads every conversation turn, consuming context window tokens each time.

How CC Loads CLAUDE.md

CLAUDE.md is delivered as a user message after the system prompt — advisory context, not enforced configuration. Adherence degrades with file length and conflicting rules.

Loading order (lowest → highest priority):

Managed policy (/Library/Application Support/ClaudeCode/CLAUDE.md) — org-wide, cannot exclude
User global (~/.claude/CLAUDE.md + ~/.claude/rules/)
Project walkup — from working dir upward: ./CLAUDE.md + ./.claude/CLAUDE.md + ./.claude/rules/ at each level
Local (./CLAUDE.local.md) — personal, not git-tracked
Additional dirs (via CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD env var)

Subdirectory CLAUDE.md files lazy-load when Claude touches files in that directory.

Compaction: CLAUDE.md survives /compact — re-read from disk and re-injected. Conversation-only instructions are lost.

Import syntax: @path/to/file pulls in additional files. Max 5 hops. Relative paths resolve from the importing file.

Size Limits

File	Target	Hard limit
Global `~/.claude/CLAUDE.md`	≤120 lines	40K chars (CC warning)
Project `./CLAUDE.md`	≤120 lines (~2500 tokens)	40K chars (CC warning)
`CLAUDE.local.md`	≤50 lines	Same
`MEMORY.md`	≤200 lines or 25KB	Hard truncation

Shorter files = better adherence. Over 200 lines, instruction-following drops measurably.

Core Principles

Compression-first: Every token costs every turn. One-liner per concept when possible
Non-obvious only: If Claude can infer it from reading code, don't state it
Actionable: Commands copy-paste-ready, paths real, steps concrete
Project-specific: Generic advice ("write tests", "use meaningful names") is noise
Dedup-aware: Don't repeat what CC system prompt or higher-level CLAUDE.md already provides

File Type Guide

Global CLAUDE.md (`~/.claude/CLAUDE.md`)

Personal development partner configuration. Loaded in every CC session across all projects.

Sections (in order):

Identity — Communication style, expertise assumption, language rule (3-4 lines)
Tech Stack — Backend, mobile, frontend, infra, environment. Remove unused lines
Workflow — Intent routing, delegation, research, execution, verification patterns
Skills — Table of detected skills with trigger descriptions
MCP — Enabled servers with one-line capabilities
LSP — Conditional on detected plugins
Rules — 3-5 imperatives. Defer detailed rules to my-coding skill

Compression-critical: Workflow section (Intent Gate table + Research delegation) must survive verbatim — these are routing anchors that CC uses to decide how to act.

Project CLAUDE.md (`./CLAUDE.md`)

Project-specific context. Loaded in every conversation within this project directory.

Sections (in order — include only if content discovered):

Header — Project name + one-line mission
Commands — Copy-paste-ready table (build, test, lint, dev)
Architecture — Annotated tree, depth 2, non-obvious purpose only
Key Files — Entry points, critical configs Claude wouldn't find easily
Code Style — Imperative conventions from project source (NOT generic)
Testing — Test commands + patterns
Gotchas — Non-obvious quirks, anti-patterns from source comments
Skills & Extensions — Approved references only

Dedup boundary: NEVER duplicate global CLAUDE.md content (workflow, identity, tech stack, coding rules). Project = project-specific facts only.

CLAUDE.local.md

Personal project-specific preferences — gitignored. Appended after CLAUDE.md at same directory level (wins on conflict).

Use for: Local URLs, sandbox endpoints, preferred test data, personal workflow shortcuts. Keep under 50 lines.

.claude/rules/ Files

Path-scoped conventions that inject when matching files are touched.

Unconditional (no frontmatter): loaded at launch alongside CLAUDE.md
Path-scoped (with paths frontmatter): inject only when matching files are opened
Use for detailed coding conventions that only matter for specific file patterns

Boundary: Generic project conventions → CLAUDE.md. File-path-specific conventions → rules.

Section Authoring Patterns

Commands Section

## Commands

| Command | Description |
|---------|-------------|
| `npm run build` | Production build with optimization |
| `npm test -- --watch` | Run tests in watch mode |

Copy-paste-ready — exact command, not descriptions of commands
Skip obvious (npm install, git clone)
Include flags that matter (--watch, --coverage, --runInBand)

Architecture Section

## Architecture

src/ api/ # REST endpoints — one file per resource services/ # Business logic layer — no HTTP concerns models/ # Sequelize models with custom scopes jobs/ # Background job processors (Bull queues)

Depth 2 max — Claude can explore deeper with Glob
Annotate only directories whose purpose isn't obvious from name
Skip node_modules/, dist/, .git/, config dirs with clear names

Code Style Section

Good — project-specific, imperative, verifiable:

- Use barrel exports (`index.ts`) in every module directory
- Prefer `readonly` arrays — use `ReadonlyArray<T>` not `T[]` for function params
- Error responses use `AppError` class from `src/errors.ts` — never raw Error

Bad — generic, vague, unverifiable:

- Follow clean code principles
- Use descriptive variable names
- Handle errors properly

Gotchas Section

Good — non-obvious, prevents debugging:

- Migrations auto-run at boot — never modify existing migration files, create new ones
- `NEXT_PUBLIC_*` vars must be set at BUILD time, not runtime
- Tests must run sequentially (`--runInBand`) due to shared DB state

Bad — obvious, generic:

- Be careful with database migrations
- Environment variables must be configured
- Tests should be independent

Key Files Section

Good — entry points Claude wouldn't find:

- `src/bootstrap.ts` — Server bootstrap, DI container setup. Import order matters
- `config/features.yml` — Feature flags. Changes require restart

Bad — discoverable or obvious:

- `package.json` — Node.js configuration
- `src/index.ts` — Application entry point

Emphasis for Adherence

Adding emphasis tokens improves instruction-following in longer files:

IMPORTANT: Always use pnpm, not npm.
YOU MUST run tests before committing.

Use sparingly — if everything is IMPORTANT, nothing is. Reserve for rules where violation causes real damage.

Quality Scoring

Score each criterion (from Anthropic's official rubric):

Criterion	Weight	What earns full score
Commands/Workflows	20pts	All essential commands with context
Architecture Clarity	20pts	Key dirs explained, entry points identified
Non-Obvious Patterns	15pts	Gotchas, workarounds, "why we do it this way"
Conciseness	15pts	Dense content, no filler, no obvious info
Currency	15pts	Commands work, file refs accurate, stack current
Actionability	15pts	Copy-paste ready, concrete steps, real paths

Red flags: Commands that would fail, references to deleted files, outdated tech versions, generic advice, unfinished TODOs, duplicate info across files.

Quality Checklist

Before finalizing any CLAUDE.md:

Every line answers: "Would removing this cause Claude to make mistakes?"
No content already in higher-level CLAUDE.md (project files)
No obvious instructions or generic best practices
No file listings discoverable via Glob or LS
No setup/installation steps (use README for that)
No verbose multi-line explanations (one-liner per concept)
Architecture uses annotated tree, non-obvious only
Code Style conventions are imperative and verifiable
Gotchas are non-obvious quirks from actual codebase
Commands are copy-paste-ready with real flags
Token budget verified (global ≤120 lines, project ≤2500 tokens)
No conflicting rules across files (Claude picks arbitrarily on conflict)

References

Topic	File	When to read
Section patterns	claude-md-patterns.md	Before writing — complete section templates, good/bad examples, monorepo patterns
CLAUDE.md dedup	claude-md-dedup-guide.md	Before writing — dedup boundaries between global/project/rules/my-coding/CC system prompt
CC dedup (general)	`${CLAUDE_SKILL_DIR}/../prompt-writer/references/cc-dedup-guide.md`	When checking what CC system prompt already provides