mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-29 16:14:59 +00:00
245 lines
7.8 KiB
Markdown
245 lines
7.8 KiB
Markdown
|
# Architecture Document Validation Checklist
|
||
|
|
|
||
|
|
**Purpose**: Validate the architecture document itself is complete, implementable, and provides clear guidance for AI agents.
|
||
|
|
|
||
|
|
**Note**: This checklist validates the ARCHITECTURE DOCUMENT only. For cross-workflow validation (PRD → Architecture → Stories alignment), use the solutioning-gate-check workflow.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 1. Decision Completeness
|
||
|
|
|
||
|
|
### All Decisions Made
|
||
|
|
|
||
|
|
- [ ] Every critical decision category has been resolved
|
||
|
|
- [ ] All important decision categories addressed
|
||
|
|
- [ ] No placeholder text like "TBD", "[choose]", or "{TODO}" remains
|
||
|
|
- [ ] Optional decisions either resolved or explicitly deferred with rationale
|
||
|
|
|
||
|
|
### Decision Coverage
|
||
|
|
|
||
|
|
- [ ] Data persistence approach decided
|
||
|
|
- [ ] API pattern chosen
|
||
|
|
- [ ] Authentication/authorization strategy defined
|
||
|
|
- [ ] Deployment target selected
|
||
|
|
- [ ] All functional requirements have architectural support
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 2. Version Specificity
|
||
|
|
|
||
|
|
### Technology Versions
|
||
|
|
|
||
|
|
- [ ] Every technology choice includes a specific version number
|
||
|
|
- [ ] Version numbers are current (verified via WebSearch, not hardcoded)
|
||
|
|
- [ ] Compatible versions selected (e.g., Node.js version supports chosen packages)
|
||
|
|
- [ ] Verification dates noted for version checks
|
||
|
|
|
||
|
|
### Version Verification Process
|
||
|
|
|
||
|
|
- [ ] WebSearch used during workflow to verify current versions
|
||
|
|
- [ ] No hardcoded versions from decision catalog trusted without verification
|
||
|
|
- [ ] LTS vs. latest versions considered and documented
|
||
|
|
- [ ] Breaking changes between versions noted if relevant
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 3. Starter Template Integration (if applicable)
|
||
|
|
|
||
|
|
### Template Selection
|
||
|
|
|
||
|
|
- [ ] Starter template chosen (or "from scratch" decision documented)
|
||
|
|
- [ ] Project initialization command documented with exact flags
|
||
|
|
- [ ] Starter template version is current and specified
|
||
|
|
- [ ] Command search term provided for verification
|
||
|
|
|
||
|
|
### Starter-Provided Decisions
|
||
|
|
|
||
|
|
- [ ] Decisions provided by starter marked as "PROVIDED BY STARTER"
|
||
|
|
- [ ] List of what starter provides is complete
|
||
|
|
- [ ] Remaining decisions (not covered by starter) clearly identified
|
||
|
|
- [ ] No duplicate decisions that starter already makes
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 4. Novel Pattern Design (if applicable)
|
||
|
|
|
||
|
|
### Pattern Detection
|
||
|
|
|
||
|
|
- [ ] All unique/novel concepts from PRD identified
|
||
|
|
- [ ] Patterns that don't have standard solutions documented
|
||
|
|
- [ ] Multi-epic workflows requiring custom design captured
|
||
|
|
|
||
|
|
### Pattern Documentation Quality
|
||
|
|
|
||
|
|
- [ ] Pattern name and purpose clearly defined
|
||
|
|
- [ ] Component interactions specified
|
||
|
|
- [ ] Data flow documented (with sequence diagrams if complex)
|
||
|
|
- [ ] Implementation guide provided for agents
|
||
|
|
- [ ] Edge cases and failure modes considered
|
||
|
|
- [ ] States and transitions clearly defined
|
||
|
|
|
||
|
|
### Pattern Implementability
|
||
|
|
|
||
|
|
- [ ] Pattern is implementable by AI agents with provided guidance
|
||
|
|
- [ ] No ambiguous decisions that could be interpreted differently
|
||
|
|
- [ ] Clear boundaries between components
|
||
|
|
- [ ] Explicit integration points with standard patterns
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 5. Implementation Patterns
|
||
|
|
|
||
|
|
### Pattern Categories Coverage
|
||
|
|
|
||
|
|
- [ ] **Naming Patterns**: API routes, database tables, components, files
|
||
|
|
- [ ] **Structure Patterns**: Test organization, component organization, shared utilities
|
||
|
|
- [ ] **Format Patterns**: API responses, error formats, date handling
|
||
|
|
- [ ] **Communication Patterns**: Events, state updates, inter-component messaging
|
||
|
|
- [ ] **Lifecycle Patterns**: Loading states, error recovery, retry logic
|
||
|
|
- [ ] **Location Patterns**: URL structure, asset organization, config placement
|
||
|
|
- [ ] **Consistency Patterns**: UI date formats, logging, user-facing errors
|
||
|
|
|
||
|
|
### Pattern Quality
|
||
|
|
|
||
|
|
- [ ] Each pattern has concrete examples
|
||
|
|
- [ ] Conventions are unambiguous (agents can't interpret differently)
|
||
|
|
- [ ] Patterns cover all technologies in the stack
|
||
|
|
- [ ] No gaps where agents would have to guess
|
||
|
|
- [ ] Implementation patterns don't conflict with each other
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 6. Technology Compatibility
|
||
|
|
|
||
|
|
### Stack Coherence
|
||
|
|
|
||
|
|
- [ ] Database choice compatible with ORM choice
|
||
|
|
- [ ] Frontend framework compatible with deployment target
|
||
|
|
- [ ] Authentication solution works with chosen frontend/backend
|
||
|
|
- [ ] All API patterns consistent (not mixing REST and GraphQL for same data)
|
||
|
|
- [ ] Starter template compatible with additional choices
|
||
|
|
|
||
|
|
### Integration Compatibility
|
||
|
|
|
||
|
|
- [ ] Third-party services compatible with chosen stack
|
||
|
|
- [ ] Real-time solutions (if any) work with deployment target
|
||
|
|
- [ ] File storage solution integrates with framework
|
||
|
|
- [ ] Background job system compatible with infrastructure
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 7. Document Structure
|
||
|
|
|
||
|
|
### Required Sections Present
|
||
|
|
|
||
|
|
- [ ] Executive summary exists (2-3 sentences maximum)
|
||
|
|
- [ ] Project initialization section (if using starter template)
|
||
|
|
- [ ] Decision summary table with ALL required columns:
|
||
|
|
- Category
|
||
|
|
- Decision
|
||
|
|
- Version
|
||
|
|
- Rationale
|
||
|
|
- [ ] Project structure section shows complete source tree
|
||
|
|
- [ ] Implementation patterns section comprehensive
|
||
|
|
- [ ] Novel patterns section (if applicable)
|
||
|
|
|
||
|
|
### Document Quality
|
||
|
|
|
||
|
|
- [ ] Source tree reflects actual technology decisions (not generic)
|
||
|
|
- [ ] Technical language used consistently
|
||
|
|
- [ ] Tables used instead of prose where appropriate
|
||
|
|
- [ ] No unnecessary explanations or justifications
|
||
|
|
- [ ] Focused on WHAT and HOW, not WHY (rationale is brief)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 8. AI Agent Clarity
|
||
|
|
|
||
|
|
### Clear Guidance for Agents
|
||
|
|
|
||
|
|
- [ ] No ambiguous decisions that agents could interpret differently
|
||
|
|
- [ ] Clear boundaries between components/modules
|
||
|
|
- [ ] Explicit file organization patterns
|
||
|
|
- [ ] Defined patterns for common operations (CRUD, auth checks, etc.)
|
||
|
|
- [ ] Novel patterns have clear implementation guidance
|
||
|
|
- [ ] Document provides clear constraints for agents
|
||
|
|
- [ ] No conflicting guidance present
|
||
|
|
|
||
|
|
### Implementation Readiness
|
||
|
|
|
||
|
|
- [ ] Sufficient detail for agents to implement without guessing
|
||
|
|
- [ ] File paths and naming conventions explicit
|
||
|
|
- [ ] Integration points clearly defined
|
||
|
|
- [ ] Error handling patterns specified
|
||
|
|
- [ ] Testing patterns documented
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 9. Practical Considerations
|
||
|
|
|
||
|
|
### Technology Viability
|
||
|
|
|
||
|
|
- [ ] Chosen stack has good documentation and community support
|
||
|
|
- [ ] Development environment can be set up with specified versions
|
||
|
|
- [ ] No experimental or alpha technologies for critical path
|
||
|
|
- [ ] Deployment target supports all chosen technologies
|
||
|
|
- [ ] Starter template (if used) is stable and well-maintained
|
||
|
|
|
||
|
|
### Scalability
|
||
|
|
|
||
|
|
- [ ] Architecture can handle expected user load
|
||
|
|
- [ ] Data model supports expected growth
|
||
|
|
- [ ] Caching strategy defined if performance is critical
|
||
|
|
- [ ] Background job processing defined if async work needed
|
||
|
|
- [ ] Novel patterns scalable for production use
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 10. Common Issues to Check
|
||
|
|
|
||
|
|
### Beginner Protection
|
||
|
|
|
||
|
|
- [ ] Not overengineered for actual requirements
|
||
|
|
- [ ] Standard patterns used where possible (starter templates leveraged)
|
||
|
|
- [ ] Complex technologies justified by specific needs
|
||
|
|
- [ ] Maintenance complexity appropriate for team size
|
||
|
|
|
||
|
|
### Expert Validation
|
||
|
|
|
||
|
|
- [ ] No obvious anti-patterns present
|
||
|
|
- [ ] Performance bottlenecks addressed
|
||
|
|
- [ ] Security best practices followed
|
||
|
|
- [ ] Future migration paths not blocked
|
||
|
|
- [ ] Novel patterns follow architectural principles
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Validation Summary
|
||
|
|
|
||
|
|
### Document Quality Score
|
||
|
|
|
||
|
|
- Architecture Completeness: [Complete / Mostly Complete / Partial / Incomplete]
|
||
|
|
- Version Specificity: [All Verified / Most Verified / Some Missing / Many Missing]
|
||
|
|
- Pattern Clarity: [Crystal Clear / Clear / Somewhat Ambiguous / Ambiguous]
|
||
|
|
- AI Agent Readiness: [Ready / Mostly Ready / Needs Work / Not Ready]
|
||
|
|
|
||
|
|
### Critical Issues Found
|
||
|
|
|
||
|
|
- [ ] Issue 1: **\*\***\_\_\_**\*\***
|
||
|
|
- [ ] Issue 2: **\*\***\_\_\_**\*\***
|
||
|
|
- [ ] Issue 3: **\*\***\_\_\_**\*\***
|
||
|
|
|
||
|
|
### Recommended Actions Before Implementation
|
||
|
|
|
||
|
|
1. ***
|
||
|
|
2. ***
|
||
|
|
3. ***
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
**Next Step**: Run the **solutioning-gate-check** workflow to validate alignment between PRD, Architecture, and Stories before beginning implementation.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
_This checklist validates architecture document quality only. Use solutioning-gate-check for comprehensive readiness validation._
|