claude-memory-bootstrap

Claude Code Five-Layer Memory System Bootstrap

Goal: give Claude perfect recall at the start of every new session, without

blowing the context budget.

Do this immediately on trigger

1. Use Read / ls to inventory the user's current working directory:

the top-level entries, any existing CLAUDE.md / AGENTS.md / README.md / package.json / pyproject.toml / main entry source files. Do not write blindly.

1. Check whether ~/.claude/CLAUDE.md already exists; if it does, do not

overwrite — ask the user if anything needs adding.

1. Check whether the target directory is a git repo (ls .git); this decides

whether CLAUDE.local.md needs a .gitignore entry.

1. Evaluate which of the five layers is missing for this project, and only

produce the missing ones.

The five layers (Claude Code official architecture)

Loading order: outer → inner. Inner layers can override outer ones.

The four writing principles (non-negotiable)

Principle 1: Less is More

Every line is re-injected on every conversation. Redundancy is a recurring tax. Self-check: if you don't write this rule, will Claude do it correctly anyway? Yes → delete it.

Principle 2: Specific over Generic

• •❌ "Please write high-quality code."
• •✅ "Use interface for object shapes; ban any, use unknown + type guards."

Principle 3: WHY / WHAT / HOW

After a critical rule, add one sentence of WHY. Claude that understands the reason will generalise correctly to situations the file doesn't list.

- service-layer code only `flush()`; routes do `commit() + refresh()`.
  **WHY**: routes own the transaction boundary; a flush inside a service that's
  reused by multiple routes would let one route commit another's half-finished
  work.

Principle 4: Progressive Disclosure

Reference detail docs with @path/to/doc.md instead of pasting them in. Keep the top file lean; let Claude load the deep ones only when needed.

Standard workflow

Step 1: Scan

ls -la <target>/
find <target> -maxdepth 3 \( -name "CLAUDE*.md" -o -name "AGENTS.md" -o -name "DESIGN.md" -o -name "spec.md" \) 2>/dev/null
test -f ~/.claude/CLAUDE.md && echo "user-level exists" || echo "user-level MISSING"
test -d <target>/.git && echo "is git repo" || echo "not git"

Step 2: User layer (if missing)

Use AskUserQuestion to collect:

1. Reply language (English / Chinese / mixed)
2. Reply tone (concise / medium / detailed)
3. Code comment language
4. Indent preference (2 / 4 / tab)
5. Test policy (never proactive / proactive for critical logic / always proactive)
6. Technical background — decides whether Claude should use analogies

Then write ~/.claude/CLAUDE.md from references/user-claude-template.md.

Step 3: Project layer

Read the project skeleton (ls -la, key config files, entry source files). Generate <project>/CLAUDE.md from references/project-claude-template.md. Required sections:

1. One-line project positioning
2. Startup checklist (the 2-3 things Claude must do on entry)
3. Task routing (only for multi-module projects)
4. Tech stack (compact table)
5. Hard constraints (real gotchas, each with WHY)
6. Anti-patterns (explicit "do not do X")
7. Project map + @-references to deeper docs

Step 4: Local layer (optional)

If the project has test accounts, local URLs, current task notes, generate <project>/CLAUDE.local.md from references/local-claude-template.md, then:

# Git repos only
test -d .git && {
  grep -q "^CLAUDE.local.md$" .gitignore 2>/dev/null || \
    printf "\n# Claude Code local memory\nCLAUDE.local.md\n" >> .gitignore
}

Step 5: Rules directory (only if project layer >200 lines)

Split topic-specific rules into .claude/rules/<topic>.md with paths: frontmatter so they load only when matching files are edited:

---
paths:
  - "src/**/*.test.ts"
  - "tests/**/*.ts"
---
# Testing conventions
...

Verification checklist (run at the end)

• •[ ] User / project / local each holds only that layer's responsibilities
• •[ ] User layer ≤ 50 lines, project layer ≤ 100 lines, local layer ≤ 50 lines
• •[ ] All critical hard constraints are followed by a WHY sentence
• •[ ] Detail docs are @-referenced, not pasted in
• •[ ] CLAUDE.local.md is gitignored (if a git repo)
• •[ ] No "write high-quality code" platitudes
• •[ ] No content that Claude would have done correctly by default
• •[ ] Anti-patterns section has at least 3 explicit "do not" rules

Common mistakes to avoid

Reference templates (in references/)

• •user-claude-template.md (+ .zh-CN.md) — for ~/.claude/CLAUDE.md
• •project-claude-template.md (+ .zh-CN.md) — for <project>/CLAUDE.md
• •local-claude-template.md (+ .zh-CN.md) — for <project>/CLAUDE.local.md
• •skill-creation-checklist.md (+ .zh-CN.md) — for packaging other

workflows as Skills later

Maintenance

• •After 1-2 weeks of use, re-audit: which rules has Claude never violated?

Delete them — they're not earning their context cost.

• •Rules Claude has actively violated should get a more concrete WHY or counter-

example. Otherwise it'll keep violating them.

• •When business rules change (formulas, thresholds, org structure): update the

source-of-truth document first (PDF / spec), then sync to CLAUDE.md, then run the code to confirm nothing drifted.