Developing Software Projects with Claude Code + OpenSpec + Multi-role Agents
An in-depth, hands-on tutorial on building a development pipeline from scratch to full autonomy. Using the doc2video case project, this tutorial provides a deep dive into leveraging Claude Code and the OpenSpec specification system to construct a multi-role collaborative AI automated development pipeline.
COURSE CONTENT
Chapter 01 | Why We Need AI, Specifications, and Multiple Roles
Upon completing this chapter, you'll be able to explain to your colleagues in three sentences why you shouldn't let Claude solo-code an entire project.
Chapter 02 | Example Project doc2video: The Big Picture
Understand the project you'll be building throughout this tutorial. This ensures you can connect every subsequent abstract concept to a specific, practical scenario.
Chapter 03 | Mental Model — Three-tier Architecture
Master the 'Tools/Knowledge/Governance' three-layer model; all subsequent chapters will map to this framework.
Chapter 04 | Environment Setup Checklist
Ensure your machine has all the prerequisites installed to run the doc2video project.
Chapter 05 | Install Claude Code
Run the `claude` command to complete your first conversation.
Chapter 06 | Install OpenSpec
Enable your project directory with OpenSpec specification capabilities.
Chapter 07 | The Worldview of OpenSpec
Understand why OpenSpec is not a 'mere document system'—but rather, a **specification version control system**.
Chapter 08 | Using `/opsx:explore` to Explore Ideas
Learn to 'think clearly before acting'—leverage 'explore mode' to clarify ambiguous ideas into actionable decisions.
Chapter 09 | Decisions Are Trade-offs
Learn to apply decision matrix thinking to transform "I want to do X" into "I accept the cost of Y to achieve X."
Chapter 10 | Propose Changes with `/opsx:propose`
Run `/opsx:propose` once to generate the full four-piece set: proposal / design / specs / tasks.
Chapter 11 | Writing design.md
Formalize all decisions made during the exploration phase into a document that reviewers can still verify three months later.
Chapter 12 | Writing Specs — Requirements and Scenarios
Write testable contracts. Each Scenario should map to a pytest function.
Chapter 13 | Writing tasks.md
Translate the spec into executable 'groups' – the smallest unit of dispatch.
Chapter 14 | What is a Subagent
Understand the relationship between subagents and main Claude, and the cost and value of dispatch.
Chapter 15 | Role Division — Avoiding the 'God Agent' Trap
Learn to decompose agents by responsibility, enabling multiple agents to mutually check and balance each other rather than each claiming its own domain.
Chapter 16 | Writing Agent Files
Develop agent files that are discoverable and dispatchable by main Claude.
Chapter 17 | Model Selection Strategy
Implement role-based model assignment to avoid the prohibitive costs of an 'all Opus' strategy or the performance bottlenecks of an 'all Sonnet' approach.
Chapter 18 | Advanced: Escalation and Architect
Mastering the 'Stuck Auto-Upgrade' mode enables multi-agent systems to evolve continuously when encountering complex problems, preventing them from entering infinite loops.
Chapter 19 | CLAUDE.md — Project Constitution
Develop a CLAUDE.md document that enables any core contributor joining the project to immediately adhere to its guidelines.
Chapter 20 | File-Based State Machine
Grasping why state must persist in files instead of residing solely in-memory is the critical distinction for systems evolving from 'toy' to 'production-grade'.
Chapter 21 | Customizing Slash Commands `/dev`
Encapsulate the orchestration logic into a single user-triggerable command.
Chapter 22 | Trigger Mode: Semi-manual and Fully Automatic
Enable `/dev` to flexibly switch between 'total control' and 'hands-off' modes.
Chapter 23 | settings.json: Comprehensive Overview
Understanding the priority and purpose of the four types of settings files enables their correct placement for team, individual, and experimental scopes.
Chapter 24 | Permission Mode
Prevent Claude Code from prompting you at every step, while ensuring it automatically blocks dangerous operations.
Chapter 25 | PreToolUse Hook: Dynamic Validation
Develop a script to intercept seemingly benign but actually harmful bash commands.
Chapter 26 | Stop hook: Notification Integration
Get proactive notifications from main Claude (Telegram / Slack / Email) upon output completion, allowing you to step away from your computer without losing progress.
Chapter 27 | First Run of `/dev`
Synthesize the knowledge from the first 26 chapters to execute your first line of real code.
Chapter 28 | Debugging and Troubleshooting
Acquire the skills to identify problem sources and apply effective solutions, enabling independent resolution of 90% of common issues.
Chapter 29 | Sandbox Selection
Knowing when to adopt Docker, when not to, and how to make compromises—all based on your project's practical constraints.
Chapter 30 | Advanced: Team, CI, Extensibility
Adapt this workflow to other scenarios: multi-user, CI, and new roles.