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):

1. Managed policy (/Library/Application Support/ClaudeCode/CLAUDE.md) — org-wide, cannot exclude
2. User global (~/.claude/CLAUDE.md + ~/.claude/rules/)
3. Project walkup — from working dir upward: ./CLAUDE.md + ./.claude/CLAUDE.md + ./.claude/rules/ at each level
4. Local (./CLAUDE.local.md) — personal, not git-tracked
5. 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

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):

1. Identity — Communication style, expertise assumption, language rule (3-4 lines)
2. Tech Stack — Backend, mobile, frontend, infra, environment. Remove unused lines
3. Workflow — Intent routing, delegation, research, execution, verification patterns
4. Skills — Table of detected skills with trigger descriptions
5. MCP — Enabled servers with one-line capabilities
6. LSP — Conditional on detected plugins
7. 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):

1. Header — Project name + one-line mission
2. Commands — Copy-paste-ready table (build, test, lint, dev)
3. Architecture — Annotated tree, depth 2, non-obvious purpose only
4. Key Files — Entry points, critical configs Claude wouldn't find easily
5. Code Style — Imperative conventions from project source (NOT generic)
6. Testing — Test commands + patterns
7. Gotchas — Non-obvious quirks, anti-patterns from source comments
8. 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):

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