Specification Driven Development with Claude Code


English | 日本語

A comprehensive Specification Driven Development (SDD) system powered by Claude Code's multi-agent architecture, orchestrating 18 specialized AI agents to deliver high-quality software development workflows from requirements analysis to production deployment.

🌟 Key Features

- 🤖 18 Specialized AI Agents: Expert agents covering design, development, quality assurance, operations, and specialized domains
- ⚡ Distributed Parallel Execution: Multiple agents work concurrently on independent tasks for maximum efficiency
- ✅ Definition of Done (DoD) Framework: Phase-based code reviews and production builds ensure quality gates at every stage
- 💬 Interactive Dialogue Flow: Each agent uses a standardized 5-phase conversation pattern for thorough requirement gathering
- 🔌 MCP Integration: Real-time access to up-to-date documentation via Context7, Microsoft Learn, and Azure MCP servers
- 📊 Comprehensive Reporting: Automated generation of execution plans, logs, and summary reports

---

🏗️ System Architecture

``
┌─────────────────────────────────────────────────────────────────┐
│ Orchestrator AI │
│ (Manages & Coordinates 18 Specialized Agents) │
└───────────────────────────┬─────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ Design & │ │ Development & │ │ Operations & │
│ Architecture │ │ Quality │ │ Management │
│ (5 agents) │ │ (5 agents) │ │ (5 agents) │
└───────────────┘ └───────────────┘ └───────────────┘
│ │ │
└───────────────────┼───────────────────┘
│
▼
┌───────────────────────┐
│ Additional Specialists │
│ (3 agents) │
└───────────────────────┘
`

---

🤖 18 Specialized AI Agents

$3

| Agent | Role | Key Deliverables |
|-------|------|------------------|
| Requirements Analyst | Requirements definition & analysis | SRS, functional/non-functional requirements, user stories |
| System Architect | System design & architecture | C4 model diagrams, ADR, architecture documents |
| API Designer | API design & specification | OpenAPI specs, GraphQL schemas, API documentation |
| Database Schema Designer | Database design & modeling | ER diagrams, DDL, normalization analysis, migration plans |
| Cloud Architect | Cloud infrastructure design | Cloud architecture diagrams, IaC code (Terraform, Bicep) |

$3

| Agent | Role | Key Deliverables |
|-------|------|------------------|
| Software Developer | Code implementation | Production-ready source code, unit tests, integration tests |
| Code Reviewer | Code quality review | Review reports, improvement suggestions, refactoring plans |
| Test Engineer | Test design & implementation | Test code, test design documents, comprehensive test cases |
| Security Auditor | Security auditing | Vulnerability reports, remediation plans, security guidelines |
| Quality Assurance | QA strategy & planning | Test plans, quality metrics, QA reports |

$3

| Agent | Role | Key Deliverables |
|-------|------|------------------|
| Project Manager | Project management | Project plans, WBS, Gantt charts, risk registers |
| DevOps Engineer | CI/CD & infrastructure automation | Pipeline definitions, Dockerfiles, Kubernetes manifests |
| Bug Hunter | Bug investigation & fixes | Bug reports, root cause analysis, fix implementations |
| Performance Optimizer | Performance optimization | Performance reports, optimization code, benchmark results |
| Technical Writer | Technical documentation | API docs, README, user guides, runbooks |

$3

| Agent | Role | Key Deliverables |
|-------|------|------------------|
| UI/UX Designer | UI/UX design & prototyping | Wireframes, mockups, interactive prototypes, design systems |
| Database Administrator | Database operations & tuning | Performance tuning reports, backup/recovery plans, HA configurations |
| AI/ML Engineer | ML model development & MLOps | Trained models, model cards, deployment pipelines, evaluation reports |

---

🚀 Quick Start

$3

- Claude Code CLI: Install Claude Code
- Node.js: v18 or higher (for MCP servers)

$3

#### Option 1: Install with npx (Recommended)

The fastest way to get started:

`bash


Navigate to your project directory

cd your-project

Install Claude Code agents

npx create-sddwcc

Start Claude Code

claude-code
`

That's it! The .claude directory with all 18 agents and the orchestrator will be installed in your project.

#### Option 2: Clone from GitHub

If you want to explore or customize the agents:

`bash


Clone the repository

git clone https://github.com/nahisaho/sddwcc.git
cd sddwcc

Copy .claude directory to your project

cp -r CLAUDE_CODE/.claude /path/to/your/project/

Or create a symlink

ln -s $(pwd)/CLAUDE_CODE/.claude /path/to/your/project/.claude
`

$3

After installation, verify the setup:

`bash


Check agent files (should show 19 files)

ls -la .claude/agents/

Check MCP configuration

cat .claude/claude.json

View orchestrator documentation

cat .claude/agents/orchestrator.md
`

$3

1. Start Claude Code:
`bash
claude-code
`

2. Invoke the Orchestrator:
`
👤 User: [Describe your project or task]

Example:
"Build a RESTful API for a task management system with authentication,
database design, CI/CD pipeline, and comprehensive documentation."
`

3. Follow the interactive workflow:
- Orchestrator analyzes your request and creates an execution plan
- Selects optimal agents (sequential or parallel execution)
- Each agent follows a 5-phase dialogue flow to gather requirements
- Agents generate deliverables with automatic DoD verification
- Orchestrator consolidates results into comprehensive reports

---

📁 Directory Structure

`
sddwcc/
├── README.md # This file
├── CLAUDE_CODE/
│ ├── CLAUDE.md # System documentation
│ ├── .claude/
│ │ ├── claude.json # MCP server configuration
│ │ └── agents/ # 19 agent definitions
│ │ ├── orchestrator.md # Main orchestrator agent
│ │ ├── requirements-analyst.md
│ │ ├── system-architect.md
│ │ ├── api-designer.md
│ │ ├── database-schema-designer.md
│ │ ├── cloud-architect.md
│ │ ├── software-developer.md
│ │ ├── code-reviewer.md
│ │ ├── test-engineer.md
│ │ ├── security-auditor.md
│ │ ├── quality-assurance.md
│ │ ├── project-manager.md
│ │ ├── devops-engineer.md
│ │ ├── bug-hunter.md
│ │ ├── performance-optimizer.md
│ │ ├── technical-writer.md
│ │ ├── ui-ux-designer.md
│ │ ├── database-administrator.md
│ │ └── ai-ml-engineer.md
│ ├── design/ # Agent-generated design artifacts
│ │ ├── api/ # API specifications
│ │ ├── architecture/ # Architecture documents
│ │ ├── cloud/ # Cloud infrastructure designs
│ │ ├── database/ # Database schemas & migrations
│ │ └── ui/ # UI/UX designs & prototypes
│ ├── orchestrator/ # Orchestrator outputs
│ │ ├── plans/ # Execution plans
│ │ ├── logs/ # Execution logs
│ │ └── reports/ # Summary reports
│ └── docs/ # Additional documentation
└── References/ # Reference materials
`

---

💡 Usage Examples

$3

`markdown
👤 User: "Develop a user authentication system with JWT tokens,
including database schema, REST API, security audit,
and deployment pipeline."

🤖 Orchestrator:
Execution Plan:

Phase 1: Design (Parallel)
├─ Requirements Analyst → User authentication requirements
├─ Database Schema Designer → Users & tokens tables
└─ API Designer → Auth endpoints (login, register, refresh)

Phase 2: Implementation
└─ Software Developer → Auth service + unit tests

Phase 3: Quality Assurance (Parallel)
├─ Code Reviewer → Code quality review
├─ Security Auditor → OWASP Top 10 check
└─ Test Engineer → Integration & E2E tests

Phase 4: Deployment
├─ DevOps Engineer → CI/CD pipeline + Docker
└─ Technical Writer → API documentation

DoD Gates: 4 checkpoints with code reviews and production builds
`

$3

`markdown
👤 User: "Our API response time is slow. Analyze and optimize performance."

🤖 Orchestrator:
Execution Plan:

Phase 1: Analysis
└─ Performance Optimizer → Bottleneck analysis

Phase 2: Implementation
└─ Performance Optimizer → Optimization implementation

Phase 3: Validation (Parallel)
├─ Code Reviewer → Review optimized code
├─ Test Engineer → Performance benchmarks
└─ Technical Writer → Optimization documentation

DoD Gates: 3 checkpoints with benchmarks and production builds
`

$3

`markdown
👤 User: "Perform a comprehensive security audit and fix vulnerabilities."

🤖 Orchestrator:
Execution Plan:

Phase 1: Audit (Parallel)
├─ Security Auditor → Vulnerability scan (OWASP Top 10)
└─ Code Reviewer → Code security review

Phase 2: Remediation
└─ Bug Hunter → Fix identified vulnerabilities

Phase 3: Validation
├─ Test Engineer → Security test cases
└─ Technical Writer → Security documentation

DoD Gates: 3 checkpoints with security reviews and tests
`

---

✅ Definition of Done (DoD) Framework

Every development phase includes mandatory quality gates:

$3

- ✅ Design review completed
- ✅ Stakeholder sign-off obtained
- ✅ All designs validated for consistency

$3

- ✅ Code Reviewer: Comprehensive code review passed
- ✅ Production Build: npm run build succeeds without errors
- ✅ Unit Tests: npm test -- --coverage passes (≥80% coverage)
- ✅ Static Analysis: All linting and type-checking passes

$3

- ✅ Security Auditor: No critical vulnerabilities (OWASP Top 10)
- ✅ Performance Optimizer: Benchmarks meet acceptance criteria
- ✅ Integration Tests: npm run test:integration passes
- ✅ E2E Tests: npm run test:e2e passes
- ✅ Production Build: npm run build:production with optimizations succeeds

$3

- ✅ CI/CD Pipeline: Full pipeline executes successfully
- ✅ Staging Deployment: npm run deploy:staging succeeds
- ✅ Smoke Tests: npm run test:smoke -- --env=staging passes
- ✅ Rollback Test: Rollback procedure verified

$3

- ✅ Final Build: npm run build:production verified
- ✅ Production Deployment: npm run deploy:production succeeds
- ✅ Smoke Tests: Production smoke tests pass
- ✅ Monitoring: All dashboards active and reporting

---

🔧 Best Practices

$3

- Identify Independent Tasks: Analyze dependencies upfront
- Launch Concurrently: Run independent agents simultaneously
- Consolidate Results: Orchestrator integrates all outputs

$3

- Every Implementation Phase: Code review + production build verification
- No Skipping Quality Gates: Each DoD must be satisfied before proceeding
- Automated Validation: Leverage CI/CD for consistent checks

$3

- Phase 1-2: Requirement gathering (one question at a time)
- Phase 3: Confirmation (prevent misunderstandings)
- Phase 4: Deliverable generation (with file outputs)
- Phase 5: Feedback loop (iterate until complete)

$3

- Code Reviewer: Invoked at every implementation phase
- Security Auditor: Reviews all code changes for vulnerabilities
- Performance Optimizer: Reviews critical performance paths

$3

- Implementation Phase: npm run build must succeed
- Pre-Deployment: npm run build:production with optimizations
- Bundle Analysis: Verify size, tree-shaking, code-splitting effectiveness

---

🔌 MCP Server Integration

The system leverages Model Context Protocol (MCP) for real-time documentation access:

$3

1. Context7 MCP
- Purpose: Up-to-date documentation for any library
- Package: @context7/mcp-server
- Usage: Latest framework documentation (React, Vue, Angular, etc.)

2. Microsoft Learn MCP
- Purpose: Microsoft Learn documentation and tutorials
- Endpoint: https://learn.microsoft.com/api/mcp
- Usage: .NET, Azure, TypeScript, VS Code documentation

3. Azure MCP
- Purpose: Interact with Azure resources and services
- Package: @azure/mcp@latest
- Usage: Azure-specific implementation guidance

$3

`markdown
Agent: Software Developer
Query: "Latest React 18 hooks best practices"
Context7 MCP → Fetches current React documentation

Agent: Cloud Architect
Query: "Azure Container Apps configuration"
Azure MCP → Retrieves Azure-specific deployment guidance
`

---

📊 Workflow Examples

$3

`
Phase 1: Requirements & Design
├─ Requirements Analyst (sequential)
├─ Database Schema Designer (parallel)
├─ API Designer (parallel)
├─ UI/UX Designer (parallel)
└─ System Architect (sequential integration)
DoD Gate 1: Design Review ✅

Phase 2: Implementation
└─ Software Developer (sequential)
DoD Gate 2: Code Review + Build + Tests ✅

Phase 3: Quality Assurance
├─ Code Reviewer (parallel)
├─ Security Auditor (parallel)
├─ Performance Optimizer (parallel)
└─ Test Engineer (sequential)
DoD Gate 3: All QA Checks ✅

Phase 4: Deployment
├─ DevOps Engineer (sequential)
└─ Technical Writer (sequential)
DoD Gate 4: CI/CD + Staging ✅

Phase 5: Production
└─ DevOps Engineer (deployment)
DoD Gate 5: Production Verified ✅
`

---

📖 Documentation

- System Overview: CLAUDE.md
- Orchestrator Agent: orchestrator.md
- Agent Definitions: agents/
- MCP Configuration: claude.json

---

🤝 Contributing

Contributions are welcome! This is an experimental system for Specification Driven Development with Claude Code.

$3

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes: Add new agents, improve workflows, enhance documentation
4. Test your changes: Ensure all agents work correctly
5. Commit: git commit -m "Add your feature"
6. Push: git push origin feature/your-feature`
7. Create a Pull Request

$3

- 🤖 New Agents: Add specialized agents for specific domains
- 📚 Documentation: Improve guides, tutorials, examples
- 🔧 Workflows: Design new standard workflows for common scenarios
- 🧪 Testing: Add validation and testing strategies
- 🎨 Templates: Create reusable templates for common deliverables

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

- Anthropic Claude: For the powerful Claude Code platform
- Model Context Protocol: For enabling real-time documentation access
- Community: For feedback and contributions to Specification Driven Development

---

📞 Support

- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: CLAUDE.md

---

Specification Driven Development with Claude Code

"Build Better Software with 18 Expert AI Agents, Distributed Parallel Execution, and Definition of Done Quality Gates"

---

🎯 Success Metrics

When using this system, you can expect:

- ✅ Requirements Phase: Stakeholder-approved specifications with zero ambiguity
- ✅ Design Phase: Comprehensive architecture with reviewed design documents
- ✅ Implementation Phase: Production-ready code with ≥80% test coverage
- ✅ Quality Phase: Zero critical vulnerabilities, performance benchmarks met
- ✅ Deployment Phase: Automated CI/CD with validated rollback procedures
- ✅ Production Phase: Successful deployment with active monitoring

---

Built with ❤️ using Claude Code's Multi-Agent Architecture