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

Design & Architecture (5 agents)

| 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) |

Development & Quality (5 agents)

| 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 |

Operations & Management (5 agents)

| 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 |

Additional Specialists (3 agents)

| 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

Prerequisites

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

Installation

Option 1: Install with npx (Recommended)

The fastest way to get started:

# 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:

# 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

Verification

After installation, verify the setup:

# 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

Usage

1. Start Claude Code:

   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

Example 1: Full-Stack Feature Development

👤 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

Example 2: Performance Optimization

👤 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

Example 3: Security Audit & Remediation

👤 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:

Phase 1: Requirements & Design

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

Phase 2: Implementation

• ✅ 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

Phase 3: Quality Assurance

• ✅ 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

Phase 4: Deployment Readiness

• ✅ 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

Phase 5: Production Deployment

• ✅ 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

1. Parallel Execution Strategy

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

2. Definition of Done Enforcement

• 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. Interactive Dialogue Flow

• 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)

4. Code Review Integration

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

5. Production Build Verification

• 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:

Configured MCP Servers

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

MCP Usage Example

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

Standard Workflow: Full-Stack Development

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.

How to Contribute

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

Areas for Contribution

• 🤖 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