Mortdecai
ea3cf45953
The original repo presented everything as equal rules. In reality, the workflow has two tiers: core practices (used in every project) and advanced rules (only in complex projects like Mortdecai). Core tier adds: - backup-before-edit (global CLAUDE.md rule) - superpowers-workflow (the actual workflow engine) - memory-system (persistent feedback and project memories) - document-hierarchy (CLAUDE.md/SESSION.md/CONTEXT.md/IDEA.md) - commit-and-push discipline - feedback-driven behaviors Updated README, docs, and dynamic-methodology to reflect the two-tier reality instead of presenting advanced rules as universal. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
101 lines
4.6 KiB
Markdown
101 lines
4.6 KiB
Markdown
# 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."
|