24 KiB
24 KiB
Multi-Agent Review Strategies
This file describes how to coordinate multiple specialized agents for comprehensive code review and quality assurance.
Agent Overview
Available Agents for Review
workflow-coordinator:
role: "Pre-review validation and workflow state management"
use_first: true
validates:
- Implementation phase completed
- All specification tasks done
- Tests passing before review
- Ready for review/completion phase
coordinates: "Transition from implementation to review"
criticality: MANDATORY
refactorer:
role: "Code quality and style review"
specializes:
- Code readability and clarity
- SOLID principles compliance
- Design pattern usage
- Code smell detection
- Complexity reduction
focus: "Making code maintainable and clean"
security:
role: "Security vulnerability review"
specializes:
- Authentication/authorization review
- Input validation checking
- Vulnerability scanning
- Encryption implementation
- Security best practices
focus: "Making code secure"
qa:
role: "Test quality and coverage review"
specializes:
- Test coverage analysis
- Test quality assessment
- Edge case identification
- Mock appropriateness
- Performance testing
focus: "Making code well-tested"
implementer:
role: "Documentation and feature completeness"
specializes:
- Documentation completeness
- API documentation review
- Code comment quality
- Example code validation
- Feature implementation gaps
focus: "Making code documented and complete"
architect:
role: "Architecture and design review"
specializes:
- Component boundary validation
- Dependency direction checking
- Abstraction level assessment
- Scalability evaluation
- Design pattern application
focus: "Making code architecturally sound"
when_needed: "Major changes, new components, refactoring"
Agent Selection Rules
MANDATORY: Workflow Coordinator First
Always Start with workflow-coordinator:
Pre-Review Protocol:
1. ALWAYS use workflow-coordinator agent first
2. workflow-coordinator validates:
- Implementation phase is complete
- All tasks in specification are done
- Tests are passing
- No blocking issues remain
3. If validation fails:
- Do NOT proceed to review
- Report incomplete work to user
- Guide user to complete implementation
4. If validation passes:
- Proceed to multi-agent review
NEVER skip workflow-coordinator validation!
Task-Based Agent Selection
Use this matrix to determine which agents to invoke:
Authentication/Authorization Feature:
agents:
- security: Security requirements and review (primary)
- refactorer: Code quality and structure
- qa: Security and integration testing
- implementer: Documentation completeness
reason: Security-critical feature needs security focus
API Development:
agents:
- refactorer: Code structure and patterns (primary)
- implementer: API documentation
- qa: API testing and validation
reason: API quality and documentation critical
Performance Optimization:
agents:
- refactorer: Code efficiency review (primary)
- qa: Performance testing validation
- architect: Architecture implications (if major)
reason: Performance changes need quality + testing
Security Fix:
agents:
- security: Security fix validation (primary)
- qa: Security test coverage
- implementer: Security documentation
reason: Security fixes need security expert review
Refactoring:
agents:
- refactorer: Code quality improvements (primary)
- architect: Design pattern compliance (if structural)
- qa: No regression validation
reason: Refactoring needs quality focus + safety
Bug Fix:
agents:
- refactorer: Code quality of fix (primary)
- qa: Regression test addition
reason: Simple bug fixes need basic review
Documentation Update:
agents:
- implementer: Documentation quality (primary)
reason: Documentation changes need content review only
New Feature (Standard):
agents:
- refactorer: Code quality and structure
- security: Security implications
- qa: Test coverage and quality
- implementer: Documentation completeness
reason: Standard features need comprehensive review
Major System Change:
agents:
- architect: Architecture validation (primary)
- refactorer: Code quality review
- security: Security implications
- qa: Comprehensive testing
- implementer: Documentation update
reason: Major changes need all-hands review
Agent Coordination Patterns
Pattern 1: Parallel Review (Standard)
When to Use: Most feature reviews where agents can work independently.
Parallel Review Pattern:
Spawn 4 agents simultaneously:
- refactorer: Review code quality
- security: Review security
- qa: Review testing
- implementer: Review documentation
Each agent focuses on their domain independently
Wait for all agents to complete
Consolidate results into unified review summary
Advantages:
- Fast (all reviews happen simultaneously)
- Comprehensive (all domains covered)
- Independent (no agent blocking others)
Time: ~5-10 minutes
Example: New Feature Review
Review Authentication Feature:
Spawn in Parallel:
Use the refactorer agent to:
- Review code structure and organization
- Check SOLID principles compliance
- Identify code smells
- Suggest improvements
Use the security agent to:
- Review authentication logic
- Check password hashing
- Validate token handling
- Identify security risks
Use the qa agent to:
- Analyze test coverage
- Check edge case handling
- Validate test quality
- Identify missing tests
Use the implementer agent to:
- Review API documentation
- Check code comments
- Validate examples
- Identify doc gaps
Wait for All Completions
Consolidate:
- Combine all agent findings
- Identify common themes
- Prioritize issues
- Generate unified review summary
Pattern 2: Sequential Review with Validation
When to Use: Critical features where one review informs the next.
Sequential Review Pattern:
Step 1: First agent reviews
→ Wait for completion
→ Analyze findings
Step 2: Second agent reviews (builds on first)
→ Wait for completion
→ Analyze findings
Step 3: Third agent reviews (builds on previous)
→ Wait for completion
→ Final analysis
Advantages:
- Each review informs the next
- Can adjust focus based on findings
- Deeper analysis possible
Time: ~15-20 minutes
Example: Security-Critical Feature Review
Review Security Feature:
Step 1: Use the security agent to:
- Deep security analysis
- Identify vulnerabilities
- Define security requirements
- Assess risk level
Output: Security requirements document + vulnerability report
Step 2: Use the refactorer agent to:
- Review code with security context
- Check if vulnerabilities addressed
- Ensure secure coding patterns
- Validate security requirements met
Context: Security agent's findings
Output: Code quality + security compliance report
Step 3: Use the qa agent to:
- Review tests with security focus
- Ensure vulnerabilities tested
- Check security edge cases
- Validate security test coverage
Context: Security requirements + code review
Output: Test coverage + security testing report
Step 4: Use the implementer agent to:
- Document security implementation
- Document security tests
- Add security examples
- Document threat model
Context: All previous reviews
Output: Documentation completeness report
Pattern 3: Iterative Review with Fixing
When to Use: When issues are expected and fixes needed during review.
Iterative Review Pattern:
Loop:
1. Agent reviews and identifies issues
2. Same agent (or another) fixes issues
3. Re-validate fixed issues
4. If new issues: repeat
5. If clean: proceed to next agent
Advantages:
- Issues fixed during review
- Continuous improvement
- Final review is clean
Time: ~20-30 minutes (depends on issues)
Example: Refactoring Review with Fixes
Review Refactored Code:
Iteration 1 - Code Quality:
Use the refactorer agent to:
- Review code structure
- Identify 3 issues:
• Function too long (85 lines)
• Duplicate code in 2 places
• Complex nested conditionals
Use the refactorer agent to:
- Break long function into 4 smaller ones
- Extract duplicate code to shared utility
- Flatten nested conditionals
Validate: All issues fixed ✅
Iteration 2 - Testing:
Use the qa agent to:
- Review test coverage
- Identify 2 issues:
• New functions not tested
• Edge case missing
Use the qa agent to:
- Add tests for new functions
- Add edge case test
Validate: Coverage now 89% ✅
Iteration 3 - Documentation:
Use the implementer agent to:
- Review documentation
- Identify 1 issue:
• Refactored functions missing docstrings
Use the implementer agent to:
- Add docstrings to all new functions
- Update examples
Validate: All documented ✅
Final: All issues addressed, ready to ship
Pattern 4: Focused Review (Subset)
When to Use: Small changes or specific review needs.
Focused Review Pattern:
Select 1-2 agents based on change type:
- Bug fix → refactorer + qa
- Docs update → implementer only
- Security fix → security + qa
- Performance → refactorer + qa
Only review relevant aspects
Skip unnecessary reviews
Advantages:
- Fast (minimal agents)
- Focused (relevant only)
- Efficient (no wasted effort)
Time: ~3-5 minutes
Example: Bug Fix Review
Review Bug Fix:
Use the refactorer agent to:
- Review fix code quality
- Check if fix is clean
- Ensure no new issues introduced
- Validate fix approach
Use the qa agent to:
- Verify regression test added
- Check test quality
- Ensure bug scenario covered
- Validate no other tests broken
Skip:
- security (not security-related)
- implementer (no doc changes)
- architect (no design changes)
Result: Fast, focused review in ~5 minutes
Review Aspect Coordination
Code Quality Review (refactorer)
Review Focus:
Readability:
- Variable/function names clear
- Code organization logical
- Comments appropriate
- Formatting consistent
Design:
- DRY principle applied
- SOLID principles followed
- Abstractions appropriate
- Patterns used correctly
Maintainability:
- Functions focused and small
- Complexity low
- Dependencies minimal
- No code smells
Consistency:
- Follows codebase conventions
- Naming patterns consistent
- Error handling uniform
- Style guide compliance
Review Output Format:
Code Quality Review by refactorer:
✅ Strengths:
• Clean separation of concerns in auth module
• Consistent error handling with custom exceptions
• Good use of dependency injection pattern
• Function sizes appropriate (avg 25 lines)
⚠️ Suggestions:
• Consider extracting UserValidator to separate class
• Could simplify nested conditionals in authenticate()
• Opportunity to cache user lookups for performance
• Some variable names could be more descriptive (e.g., 'data' → 'user_data')
🚨 Required Fixes:
• None
Complexity Metrics:
• Average cyclomatic complexity: 3.2 (target: <5) ✅
• Max function length: 42 lines (target: <50) ✅
• Duplicate code: 0.8% (target: <2%) ✅
Security Review (security)
Review Focus:
Authentication:
- Password storage secure (hashing)
- Token validation robust
- Session management safe
- MFA properly implemented
Authorization:
- Permission checks present
- RBAC correctly implemented
- Resource ownership validated
- No privilege escalation
Input Validation:
- All inputs sanitized
- SQL injection prevented
- XSS prevented
- CSRF protection active
Data Protection:
- Sensitive data encrypted
- Secure communication (HTTPS)
- No secrets in code
- PII handling compliant
Vulnerabilities:
- No known CVEs in deps
- No hardcoded credentials
- No insecure algorithms
- No information leakage
Review Output Format:
Security Review by security:
✅ Strengths:
• Password hashing uses bcrypt with cost 12 (recommended)
• JWT validation includes expiry, signature, and issuer checks
• Input sanitization comprehensive across all endpoints
• No hardcoded secrets or credentials found
⚠️ Suggestions:
• Consider adding rate limiting to login endpoint (prevent brute force)
• Add logging for failed authentication attempts (security monitoring)
• Consider implementing password complexity requirements
• Could add request signing for critical API operations
🚨 Required Fixes:
• None - all critical security measures in place
Vulnerability Scan:
• Dependencies: 0 critical, 0 high, 1 low (acceptable)
• Code: No security vulnerabilities detected
• Secrets: No hardcoded secrets found
Test Coverage Review (qa)
Review Focus:
Coverage Metrics:
- Overall coverage ≥80%
- Critical paths 100%
- Edge cases covered
- Error paths tested
Test Quality:
- Assertions meaningful
- Test names descriptive
- Tests isolated
- No flaky tests
- Mocks appropriate
Test Types:
- Unit tests for logic
- Integration for flows
- E2E for critical paths
- Performance if needed
Test Organization:
- Clear structure
- Good fixtures
- Helper functions
- Easy to maintain
Review Output Format:
Test Coverage Review by qa:
✅ Strengths:
• Coverage at 87% (target: 80%) - exceeds requirement ✅
• Critical auth paths 100% covered
• Good edge case coverage (token expiry, invalid tokens, etc.)
• Test names clear and descriptive
• Tests properly isolated with fixtures
⚠️ Suggestions:
• Could add tests for token refresh edge cases (concurrent requests)
• Consider adding load tests for auth endpoints (performance validation)
• Some assertions could be more specific (e.g., check exact error message)
• Could add property-based tests for token generation
🚨 Required Fixes:
• None
Coverage Breakdown:
• src/auth/jwt.py: 92% (23/25 lines)
• src/auth/service.py: 85% (34/40 lines)
• src/auth/validators.py: 100% (15/15 lines)
Test Counts:
• Unit tests: 38 passed
• Integration tests: 12 passed
• Security tests: 8 passed
• Total: 58 tests, 0 failures
Documentation Review (implementer)
Review Focus:
API Documentation:
- All endpoints documented
- Parameters described
- Responses documented
- Examples provided
Code Documentation:
- Functions have docstrings
- Complex logic explained
- Public APIs documented
- Types annotated
Project Documentation:
- README up to date
- Setup instructions clear
- Architecture documented
- Examples working
Completeness:
- No missing docs
- Accurate and current
- Easy to understand
- Maintained with code
Review Output Format:
Documentation Review by implementer:
✅ Strengths:
• API documentation complete with OpenAPI specs
• All public functions have clear docstrings
• README updated with authentication section
• Examples provided and tested
⚠️ Suggestions:
• Could add more code examples for token refresh flow
• Consider adding architecture diagram for auth flow
• Some docstrings could include example usage
• Could document error codes more explicitly
🚨 Required Fixes:
• None
Documentation Coverage:
• Public functions: 100% (all documented)
• API endpoints: 100% (all in OpenAPI)
• README: Up to date ✅
• Examples: 3 working examples included
Architecture Review (architect)
When to Invoke:
Trigger Architecture Review:
- New system components added
- Major refactoring done
- Cross-module dependencies changed
- Database schema modified
- API contract changes
- Performance-critical features
Skip for:
- Small bug fixes
- Documentation updates
- Minor refactoring
- Single-file changes
Review Focus:
Component Boundaries:
- Clear separation of concerns
- Dependencies flow correctly
- No circular dependencies
- Proper abstraction layers
Scalability:
- Horizontal scaling supported
- No obvious bottlenecks
- Database queries optimized
- Caching appropriate
Maintainability:
- Easy to extend
- Easy to test
- Low coupling
- High cohesion
Future-Proofing:
- Flexible design
- Easy to modify
- Minimal technical debt
- Clear upgrade path
Review Output Format:
Architecture Review by architect:
✅ Strengths:
• Clean layered architecture maintained
• Auth module well-isolated from other concerns
• JWT implementation abstracted (easy to swap if needed)
• Good use of dependency injection for testability
⚠️ Suggestions:
• Consider event-driven approach for audit logging (scalability)
• Could abstract session storage interface (flexibility)
• May want to add caching layer for user lookups (performance)
• Consider adding rate limiting at architecture level
🚨 Required Fixes:
• None
Architecture Health:
• Coupling: Low ✅
• Cohesion: High ✅
• Complexity: Manageable ✅
• Scalability: Good ✅
• Technical debt: Low ✅
Review Consolidation
Collecting Agent Reviews
Consolidation Strategy:
Step 1: Collect All Reviews
- Wait for all agents to complete
- Gather all review outputs
- Organize by agent
Step 2: Identify Common Themes
- Issues mentioned by multiple agents
- Conflicting suggestions (rare)
- Critical vs nice-to-have
Step 3: Prioritize Findings
- 🚨 Required Fixes (blocking)
- ⚠️ Suggestions (improvements)
- ✅ Strengths (positive feedback)
Step 4: Generate Unified Summary
- Overall assessment
- Critical issues (if any)
- Key improvements suggested
- Ready-to-ship decision
Unified Review Summary Template
📊 Multi-Agent Review Summary
Code Quality (refactorer): ✅ EXCELLENT
Strengths: [Top 3 strengths]
Suggestions: [Top 2-3 suggestions]
Security (security): ✅ SECURE
Strengths: [Top 3 strengths]
Suggestions: [Top 2-3 suggestions]
Testing (qa): ✅ WELL-TESTED
Strengths: [Coverage metrics + top strengths]
Suggestions: [Top 2-3 suggestions]
Documentation (implementer): ✅ COMPLETE
Strengths: [Documentation coverage]
Suggestions: [Top 2-3 suggestions]
Architecture (architect): ✅ SOLID (if included)
Strengths: [Architecture assessment]
Suggestions: [Top 2-3 suggestions]
Overall Assessment: ✅ READY TO SHIP
Critical Issues: [Count] (must be 0 to ship)
Suggestions: [Count] (nice-to-have improvements)
Quality Score: [Excellent/Good/Needs Work]
Recommendation: [Ship / Fix Critical Issues / Consider Suggestions]
Example Consolidated Review
📊 Multi-Agent Review Summary
Code Quality (refactorer): ✅ EXCELLENT
Strengths:
• Clean architecture with excellent separation of concerns
• Consistent code style and naming conventions
• Low complexity (avg 3.2, target <5)
Suggestions:
• Consider extracting UserValidator class
• Simplify nested conditionals in authenticate()
Security (security): ✅ SECURE
Strengths:
• Robust bcrypt password hashing (cost 12)
• Comprehensive JWT validation
• No hardcoded secrets or credentials
Suggestions:
• Add rate limiting to prevent brute force
• Add security event logging
Testing (qa): ✅ WELL-TESTED
Strengths:
• 87% coverage (exceeds 80% target)
• All critical paths fully tested
• Good edge case coverage
Suggestions:
• Add tests for concurrent token refresh
• Consider load testing auth endpoints
Documentation (implementer): ✅ COMPLETE
Strengths:
• All APIs documented with OpenAPI
• Clear docstrings on all functions
• README updated with examples
Suggestions:
• Add architecture diagram
• More code examples for token flow
Overall Assessment: ✅ READY TO SHIP
Critical Issues: 0
Suggestions: 8 nice-to-have improvements
Quality Score: Excellent
Recommendation: SHIP - All quality gates passed. Consider addressing suggestions in future iteration.
Agent Communication Best Practices
Clear Context Handoff
When Chaining Agents:
Good Context Handoff:
Use the security agent to review authentication
→ Output: Security review with 3 suggestions
Use the implementer agent to document security measures
Context: Security review identified token expiry, hashing, validation
Task: Document these security features in API docs
Bad Context Handoff:
Use the security agent to review authentication
Use the implementer agent to add docs
Problem: implementer doesn't know what security found
Explicit Review Boundaries
Define What Each Agent Reviews:
Good Boundary Definition:
Use the refactorer agent to review code quality:
- Focus: Code structure, naming, patterns
- Scope: src/auth/ directory only
- Exclude: Security aspects (security agent will cover)
Bad Boundary Definition:
Use the refactorer agent to review the code
Problem: Unclear scope and focus
Validation After Each Review
Always Validate Agent Output:
Review Validation:
After agent completes:
1. Check review is comprehensive
2. Verify findings are actionable
3. Ensure no critical issues missed
4. Validate suggestions are reasonable
If issues:
- Re-prompt agent with clarifications
- Use different agent for second opinion
- Escalate to user if uncertain
Quality Checkpoint Triggers
Automatic Agent Invocation
Based on Code Metrics:
High Complexity Detected:
If cyclomatic complexity >10:
→ Use the refactorer agent to:
- Analyze complex functions
- Suggest simplifications
- Break into smaller functions
Security Patterns Found:
If authentication/encryption code:
→ Use the security agent to:
- Review security implementation
- Validate secure patterns
- Check for vulnerabilities
Low Test Coverage:
If coverage <80%:
→ Use the qa agent to:
- Identify untested code
- Suggest test cases
- Improve coverage
Missing Documentation:
If docstring coverage <90%:
→ Use the implementer agent to:
- Identify missing docs
- Generate docstrings
- Add examples
Circular Dependencies:
If circular deps detected:
→ Use the architect agent to:
- Analyze dependency structure
- Suggest refactoring
- Break circular references
Multi-Agent Review Best Practices
DO:
✅ Best Practices:
- ALWAYS use workflow-coordinator first
- Use parallel reviews for speed when possible
- Provide clear context to each agent
- Validate each agent's output
- Consolidate findings into unified summary
- Focus agents on their expertise areas
- Skip unnecessary agents for simple changes
- Use sequential review for critical features
DON'T:
❌ Anti-Patterns:
- Skip workflow-coordinator validation
- Use all agents for every review (overkill)
- Let agents review outside their expertise
- Forget to consolidate findings
- Accept reviews without validation
- Chain agents without clear handoff
- Run sequential when parallel would work
- Use parallel when sequential needed
Comprehensive multi-agent review strategies for quality assurance and code validation