claude-memory-bootstrap

A Claude Code Skill that helps you build your own CLAUDE.md memory system the right way — short, layered, actionable.

Languages: English · 中文

---

The problem

Every time you start a fresh Claude Code conversation, Claude doesn't remember:

• What stack your project uses
• Your code style and team conventions
• The non-obvious gotchas you've already explained 5 times
• Which subproject "the new feature" is supposed to go into

You can solve this with CLAUDE.md files — Claude Code's persistent memory system. But most people write one bad CLAUDE.md and call it done: 500 lines of generic advice ("write clean code"), no layering, no triggers, no separation between personal preferences and project rules. Every conversation pays the full context cost.

This skill teaches Claude how to build a good memory system for you, in any project. It bakes in:

• The official five-layer architecture (enterprise / user / project / local / rules)
• Four core principles: Less is More, Specific over Generic, WHY/WHAT/HOW, Progressive Disclosure
• A standard workflow Claude follows when you say "set up a memory system here"
• Templates for each layer, with line-budget guidance

---

30-second start

git clone https://github.com/<your-username>/claude-memory-bootstrap.git
cd claude-memory-bootstrap
./install.sh

install.sh copies the skill into ~/.claude/skills/claude-memory-bootstrap/. After that, in any Claude Code session, say:

"Set up a memory system for this project."

or

"Help me write a CLAUDE.md."

Claude will trigger the skill, scan your project, ask you a few preference questions, and produce the right files at the right layers.

---

What the skill does (in 5 steps)

1. Scan — inventory existing CLAUDE*.md, AGENTS.md, README.md, build tool, git status.
2. Evaluate gaps — which of the five layers are missing? Which are bloated?
3. Ask preferences — language, code style, test policy, indent, audience.
4. Generate — emit only the missing layers, sized to the layer's budget.
5. Verify — run a checklist (line budget? WHY tags? .gitignore correct? specific not generic?).

The skill refuses to overwrite an existing CLAUDE.md without asking. It refuses to put secrets in committed files. It refuses to write generic advice like "use meaningful variable names".

---

The five-layer memory architecture

Claude Code loads memory in layers, outer to inner. Inner layers can override outer ones.

Layer	Path	Holds	Budget
1. Enterprise policy	/Library/Application Support/ClaudeCode/CLAUDE.md (macOS)	Org-wide security / compliance	Skip if individual
2. User	~/.claude/CLAUDE.md	Cross-project preferences (language, indent, test policy)	~50 lines
3. Project	<project>/CLAUDE.md	Team-shared project knowledge (stack, conventions)	~100 lines
4. Local	<project>/CLAUDE.local.md (must be gitignored)	Machine-only info (test accounts, local URLs, current task)	~50 lines
5. Rules	<project>/.claude/rules/*.md with paths: frontmatter	Conditional rules loaded only when matching files are edited	Use when project-level >200 lines

Mixing layers is the most common mistake. "Use Chinese in responses" belongs in layer 2, not layer 3. "Admin password: 123456" belongs in layer 4, not layer 3. The skill keeps these separated.

---

The four writing principles (why your CLAUDE.md should be short)

1. Less is More

Every line is re-injected on every conversation. Redundancy isn't free — it's a recurring tax. Self-check: if I don't write this rule, will Claude get it right anyway? If yes, delete it.

2. Specific over Generic

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

3. WHY / WHAT / HOW

For critical rules, follow up the WHAT with one sentence of WHY. Claude reusing the principle in unseen situations is what makes the memory file pay off long-term.

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

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.

---

Repository structure

claude-memory-bootstrap/
├── README.md              ← you are here
├── README.zh-CN.md
├── LICENSE                ← MIT
├── CHANGELOG.md
├── SKILL.md               ← entry point, auto-loaded by Claude Code
├── SKILL.zh-CN.md
├── install.sh             ← copies into ~/.claude/skills/
├── references/            ← templates Claude consults when generating
│   ├── user-claude-template.md       (+.zh-CN.md)
│   ├── project-claude-template.md    (+.zh-CN.md)
│   ├── local-claude-template.md      (+.zh-CN.md)
│   └── skill-creation-checklist.md   (+.zh-CN.md)
└── examples/              ← case studies (sanitised)
    └── case-saas-monorepo.md         (+.zh-CN.md)

---

When not to use this

• One-off scripts you'll delete next week.
• A project where you're the only contributor and the only AI tool is occasional autocomplete.
• Repos with a fully working CLAUDE.md you're happy with — the skill detects this and won't overwrite.

---

Contributing

Issues and PRs welcome. Specifically valuable:

• Translations to more languages (Japanese / Korean / Spanish welcome).
• Case studies for stacks not yet covered (Rust + Tauri, Elixir + Phoenix, etc.).
• Reports of cases where the skill's workflow missed something or generated bad output.

---

Credits

Built on top of:

• The official Claude Code memory system documentation (the five-layer architecture).
• Huang Jia (黄佳)'s Claude Code 工程化实战 column on GeekBang Time — the Less-is-More / Specific-over-Generic / WHY/WHAT/HOW / Progressive Disclosure principles come from there.
• Real workflow refinement from operating a multi-project monorepo (case study in examples/).

---

License

MIT