Chapter 1: Why "AI + Specification + Multi-Role" is Needed
Learning Objectives
After reading this chapter, you will be able to explain to colleagues in three sentences why you shouldn't let Claude Code "one-shot" an entire project.
Three Real Pain Points
If you've only used "raw" AI programming (opening a chat, letting Claude write code directly, copying, submitting), you've likely encountered these three issues:
Pain Point 1: Requirements Live Only in Chat
Today you tell Claude: "This feature is for logged-in users."
Tomorrow, after /clear, you tell it: "Modify the login logic."
→ It doesn't remember the constraint "must support logged-in users."
→ You have to explain it all over again.
→ Three months later, no one remembers why it was designed this way.
Pain Point 2: Single Agent Writes, Tests, and Reviews
You tell Claude: "Write code + write tests."
It writes a piece of code → then writes a test that "just happens to pass its own code."
Tests pass 100%, but in reality, they test nothing meaningful.
You can't tell, because its output looks very professional.
Pain Point 3: Unrestricted Permissions
You clicked "Always Allow Bash" once.
Claude later ran `rm -rf node_modules`.
As a result, when parsing the path, it included `~/Documents`.
Your collection of resume videos is gone.
Three Corresponding Solutions
flowchart LR
P1["Pain Point 1
Requirements in Chat"] --> S1["Specification Layer
OpenSpec"]
P2["Pain Point 2
Single Agent Self-Validation"] --> S2["Governance Layer
Multi-Role + Checks & Balances"]
P3["Pain Point 3
Unrestricted Permissions"] --> S3["Security Layer
Permission + Hook"]
S1 --> R["Alignable
Auditable
Evolvable"]
S2 --> R
S3 --> R| Solution | How it Solves It | This Tutorial Chapter |
|---|---|---|
| OpenSpec | Make requirements/designs/tasks into git-friendly markdown, versioned alongside code | Ch 7~13 |
| Multi-Role Agents | Developer writes, tester tests, reviewer reviews, e2e-tester verifies, ensuring no role oversteps boundaries | Ch 14~18 |
| Permission + Hook | Static rules reject dangerous operations + dynamic scripts block path traversal | Ch 23~26 |
Not "Over-Engineering"
You might be thinking: "This seems much more complex than just letting Claude write code directly. Is it worth it?"
The criterion is simple:
"Will someone taking over this project six months from now know exactly what it's supposed to do?"
- If the answer is yes → You need this system.
- If the answer is no → You need at least part of it.
The doc2video project, which this tutorial is based on, is a real-world medium-sized project: 61 development tasks, 13 groups, and 4 agent roles. Manually managing details of this scale would quickly lead to cognitive overload.
What You Can Do Now
- Explain the three pain points of AI programming clearly to colleagues.
- Determine whether your project "should adopt specifications + multi-role agents."
In the next chapter, we'll look at what the actual project we'll be building looks like.