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>
2.4 KiB
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, blockersmemory/gotchas-<topic>.md— Gotchas grouped by technologymemory/process-lessons.md— How-to-work-with-this-repo lessonsmemory/m<N>-reflection.md— One file per milestone reflectionmemory/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.