Subagent-Driven Development
This approach is ideal for large-scale refactoring, parallel development streams, complex features requiring multiple expertise areas, and high-risk changes requiring thorough validation.
Each agent has specific responsibilities, produces artifacts for the next phase, and must pass quality gates before proceeding. Enable parallel execution where possible.
Parallel Development Pattern
- Identify independent work streams
- Create separate agent chains for each stream
- Execute streams in parallel
- Integration phase to merge streams
- End-to-end testing
- Final review and approval
Quality Gates (Should Have - Warning)
- Code coverage >80%
- Documentation complete
- No review comments unresolved
- Performance optimized
Agent Boundaries
- Each agent has specific responsibility
- No overlap between agents
- Clear handoff documentation
- Artifacts passed between phases
Phase Execution
- Don't proceed until quality gate passes
- Each phase must be reversible
- Document all handoffs
- Track quality gate results
<best_practices>
Agent Specializations
1. Planning Agent
Responsibility: Break down complex tasks into actionable steps
Input:
- High-level requirement
- Constraints and preferences
- Existing codebase context
Output:
- Detailed implementation plan
- Risk assessment
- Dependencies identified
- Success criteria defined
Quality Gate:
- Plan is comprehensive
- Risks are identified
- Steps are actionable
- Success criteria clear
2. Implementation Agent
Responsibility: Execute the plan with clean, tested code
Input:
- Approved implementation plan
- Code to modify
- Testing requirements
Output:
- Implemented changes
- Unit tests
- Integration points updated
Quality Gate:
- Code follows plan
- Tests pass locally
- No regressions
- Code is clean
3. Review Agent
Responsibility: Critical analysis of implementation
Input:
- Implementation changes
- Original plan
- Codebase standards
Output:
- Code review feedback
- Security concerns
- Performance issues
- Improvement suggestions
Quality Gate:
- No critical issues
- Security reviewed
- Performance acceptable
- Standards followed
4. Testing Agent
Responsibility: Comprehensive testing validation
Input:
- Implemented changes
- Test requirements
- Edge case scenarios
Output:
- Test results
- Coverage report
- Bug findings
- Performance metrics
Quality Gate:
- All tests pass
- Coverage threshold met
- No critical bugs
- Performance within limits
5. Documentation Agent
Responsibility: Complete documentation updates
Input:
- Final implementation
- API changes
- User-facing features
Output:
- Updated documentation
- API reference
- Migration guides
- Changelog entry
Quality Gate:
- Docs are accurate
- Examples work
- Migration guide clear
- Changelog complete
Best Practices
- Clear Agent Boundaries: Each agent has a specific responsibility and doesn't overlap with others
- Handoff Documentation: Each phase produces artifacts for the next phase
- Quality Gates Are Strict: Don't proceed to next phase until quality gate passes
- Rollback Strategy: Each phase should be reversible if issues are found
- Parallel When Possible: Independent streams can run simultaneously </best_practices>
Phase 1: Planning
Agent: Planning Specialist Task: Analyze current auth system, design new architecture Deliverable: 10-page implementation plan with risk assessment Quality Gate: ✅ Plan approved
Phase 2: Implementation
Agent: Backend Developer Task: Implement new auth service with OAuth 2.0 Deliverable: Working auth service with unit tests Quality Gate: ✅ All tests pass
Phase 3: Security Review
Agent: Security Specialist Task: Audit authentication flow for vulnerabilities Deliverable: Security report with recommendations Quality Gate: ⚠️ 3 medium-severity issues found
Phase 4: Fix Implementation
Agent: Backend Developer Task: Address security issues Deliverable: Updated code with fixes Quality Gate: ✅ All issues resolved
Phase 5: Integration Testing
Agent: QA Specialist Task: Test auth flows across all applications Deliverable: Test report with coverage metrics Quality Gate: ✅ 95% coverage, no critical bugs
Phase 6: Documentation
Agent: Technical Writer Task: Update API docs and migration guides Deliverable: Complete documentation set Quality Gate: ✅ Docs accurate and complete
Phase 7: Final Review
Agent: Architect Task: Validate entire refactoring Deliverable: Final approval Quality Gate: ✅ Approved for merge
## Parallel Development Pattern
```markdown
## Parallel Refactoring
### Stream 1: Backend API
- [ ] Planning: Design new API structure
- [ ] Implementation: Build new endpoints
- [ ] Testing: Verify API contracts
- [ ] Review: Security and performance
### Stream 2: Frontend Integration
- [ ] Planning: Update component structure
- [ ] Implementation: Connect to new API
- [ ] Testing: Verify user flows
- [ ] Review: UX and accessibility
### Stream 3: Data Migration
- [ ] Planning: Design migration script
- [ ] Implementation: Build migration tool
- [ ] Testing: Verify data integrity
- [ ] Review: Rollback strategy
### Integration Phase
- [ ] Merge all streams
- [ ] End-to-end testing
- [ ] Final review
- [ ] Deploy
<integration_notes>
When to Use This Skill
✅ Large-scale refactoring across many files ✅ Parallel development streams ✅ Complex feature requiring multiple expertise areas ✅ High-risk changes requiring thorough validation ✅ Tasks needing separation of concerns
Common Mistakes
❌ Skipping quality gates: "Let's just fix it later" ❌ Blurry agent boundaries: Multiple agents doing same work ❌ Poor handoffs: Next agent doesn't have context ❌ No rollback: Can't undo if things go wrong ❌ Serial when parallel possible: Slowing down unnecessarily
Integration with Claude
When using subagent-driven development, say:
- "Use subagent-driven development for [complex task]"
- "Break this into phases with quality gates"
- "Run planning, implementation, and review agents"
- "Set up parallel streams for [feature set]"
Claude will:
- Identify appropriate agent specializations
- Define clear quality gates
- Produce handoff artifacts
- Respect phase boundaries
- Enable parallel execution where possible
- Ensure thorough validation at each step </integration_notes>
<output_format> Multi-phase execution with:
-
Phase Artifacts:
- Planning: Implementation plan, risk assessment, success criteria
- Implementation: Code changes, unit tests, integration updates
- Review: Code review feedback, security/performance analysis
- Testing: Test results, coverage report, bug findings
- Documentation: Updated docs, API reference, migration guides
-
Quality Gate Results:
- Pass/fail status for each gate
- Blocking issues identified
- Warnings and recommendations
- Approval decisions
-
Final Deliverable:
- All phases completed
- All quality gates passed
- Documentation updated
- Ready for deployment </output_format>