Codify session learnings into docs/, rules/, or CLAUDE.md so future sessions can discover them. Use when: a bug is fixed, a problem is solved, a design decision is made, a non-obvious gotcha is discovered, a workflow is established, or the user says "it works", "solved", "fixed", "なるほど", "わかった".
Capture knowledge from this session and persist it so future sessions benefit.
Identify what was learned. Focus on:
Search docs/ and CLAUDE.md for related content. If a related doc already exists, instead of creating a new one. Avoid duplication.
| Target | When to use |
|---|---|
| Test / linter rule | The issue can be caught mechanically. Always prefer this |
docs/<topic>.md | Solutions, gotchas, design decisions, specs — anything worth more than one line |
.claude/rules/ with paths | Coding conventions scoped to specific file types |
CLAUDE.md (one-line pointer) | Only add a pointer to docs/. Never add content directly |
Priority: test/linter > docs/ > rules/ > CLAUDE.md pointer.
Why this order:
For docs/ files:
# <Title>
## Problem
What went wrong or what question came up.
## Solution
What works and why.
## Prevention
How to avoid this in the future (test, linter rule, hook, or convention).
Keep it concise. One page per topic. Use clear terminology — future sessions discover docs via grep.
CLAUDE.md should be a map that points to docs/. After writing:
docs/ is not mentioned in CLAUDE.md, propose adding a one-line pointerCLAUDE.md is capped at 200 lines (official recommendation). Every line must earn its place.
Stage the new/updated docs and any CLAUDE.md changes. Commit within the same session so the knowledge is immediately available to the next session via git.