# Document Hierarchy

The foundation of the entire workflow. Four file types, each with a distinct purpose, used consistently across every project.

## The Four Documents

| File | Purpose | When Updated | Loaded |
|------|---------|-------------|--------|
| **CLAUDE.md** | Project instructions for the AI | When components, tools, or architecture change | Every session (auto) |
| **SESSION.md** | Accumulated AI memory — decisions, discoveries, patterns | During/after each session | On demand |
| **CONTEXT.md** | Static infrastructure facts — hosts, ports, services | When infrastructure changes | On demand |
| **IDEA.md** | Plain-language project brief | Rarely (initial creation) | On demand |

## CLAUDE.md — The Starting Point

The AI reads this first, every session. It should contain:

- **Project state** — current phase, branch, test status, deployment
- **Architecture** — how components connect, key files and their roles
- **Conventions** — commit style, naming, project-specific rules
- **Credentials** — where they live (never the values themselves)
- **Development commands** — setup, run, test

**Keep it lean.** Everything in CLAUDE.md loads every session. Don't dump session notes or temporary debugging context here. Stable, long-term facts only.

**Keep it current.** If you create a new tool and don't document it here, the next session won't know it exists. Update CLAUDE.md immediately when components change — don't leave it for later.

## SESSION.md — The Living Memory

Accumulates decisions, discoveries, and context across AI sessions. Grouped by topic, not by date.

```markdown
## Session Notes

### Infrastructure decisions
- Chose LXC over Docker-in-LXC because the service doesn't need container isolation
- Enabled nesting=1 on the container to allow Docker inside

### Bug fixes & discoveries
- Service wasn't starting: had autoStart=false in config
  (fixed: set autoStart=true, verified with restart)

### Open threads
- [ ] Add Redis backend for session persistence
- [ ] Web dashboard for monitoring
```

**Key principle:** Update the relevant section rather than appending raw timestamped blocks. A reader should be able to scan by topic, not wade through chronological entries.

## CONTEXT.md — The Infrastructure Facts

Static facts about where and how the project runs. Ports, hosts, services, dependencies. Updated when infrastructure changes, not during routine development.

This is separate from CLAUDE.md because infrastructure facts are reference material — loaded on demand, not every session.

## IDEA.md — The Original Intent

Written once at project creation. Captures what the project is, what problem it solves, and any known constraints. Rarely modified after creation.

Useful for: new contributors understanding why the project exists, AI assistants that need to understand the original motivation, and the project creator looking back at initial intent vs current reality.

## How They Relate

```
Session start:
  → AI reads CLAUDE.md (auto-loaded, always)
  → AI checks MEMORY.md (auto-loaded, always)
  → AI checks .claude/sessions/ for recent handoffs

During work:
  → AI reads CONTEXT.md when infrastructure details needed
  → AI reads SESSION.md when historical decisions needed
  → AI reads IDEA.md when original intent/scope is questioned

Session end:
  → AI updates SESSION.md with new decisions/discoveries
  → AI updates CLAUDE.md if components changed
  → AI writes handoff if work is unfinished
```

## The Global CLAUDE.md

In addition to per-project CLAUDE.md files, a global `~/.claude/CLAUDE.md` applies to all projects. Use it for:

- Universal rules (like "backup before edit")
- Tool documentation (CLI wrappers, custom scripts)
- Infrastructure overview (what machines exist, how to reach them)
- Cross-project conventions

Per-project CLAUDE.md files inherit from and can override the global one.

## Anti-Patterns

**CLAUDE.md as a dumping ground.** If it grows beyond ~200 lines, it's too heavy. Move reference material to CONTEXT.md, move decisions to SESSION.md, move architecture to `docs/`.

**SESSION.md as a chat transcript.** It's not a log of what was said. It's a curated record of what was *decided* and *discovered*. Group by topic, not by date.

**CONTEXT.md for opinions.** It stores facts (this service runs on port 8080), not opinions (we should probably migrate to a different port). Opinions go in SESSION.md or design docs.

**Forgetting to update CLAUDE.md.** The single most common failure mode. You create a new tool, the session ends, the next session doesn't know it exists. Update immediately, not "later."