claude-foundations/best-practices/documentation.md

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