f41c22d0ac
- CLAUDE.md: add "Question the question" and "One clarifying question" rules to Tone and Interaction — XY problem detection, false premise checks, and explicit reframe pattern before answering - Add claude/ detail-file directory (topic docs referenced from CLAUDE.md) - Add ABOUT.md, FUTURE.md - Update memory/, scripts/, settings.yaml with accumulated session changes Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
76 lines
4.3 KiB
Markdown
76 lines
4.3 KiB
Markdown
# Documentation Standards
|
|
|
|
Every project maintains standard markdown files. Index files (MEMORY.md, CONTEXT.md, BESTPRACTICES.md, SPEC.md, CLAUDE.md at root) are **thin indexes** pointing to detail files in subdirectories — not large documents themselves.
|
|
|
|
## CLAUDE.md (per-project)
|
|
|
|
The primary reference for Claude sessions. Should contain:
|
|
- Project overview and architecture
|
|
- Repository structure (keep updated as the project evolves)
|
|
- Key design decisions with rationale
|
|
- Conventions and coding standards
|
|
- Environment details (IPs, URLs, credentials references)
|
|
- Common operations / how-to recipes
|
|
|
|
For long projects, follow the same thin-index pattern as MEMORY.md — keep CLAUDE.md as the always-on guardrails + a "when to read which detail file" pointer table, and put per-subsystem conventions in `claude/<topic>.md`.
|
|
|
|
## MEMORY.md (Tiered Memory System)
|
|
|
|
**MEMORY.md** is a **thin index only** — one-line descriptions with links to topic files in `memory/`. No content lives in MEMORY.md itself.
|
|
|
|
**memory/** contains the actual content, split by topic:
|
|
- `memory/project-status.md` — current milestone, what's next, blockers
|
|
- `memory/network.md` — IPs, VIPs, subnets, topology
|
|
- `memory/gotchas-<topic>.md` — gotchas grouped by technology (`gotchas-cilium.md`, `gotchas-authelia.md`)
|
|
- `memory/process-lessons.md` — how-to-work-with-this-repo lessons for Claude
|
|
- `memory/m<N>-reflection.md` — one file per milestone reflection (time-bound, per-file is natural)
|
|
- `memory/decisions.md` — architecture and design decisions made during planning
|
|
|
|
Principles:
|
|
- **Split by topic, not by time.** A Cilium gotcha belongs in `gotchas-cilium.md` whether discovered in M5 or M8.
|
|
- **Milestone reflections are the exception** — inherently time-bound, one file per milestone.
|
|
- **Index descriptions matter.** "Cilium L2/LB gotchas and externalTrafficPolicy quirks" beats "cluster stuff".
|
|
- **Prune aggressively.** If a gotcha was fixed (e.g., chart upgraded past the bug), delete it. Stale memory is worse than no memory.
|
|
- **Each memory file should be self-contained and greppable.**
|
|
- **Deduplicate with CLAUDE.md.** Stable conventions live in CLAUDE.md. Memory holds learnings, gotchas, reflections. If something in memory has graduated to a stable convention, move it to CLAUDE.md and remove it from memory.
|
|
|
|
When reading memory at session start: read MEMORY.md (the index), then selectively read topic files relevant to the current task. Don't read all memory files unless doing a broad review.
|
|
|
|
When writing memory after a milestone: create the reflection file, update affected topic files, update the index.
|
|
|
|
## CONTEXT.md (Active Work Focus)
|
|
|
|
Thin index — one-line descriptions with links to detail files in `context/`. Answers "what should I focus on right now?"
|
|
|
|
**context/** contains one file per active work stream: background, status, what to test, future direction.
|
|
|
|
Principles:
|
|
- **Keep it current.** Remove entries when work is complete. CONTEXT.md reflects what's actively in progress, not history.
|
|
- **Link, don't inline.** Index stays small so `context-load` doesn't bloat the system prompt.
|
|
- **Orient agents.** CONTEXT.md is the primary mechanism for pointing independent agents (including container agents) at the right work.
|
|
- **Complement, don't duplicate.** CLAUDE.md = stable conventions. MEMORY.md = accumulated learnings. CONTEXT.md = *current* focus.
|
|
|
|
## BESTPRACTICES.md (Best Practices Index)
|
|
|
|
Index of generalised best practices extracted from real project work via `/distill-best-practices`. Only exists in `claude-foundations` — other projects inherit it via `context-load` walking up the directory hierarchy.
|
|
|
|
Thin index pointing to topic files in `best-practices/` (e.g., `kubernetes.md`, `helm.md`). Read only files relevant to the current project's stack.
|
|
|
|
`/distill-best-practices` maintains both the topic files and the index.
|
|
|
|
## FUTURE.md
|
|
|
|
Backlog of improvement ideas, each with:
|
|
- **Problem:** what's painful or manual today
|
|
- **Idea:** what the improvement looks like
|
|
- **Open questions:** unknowns to research before starting
|
|
- **Depends on:** other items or milestones that should come first
|
|
|
|
## README.md
|
|
|
|
Human-readable project documentation:
|
|
- Architecture summary
|
|
- Quick start / setup instructions
|
|
- Milestone table with status
|
|
- Scripts section listing every script with purpose and usage
|