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

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.

CONTEXT.md (Active Work Focus)

Tells Claude (and independent agents) what the project is currently working on. Follows the same thin-index pattern as MEMORY.md.

CONTEXT.md is a thin index with links to context/<topic>.md detail files.

Principles:

• Keep it current — remove entries when work is complete
• Orient agents — this is the primary mechanism for pointing independent agents at the right work
• Complement, don't duplicate — CLAUDE.md has conventions, MEMORY.md has learnings, CONTEXT.md has the current focus