checklist.md 8.0 KB
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 implementation-readiness 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
AI Tooling (MCP Servers)
- Available MCPs for chosen engine identified and presented to user
- User preference recorded (accepted or declined)
- If accepted: MCP capabilities and setup instructions included in Development Environment
- If declined: Note that MCPs can be added later
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
{ list issues }
Recommended Actions Before Implementation
{ list actions }
Next Step: Run the implementation-readiness workflow to validate alignment between PRD, Architecture, and Stories before beginning implementation.
This checklist validates architecture document quality only. Use implementation-readiness for comprehensive readiness validation.