520 lines
20 KiB
Markdown
520 lines
20 KiB
Markdown
# Architect Integration Guide
|
|
**BMAD Method: System Architecture Persona**
|
|
|
|
## Introduction
|
|
|
|
This integration guide provides detailed instructions for incorporating the Architect persona into your BMAD Method workflow. It covers integration points, collaboration patterns, handoff procedures, and practical examples to ensure seamless incorporation of architectural expertise throughout your project lifecycle.
|
|
|
|
## Table of Contents
|
|
|
|
1. [Integration Overview](#integration-overview)
|
|
2. [Workflow Integration Points](#workflow-integration-points)
|
|
3. [Collaboration Patterns](#collaboration-patterns)
|
|
4. [Handoff Procedures](#handoff-procedures)
|
|
5. [Input and Output Artifacts](#input-and-output-artifacts)
|
|
6. [Integration Examples](#integration-examples)
|
|
7. [Common Integration Challenges](#common-integration-challenges)
|
|
8. [Integration Checklist](#integration-checklist)
|
|
|
|
## Integration Overview
|
|
|
|
The Architect persona integrates with the BMAD Method at strategic points throughout the project lifecycle, providing technical expertise, architectural guidance, and quality validation. Successful integration requires clear communication channels, well-defined handoff procedures, and collaborative workflows that leverage the Architect's specialized capabilities.
|
|
|
|
### Key Integration Principles
|
|
|
|
1. **Early Involvement**: Engage the Architect persona at the earliest stages of project planning
|
|
2. **Continuous Collaboration**: Maintain ongoing dialogue between the Architect and other personas
|
|
3. **Clear Deliverables**: Define specific architectural artifacts and their acceptance criteria
|
|
4. **Feedback Loops**: Establish mechanisms for architectural validation and refinement
|
|
5. **Knowledge Transfer**: Ensure architectural decisions and rationales are effectively communicated
|
|
|
|
## Workflow Integration Points
|
|
|
|
The Architect persona integrates with the BMAD workflow at specific points:
|
|
|
|
### Project Initiation
|
|
|
|
- **Integration Point**: Initial project scoping and requirement gathering
|
|
- **Architect Activities**:
|
|
- Review business requirements for technical feasibility
|
|
- Identify technical constraints and limitations
|
|
- Provide initial architecture vision
|
|
- Establish technical guardrails
|
|
- **Collaborating Personas**: Product Owner, Project Manager
|
|
- **Artifacts**: Initial architecture vision document, technical constraints list
|
|
|
|
### Planning Phase
|
|
|
|
- **Integration Point**: Feature planning and prioritization
|
|
- **Architect Activities**:
|
|
- Provide technical complexity assessments
|
|
- Identify architectural dependencies
|
|
- Create high-level architecture diagrams
|
|
- Establish technical standards
|
|
- **Collaborating Personas**: Product Owner, Project Manager, UX/UI Architect
|
|
- **Artifacts**: High-level architecture document, technical standards guide
|
|
|
|
### Design Phase
|
|
|
|
- **Integration Point**: Detailed solution design
|
|
- **Architect Activities**:
|
|
- Create detailed architecture documentation
|
|
- Define component boundaries and interfaces
|
|
- Establish data models and flows
|
|
- Document architectural decisions
|
|
- **Collaborating Personas**: UX/UI Architect, Developer, DevOps Engineer
|
|
- **Artifacts**: Detailed architecture documentation, component specifications, data models
|
|
|
|
### Implementation Phase
|
|
|
|
- **Integration Point**: Development and technical review
|
|
- **Architect Activities**:
|
|
- Provide technical guidance to development teams
|
|
- Review implementation for architectural alignment
|
|
- Address complex technical challenges
|
|
- Update architecture documentation as needed
|
|
- **Collaborating Personas**: Developer, DevOps Engineer
|
|
- **Artifacts**: Implementation guidelines, architecture reviews, technical solutions
|
|
|
|
### Validation Phase
|
|
|
|
- **Integration Point**: Quality assurance and testing
|
|
- **Architect Activities**:
|
|
- Validate implementation against architectural standards
|
|
- Assess non-functional requirements compliance
|
|
- Identify architectural improvements
|
|
- Document technical debt
|
|
- **Collaborating Personas**: Developer, DevOps Engineer, QA Engineer
|
|
- **Artifacts**: Architecture validation reports, technical debt documentation
|
|
|
|
### Evolution Phase
|
|
|
|
- **Integration Point**: System enhancement and evolution
|
|
- **Architect Activities**:
|
|
- Evaluate architecture performance and scalability
|
|
- Plan for system evolution
|
|
- Assess new technologies
|
|
- Update architecture to accommodate new requirements
|
|
- **Collaborating Personas**: Product Owner, Project Manager, Developer
|
|
- **Artifacts**: Architecture evolution plans, technology assessments
|
|
|
|
## Collaboration Patterns
|
|
|
|
Effective collaboration between the Architect and other personas is essential for successful integration:
|
|
|
|
### Architect + Product Owner
|
|
|
|
- **Collaboration Focus**: Aligning technical solutions with business requirements
|
|
- **Communication Cadence**: Weekly alignment meetings, ad-hoc consultations
|
|
- **Shared Artifacts**: PRD, architecture vision, technical constraints
|
|
- **Collaboration Tools**: Requirement mapping, technical feasibility assessments
|
|
- **Best Practices**:
|
|
- Translate technical concepts into business terms
|
|
- Document technical constraints and their business impacts
|
|
- Collaborate on feature prioritization based on technical complexity
|
|
- Maintain ongoing dialogue about technical trade-offs
|
|
|
|
### Architect + Project Manager
|
|
|
|
- **Collaboration Focus**: Technical planning and risk management
|
|
- **Communication Cadence**: Sprint planning, bi-weekly status updates
|
|
- **Shared Artifacts**: Project plan, technical risk register, architecture roadmap
|
|
- **Collaboration Tools**: Technical complexity assessments, dependency mapping
|
|
- **Best Practices**:
|
|
- Provide accurate technical complexity estimates
|
|
- Identify technical dependencies and risks early
|
|
- Collaborate on resource allocation for technical tasks
|
|
- Maintain transparency about technical challenges
|
|
|
|
### Architect + UX/UI Architect
|
|
|
|
- **Collaboration Focus**: Aligning technical and design approaches
|
|
- **Communication Cadence**: Design review sessions, technical feasibility checks
|
|
- **Shared Artifacts**: Design specifications, component architecture, technical constraints
|
|
- **Collaboration Tools**: Component mapping, technical feasibility assessments
|
|
- **Best Practices**:
|
|
- Establish clear boundaries between design and technical concerns
|
|
- Collaborate on component architecture and reusability
|
|
- Validate technical feasibility of proposed designs
|
|
- Create shared understanding of implementation constraints
|
|
|
|
### Architect + Developer
|
|
|
|
- **Collaboration Focus**: Technical implementation guidance
|
|
- **Communication Cadence**: Implementation kickoffs, technical reviews, ad-hoc support
|
|
- **Shared Artifacts**: Architecture documentation, implementation guidelines, code reviews
|
|
- **Collaboration Tools**: Architecture walkthroughs, technical mentoring sessions
|
|
- **Best Practices**:
|
|
- Provide clear, actionable implementation guidance
|
|
- Be available for technical consultation
|
|
- Review implementation for architectural alignment
|
|
- Focus on knowledge transfer and capability building
|
|
|
|
### Architect + DevOps Engineer
|
|
|
|
- **Collaboration Focus**: Infrastructure and deployment architecture
|
|
- **Communication Cadence**: Infrastructure planning, deployment reviews
|
|
- **Shared Artifacts**: Infrastructure architecture, deployment plans, operational requirements
|
|
- **Collaboration Tools**: Infrastructure reviews, deployment validation
|
|
- **Best Practices**:
|
|
- Collaborate on infrastructure architecture design
|
|
- Align application and infrastructure architecture
|
|
- Establish clear operational requirements
|
|
- Validate deployment approaches against architecture
|
|
|
|
## Handoff Procedures
|
|
|
|
Clear handoff procedures ensure smooth transitions between the Architect and other personas:
|
|
|
|
### Architecture Vision to Detailed Design
|
|
|
|
- **Handoff Trigger**: Completion of initial architecture vision
|
|
- **Sending Persona**: Architect
|
|
- **Receiving Personas**: UX/UI Architect, Developer
|
|
- **Artifacts**:
|
|
- Architecture vision document
|
|
- Technical constraints list
|
|
- High-level component diagram
|
|
- Initial data model
|
|
- **Handoff Process**:
|
|
1. Architect prepares handoff package with all artifacts
|
|
2. Architecture walkthrough session with receiving personas
|
|
3. Q&A session to clarify technical approach
|
|
4. Receiving personas acknowledge understanding
|
|
5. Establish ongoing consultation process
|
|
- **Validation Criteria**: Receiving personas can articulate technical approach and constraints
|
|
|
|
### Detailed Architecture to Implementation
|
|
|
|
- **Handoff Trigger**: Completion of detailed architecture documentation
|
|
- **Sending Persona**: Architect
|
|
- **Receiving Persona**: Developer
|
|
- **Artifacts**:
|
|
- Detailed architecture documentation
|
|
- Component specifications
|
|
- Interface definitions
|
|
- Data models
|
|
- Implementation guidelines
|
|
- **Handoff Process**:
|
|
1. Architect prepares implementation package
|
|
2. Technical walkthrough with development team
|
|
3. Component-level deep dives as needed
|
|
4. Establish technical review process
|
|
5. Define architecture compliance criteria
|
|
- **Validation Criteria**: Developers can implement components according to architecture
|
|
|
|
### Implementation Review to Architecture Update
|
|
|
|
- **Handoff Trigger**: Significant implementation deviations or challenges
|
|
- **Sending Persona**: Developer
|
|
- **Receiving Persona**: Architect
|
|
- **Artifacts**:
|
|
- Implementation deviation report
|
|
- Technical challenge description
|
|
- Proposed solutions or alternatives
|
|
- **Handoff Process**:
|
|
1. Developer documents deviation or challenge
|
|
2. Technical review with Architect
|
|
3. Collaborative solution development
|
|
4. Architecture update if needed
|
|
5. Implementation guidance refinement
|
|
- **Validation Criteria**: Agreed solution aligns with architectural principles
|
|
|
|
### Architecture Validation to Evolution Planning
|
|
|
|
- **Handoff Trigger**: Completion of implementation phase
|
|
- **Sending Persona**: Architect
|
|
- **Receiving Personas**: Product Owner, Project Manager
|
|
- **Artifacts**:
|
|
- Architecture validation report
|
|
- Technical debt documentation
|
|
- Performance assessment
|
|
- Evolution recommendations
|
|
- **Handoff Process**:
|
|
1. Architect prepares validation and evolution package
|
|
2. Review session with receiving personas
|
|
3. Prioritization of technical improvements
|
|
4. Integration into product roadmap
|
|
5. Evolution planning
|
|
- **Validation Criteria**: Technical improvements incorporated into product roadmap
|
|
|
|
## Input and Output Artifacts
|
|
|
|
The Architect persona works with specific artifacts throughout the integration process:
|
|
|
|
### Input Artifacts
|
|
|
|
- **Business Requirements Document**
|
|
- Source: Product Owner
|
|
- Usage: Basis for technical solution design
|
|
- Integration Point: Project Initiation
|
|
|
|
- **Product Requirement Document (PRD)**
|
|
- Source: Product Owner
|
|
- Usage: Detailed requirements for architecture design
|
|
- Integration Point: Planning Phase
|
|
|
|
- **UX/UI Specifications**
|
|
- Source: UX/UI Architect
|
|
- Usage: Frontend architecture alignment
|
|
- Integration Point: Design Phase
|
|
|
|
- **Existing System Documentation**
|
|
- Source: Various
|
|
- Usage: Integration planning and compatibility assessment
|
|
- Integration Point: Planning Phase
|
|
|
|
- **Non-functional Requirements**
|
|
- Source: Product Owner, Stakeholders
|
|
- Usage: Architecture quality attributes definition
|
|
- Integration Point: Planning Phase
|
|
|
|
### Output Artifacts
|
|
|
|
- **Architecture Vision Document**
|
|
- Audience: All personas
|
|
- Content: High-level architecture approach, key decisions, constraints
|
|
- Integration Point: Project Initiation
|
|
|
|
- **Technical Standards Guide**
|
|
- Audience: Developers, DevOps Engineers
|
|
- Content: Coding standards, patterns, practices, technology selections
|
|
- Integration Point: Planning Phase
|
|
|
|
- **Detailed Architecture Documentation**
|
|
- Audience: Developers, DevOps Engineers
|
|
- Content: Component specifications, interfaces, data models, flows
|
|
- Integration Point: Design Phase
|
|
|
|
- **Architecture Decision Records**
|
|
- Audience: All technical personas
|
|
- Content: Key decisions, alternatives considered, rationales
|
|
- Integration Point: Throughout project lifecycle
|
|
|
|
- **Implementation Guidelines**
|
|
- Audience: Developers
|
|
- Content: Technical guidance for implementation
|
|
- Integration Point: Implementation Phase
|
|
|
|
- **Architecture Validation Reports**
|
|
- Audience: Product Owner, Project Manager
|
|
- Content: Compliance assessment, technical debt, improvements
|
|
- Integration Point: Validation Phase
|
|
|
|
- **Architecture Evolution Plan**
|
|
- Audience: Product Owner, Project Manager
|
|
- Content: Technical roadmap, improvement opportunities
|
|
- Integration Point: Evolution Phase
|
|
|
|
## Integration Examples
|
|
|
|
### Methodology Integration
|
|
|
|
### Loading Architect Persona
|
|
- Copy `bmad-agent/personas/architect.md` content into AI assistant context
|
|
- Reference architecture task library for specific workflows
|
|
- Use architecture templates as guidance frameworks
|
|
- Apply quality checklists for validation
|
|
|
|
### Prompt Structuring Examples
|
|
```
|
|
"Acting as Fred the System Architect from BMAD Method, help me design the architecture for [system].
|
|
Use the system architecture template and follow the architecture quality standards."
|
|
```
|
|
|
|
### Example 1: E-commerce Platform Architecture
|
|
|
|
**Context**: New e-commerce platform development
|
|
|
|
**Integration Flow**:
|
|
|
|
1. **Project Initiation**
|
|
- Product Owner provides business requirements for online store
|
|
- Architect reviews requirements and creates initial architecture vision
|
|
- Early identification of microservices approach for scalability
|
|
|
|
2. **Planning Phase**
|
|
- Architect creates high-level architecture with service boundaries
|
|
- Technical complexity assessment reveals payment processing as high-risk area
|
|
- Project Manager adjusts timeline based on technical complexity
|
|
|
|
3. **Design Phase**
|
|
- Detailed architecture documentation for each microservice
|
|
- UX/UI Architect and System Architect collaborate on frontend architecture
|
|
- Component interfaces and data models defined
|
|
|
|
4. **Implementation Phase**
|
|
- Regular architecture reviews during development
|
|
- Technical guidance for complex payment integration
|
|
- Architecture updates based on implementation learnings
|
|
|
|
5. **Validation Phase**
|
|
- Performance testing reveals scaling issues in inventory service
|
|
- Architect provides optimization recommendations
|
|
- Technical debt documented for future sprints
|
|
|
|
6. **Evolution Phase**
|
|
- Architecture evolution plan for international expansion
|
|
- Assessment of new technologies for recommendation engine
|
|
- Technical roadmap aligned with product roadmap
|
|
|
|
**Key Integration Artifacts**:
|
|
- E-commerce Architecture Vision
|
|
- Microservice Boundaries Document
|
|
- Service Interface Specifications
|
|
- Data Model Documentation
|
|
- Performance Optimization Plan
|
|
|
|
### Example 2: Legacy System Modernization
|
|
|
|
**Context**: Modernization of legacy inventory management system
|
|
|
|
**Integration Flow**:
|
|
|
|
1. **Project Initiation**
|
|
- Architect assesses existing system architecture
|
|
- Technical constraints identified due to legacy integrations
|
|
- Modernization approach defined with Product Owner
|
|
|
|
2. **Planning Phase**
|
|
- Phased modernization architecture created
|
|
- Technical risk assessment for data migration
|
|
- Project Manager creates phased implementation plan
|
|
|
|
3. **Design Phase**
|
|
- Detailed architecture for new system components
|
|
- Interface designs for legacy system integration
|
|
- Data migration strategy and models
|
|
|
|
4. **Implementation Phase**
|
|
- Technical guidance for legacy integration
|
|
- Architecture reviews for new components
|
|
- Adaptation for unexpected legacy system constraints
|
|
|
|
5. **Validation Phase**
|
|
- Integration testing reveals performance bottlenecks
|
|
- Architecture adjustments for performance optimization
|
|
- Technical debt documentation for phase 2
|
|
|
|
6. **Evolution Phase**
|
|
- Architecture roadmap for complete legacy replacement
|
|
- Technology recommendations for future phases
|
|
- Technical strategy aligned with business modernization goals
|
|
|
|
**Key Integration Artifacts**:
|
|
- Legacy System Assessment
|
|
- Modernization Architecture Vision
|
|
- Integration Interface Specifications
|
|
- Data Migration Strategy
|
|
- Technical Evolution Roadmap
|
|
|
|
## Common Integration Challenges
|
|
|
|
### Challenge 1: Business-Technical Alignment
|
|
|
|
- **Symptoms**: Architectural solutions don't address business needs, frequent requirement changes
|
|
- **Root Causes**: Insufficient collaboration between Architect and Product Owner, unclear business requirements
|
|
- **Resolution Strategies**:
|
|
- Establish regular alignment sessions
|
|
- Create shared understanding of business goals
|
|
- Document business drivers for architectural decisions
|
|
- Validate architecture against business requirements
|
|
|
|
### Challenge 2: Design-Architecture Misalignment
|
|
|
|
- **Symptoms**: UX/UI designs that are technically challenging to implement, frequent design revisions
|
|
- **Root Causes**: Late involvement of Architect in design process, insufficient collaboration
|
|
- **Resolution Strategies**:
|
|
- Involve Architect early in design process
|
|
- Establish technical feasibility reviews
|
|
- Create shared component library
|
|
- Document technical constraints for design team
|
|
|
|
### Challenge 3: Architecture Compliance
|
|
|
|
- **Symptoms**: Implementation deviates from architecture, inconsistent technical approaches
|
|
- **Root Causes**: Insufficient architecture communication, lack of compliance validation
|
|
- **Resolution Strategies**:
|
|
- Create clear, accessible architecture documentation
|
|
- Establish regular architecture reviews
|
|
- Provide implementation examples
|
|
- Create architecture compliance checklist
|
|
|
|
### Challenge 4: Technical Debt Management
|
|
|
|
- **Symptoms**: Accumulating technical debt, decreasing development velocity
|
|
- **Root Causes**: Pressure to deliver features, insufficient technical debt tracking
|
|
- **Resolution Strategies**:
|
|
- Establish technical debt tracking process
|
|
- Include technical debt in product backlog
|
|
- Create technical debt reduction plan
|
|
- Educate stakeholders on technical debt impacts
|
|
|
|
### Challenge 5: Knowledge Transfer
|
|
|
|
- **Symptoms**: Development team struggles to implement architecture, frequent technical questions
|
|
- **Root Causes**: Complex architecture documentation, insufficient knowledge sharing
|
|
- **Resolution Strategies**:
|
|
- Create multiple views of architecture documentation
|
|
- Conduct architecture walkthrough sessions
|
|
- Provide implementation examples
|
|
- Establish mentoring relationships
|
|
|
|
## Integration Checklist
|
|
|
|
Use this checklist to ensure successful integration of the Architect persona:
|
|
|
|
### Project Initiation Integration
|
|
|
|
- [ ] Architect involved in initial project scoping
|
|
- [ ] Business requirements reviewed for technical feasibility
|
|
- [ ] Initial architecture vision created
|
|
- [ ] Technical constraints and limitations documented
|
|
- [ ] Architecture vision shared with all stakeholders
|
|
|
|
### Planning Phase Integration
|
|
|
|
- [ ] Architect involved in feature planning
|
|
- [ ] Technical complexity assessments provided
|
|
- [ ] High-level architecture diagrams created
|
|
- [ ] Technical standards established
|
|
- [ ] Architecture approach aligned with business goals
|
|
|
|
### Design Phase Integration
|
|
|
|
- [ ] Detailed architecture documentation created
|
|
- [ ] Component boundaries and interfaces defined
|
|
- [ ] Data models and flows established
|
|
- [ ] Architectural decisions documented
|
|
- [ ] Architecture reviewed with implementation teams
|
|
|
|
### Implementation Phase Integration
|
|
|
|
- [ ] Regular architecture guidance provided
|
|
- [ ] Implementation reviewed for architectural alignment
|
|
- [ ] Technical challenges addressed collaboratively
|
|
- [ ] Architecture documentation updated as needed
|
|
- [ ] Knowledge transfer sessions conducted
|
|
|
|
### Validation Phase Integration
|
|
|
|
- [ ] Implementation validated against architecture
|
|
- [ ] Non-functional requirements compliance assessed
|
|
- [ ] Technical debt documented
|
|
- [ ] Architecture improvements identified
|
|
- [ ] Validation results shared with stakeholders
|
|
|
|
### Evolution Phase Integration
|
|
|
|
- [ ] Architecture performance and scalability evaluated
|
|
- [ ] System evolution plan created
|
|
- [ ] New technologies assessed
|
|
- [ ] Architecture updated for new requirements
|
|
- [ ] Technical roadmap aligned with product roadmap
|
|
|
|
## Conclusion
|
|
|
|
Successful integration of the Architect persona into the BMAD Method workflow requires intentional collaboration, clear communication, and well-defined processes. By following the guidelines in this integration guide, teams can effectively leverage architectural expertise throughout the project lifecycle, resulting in technically sound solutions that meet business requirements.
|
|
|
|
For more detailed information about the Architect persona, refer to the [Architect Comprehensive Guide](architect-comprehensive-guide.md) and [Architect Quickstart](architect-quickstart.md) documents.
|