claude-foundations/claude/documentation-standards.md

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