Chapter 03 | Mental Model — Three-tier Architecture

Chapter 3: Mental Model - The Three-Layer Architecture

Learning Objectives

Master the "Tooling/Knowledge/Governance" three-layer model. All subsequent chapters will map back to this diagram.

Three-Layer Architecture Diagram

flowchart TB
    subgraph G["Governance Layer (Governance)"]
        direction LR
        Agents["Multi-role agent
dev / tester / reviewer / e2e"]
        Perm["permission + hook"]
        Cmd["/dev Custom Commands"]
    end

    subgraph K["Knowledge Layer (Knowledge)"]
        direction LR
        Specs["specs/
Current System Commitments"]
        Changes["changes/
In-progress Changes"]
        Tasks["tasks.md
Executable Checklist"]
    end

    subgraph T["Tooling Layer (Tooling)"]
        direction LR
        CC["Claude Code
Main Process + Bash/Edit/Write"]
        Models["Model Routing
opus / sonnet / haiku"]
    end

    G -.->|Read/Write| K
    G -.->|Execute| T
    K -.->|Define Boundaries| T

    style G fill:#fce4ec
    style K fill:#e8f5e9
    style T fill:#e3f2fd

Company Analogy

Imagine the project as a small company:

The CEO doesn't write code but sets direction; the PM doesn't write code but orchestrates. Devs, QAs, and Reviewers each perform their duties. Everyone consults the same PRD (specs/)—not their individual remembered versions.

Why the Three-Layer Separation is Crucial

If you don't separate into layers, these confusions will occur:

flowchart LR
    Bad["No Layer Separation"] --> X1["Specs change, agent unaware"]
    Bad --> X2["Agent oversteps, modifies spec"]
    Bad --> X3["Permission rules scattered"]

    Good["Three-Layer Separation"] --> Y1["Specs change, all agents re-read"]
    Good --> Y2["Agent write permissions restricted by file path"]
    Good --> Y3["Permissions unified in settings.json"]

    style Bad fill:#ffcdd2
    style Good fill:#c8e6c9

The "Flow" Between Layers

You want to implement a new feature
   ↓
Governance Layer initiates: main Claude starts explore
   ↓
Knowledge Layer output: proposal + design + specs + tasks
   ↓
Governance Layer orchestrates: dispatch developer to implement task
   ↓
Tooling Layer executes: Claude Code uses Bash/Edit to write code
   ↓
Knowledge Layer updates: tasks.md checked off + review/N.md written
   ↓
Governance Layer decides: reviewer approves → proceed to next group

Chapter Correspondence

After completing Part VI, you will have a complete "Governance Layer"—combined with the preceding "Knowledge Layer + Tooling Layer," the entire system will be operational.

What You Can Do Now

• Draw the three-layer relationship diagram.
• For a specific feature (e.g., "add OAuth login"), describe which layer performs which action.
• Identify practices in real-world projects that constitute "layer leakage."

In the next chapter, we'll get hands-on—preparing the environment.