e7c8214499
- Add statusline.sh and set-topic.sh for per-session status line topics - Update context-load with improved directory walking and output format - Update CLAUDE.md with status line docs and early-call safety note - Update MEMORY.md and README.md with new script/skill entries - Add memory files: script-statusline, skill-decompose, skill-orchestrate, gotchas-gitea - Add networking.md best practice (nftables, systemd sockets, Docker forwarding, TLS) - Update best practices from prior distill: documentation, kubernetes, scripting, secrets-management, skills-development - Prune reflected session logs, add new session logs - Update reflection state Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
55 lines
2.4 KiB
Markdown
55 lines
2.4 KiB
Markdown
# Documentation Standards
|
|
|
|
Every project maintains four core markdown files.
|
|
|
|
## CLAUDE.md
|
|
|
|
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, credential references — never actual values)
|
|
- Common operations / how-to recipes
|
|
- Put critical rules at the top — Claude reads sequentially and earlier content has more influence
|
|
|
|
## MEMORY.md (Tiered Memory System)
|
|
|
|
Long-running projects accumulate significant context. Use a **tiered memory** structure:
|
|
|
|
**MEMORY.md** is a **thin index only** — one-line descriptions with links to topic files in `memory/`. No content lives in MEMORY.md itself. Keep it under ~50 lines.
|
|
|
|
**memory/** contains the actual content, split by topic:
|
|
- `memory/project-status.md` — Current milestone, what's next, blockers
|
|
- `memory/gotchas-<topic>.md` — Gotchas grouped by technology
|
|
- `memory/process-lessons.md` — How-to-work-with-this-repo lessons
|
|
- `memory/m<N>-reflection.md` — One file per milestone reflection
|
|
- `memory/decisions.md` — Architecture and design decisions
|
|
|
|
**Principles:**
|
|
- Split by topic, not by time
|
|
- Index descriptions matter — they're used to decide what to read
|
|
- Prune aggressively — stale memory is worse than no memory
|
|
- Each file should be self-contained and greppable
|
|
- Deduplicate with CLAUDE.md — stable conventions go in CLAUDE.md, learnings and gotchas go in memory
|
|
|
|
## 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
|
|
|
|
## Extract Reusable Patterns Early
|
|
|
|
When a reusable pattern emerges during project work (a gotcha that applies to any project using the same tool, a process lesson that generalises), extract it into a best-practices guide immediately rather than waiting for a dedicated distillation pass. The guide pays for itself when used to audit and improve the current project in the same session, and benefits all future projects.
|