A field guide and starter kit

CLAUDE.md is not a config file.

It's the editorial layer of a layered context system. Most people are using maybe 10% of what it can do. This kit closes that gap.

What it actually is

A config file declares values: port: 8080, theme: dark. Read once, applied. Static.

CLAUDE.md describes a working relationship: your style, your stack, the rules you keep retyping into every new chat. Read every session, shapes Claude's responses.

The difference matters. Config-file thinking gives you settings. Editorial thinking gives you "always run migrations through Alembic, never raw SQL" — the rules that make Claude useful, not just configured.

# What you get

home/                              → ~/.claude/
+-- CLAUDE.md                      Lean global identity
+-- templates/
|   +-- cloudflare-worker.md
|   +-- python-package.md
|   +-- node-typescript.md
|   +-- fastapi.md
|   +-- react-frontend.md
|   +-- monorepo.md
+-- commands/
|   +-- standup.md
|   +-- postmortem.md
|   +-- explain.md
+-- agents/
|   +-- code-reviewer.md
|   +-- test-writer.md
+-- hooks/
    +-- pre-tool-use.md            example config

project/                           → <repo>/
+-- CLAUDE.md                      uses @imports
+-- CLAUDE.local.md                gitignored scratchpad
+-- frontend/CLAUDE.md           path-scoped
+-- .claude/
    +-- settings.json              allow/deny lists
    +-- rules/
    |   +-- database.md
    |   +-- api-design.md
    |   +-- secrets.md
    +-- skills/
        +-- security-review/SKILL.md
        +-- dependency-audit/SKILL.md

install.sh, install.ps1            one-command install

The four layers

CLAUDE.md is loaded from four scopes, most-general to most-specific. The kit gives you a working starting point in each.

# Loaded in order; most specific wins

~/.claude/CLAUDE.md          "You"   - style, defaults, every project
<repo>/CLAUDE.md             "Team"  - committed, shared with collaborators
<repo>/CLAUDE.local.md       "Local" - gitignored, just this checkout
<repo>/subdir/CLAUDE.md      "Path"  - loads only when working in subdir/

Layer 1 is your personal style. Layer 2 is the codebase's constitution. Layer 3 is your scratchpad. Layer 4 keeps frontend rules out of backend sessions and vice versa. Conflate any two and you'll feel friction.

Why this exists

If you run more than one project, you're already retyping the same conventions into every new Claude Code session. Cache-bump rules. Deploy patterns. "Never use CMD for git commits." "Never --branch=production." That's friction you don't have to carry.

This kit is the composition pattern in working form: a small library of fragments at ~/.claude/templates/, and project files that @import what they need. Edit the fragments once; every project inherits the improvement.

Already typed /init?

/init reads your repo and generates a baseline CLAUDE.md. It's a fine starting point — but it only fills Layer 2, and only with what it can guess from existing code. The kit completes the picture: a global layer that travels with you, path-scoped rules, a real .claude/ folder, and templates you can @import instead of retyping.

If you've already run /init: install the kit, keep what /init got right (it's good at facts — your stack, your build commands), let the kit handle the structure. The kit's STRUCTURE.md walks through the merge.

If you haven't: install the kit first, then customize. You may not need /init at all — the kit's project template is a better skeleton, and you can fill in the codebase facts yourself in five minutes.

Get the kit.

Drop the link in your inbox. No fluff, no upsell sequence.

One email with the download. Occasional follow-ups about Claude Code workflow. Unsubscribe in one click.

Read the full article: CLAUDE.md Is Not a Config File →