Claude Code Multi-Agent Template

A practical template for structuring Claude Code projects with specialized subagents, persistent memory, and lifecycle hooks.

Built from real production use across 10+ projects at jpcpol. The patterns here emerged from working around a specific problem: Claude reads too much context on every session start, which wastes tokens and slows down simple tasks.

---

The Problem This Solves

By default, Claude Code loads CLAUDE.md on every session. In complex projects, that file grows to 400–800 lines covering architecture, conventions, history, and state. Claude reads all of it even when you just asked "where is the login function?"

This template introduces three complementary patterns:

Pattern	What it does
Compact MEMORY.md	A 4-line index. Claude reads only the memory files relevant to the current task
Lifecycle hooks	SessionStart reminds Claude what to read; PreCompact saves state before context compression
Specialized subagents	Route tasks to the right model+effort level. Don't use Opus for a grep

---

Repo Structure

claude-multiagent-template/
├── README.md                          ← this file
├── docs/
│   ├── memory-pattern.md              ← how and why the MEMORY.md pattern works
│   ├── hooks-guide.md                 ← SessionStart, PreCompact, Stop hooks
│   └── context-handoff.md             ← passing context between agents
└── templates/
    ├── software-project/              ← template for SaaS / backend / fullstack projects
    │   ├── .claude/
    │   │   ├── CLAUDE.md              ← session routing + reading order
    │   │   ├── MEMORY.md              ← compact 4-line index
    │   │   ├── settings.json          ← hooks configuration
    │   │   ├── agents/
    │   │   │   ├── architect.md
    │   │   │   ├── developer.md
    │   │   │   ├── debugger.md
    │   │   │   ├── tester.md
    │   │   │   ├── documenter.md
    │   │   │   ├── researcher.md
    │   │   │   ├── security-auditor.md
    │   │   │   └── context_handoff.md
    │   │   └── memory/
    │   │       ├── claude_continuity.md
    │   │       ├── project_state.md
    │   │       ├── arch_decisions.md
    │   │       └── session_state.md
    └── research-project/              ← template for ML research / data science projects
        └── .claude/
            ├── CLAUDE.md
            ├── MEMORY.md
            ├── settings.json
            ├── agents/
            │   ├── architect.md       ← specialized for experiment design
            │   ├── developer.md
            │   ├── debugger.md        ← distinguishes bugs from valid negative results
            │   ├── researcher.md
            │   ├── documenter.md
            │   └── context_handoff.md
            └── memory/
                ├── claude_continuity.md
                ├── project_state.md
                ├── research_decisions.md  ← replaces arch_decisions for research
                └── session_state.md

---

Quick Start

1. Copy the templates/software-project/.claude/ directory into your project root
2. Edit .claude/MEMORY.md to point to your actual memory files
3. Edit .claude/memory/project_state.md with your project's current state
4. Edit .claude/settings.json — update the SessionStart message with your project name
5. That's it. Start a Claude Code session and it will read the compact index first

For research projects, use templates/research-project/ instead — same structure but arch_decisions.md is replaced by research_decisions.md and the agents are tuned for experiment design.

---

How the Patterns Work Together

Session opens
    │
    ▼
SessionStart hook fires
    → Claude reads MEMORY.md (4 lines, always)
    → Claude reads session_state.md (what was pending)
    │
    ├─ Simple task ("where is X?")
    │       → @researcher (Haiku, read-only) answers it
    │       → Done. Opus/Sonnet never loaded.
    │
    ├─ Implementation task
    │       → Claude reads project_state.md
    │       → Delegates to @developer (Sonnet)
    │       → @developer reads only the relevant files
    │
    └─ Architecture decision
            → Claude reads arch_decisions.md
            → Delegates to @architect (Opus)
            → @architect produces ADR
            → session_state.md updated at end

Context nears limit
    │
    ▼
PreCompact hook fires
    → Claude updates session_state.md BEFORE compression
    → Next session resumes from that checkpoint

---

What's Actually Documented by Anthropic vs Community Patterns

Feature	Status
.claude/agents/ directory and frontmatter	✅ Official docs
model, tools, effort in agent frontmatter	✅ Official
SessionStart hook	✅ Official (hooks system)
PreCompact hook	✅ Official (hooks system)
Stop hook	✅ Official
MEMORY.md compact index pattern	🔶 Community pattern
Agent-to-agent context handoff protocol	🔶 Community pattern
research_decisions.md vs arch_decisions.md split	🔶 Community pattern

---

Contributing

If you adapt this template for your project and discover improvements, PRs are welcome. Specifically interested in:

• Templates for other project types (mobile, data pipeline, monorepo)
• Hook patterns for CI/CD integration
• Agent configurations for specific domains (security, data science, DevOps)

---

License

MIT — use freely, attribution appreciated.