| name | architecture |
| description | Design software system architecture using requirements, constraints, data models, APIs, integrations, dependencies, and technical tradeoff analysis. Use when deciding how a system or feature will fundamentally work. |
Purpose
This skill helps define the technical structure of a software product or
feature before implementation decisions become expensive to reverse.
Use this skill when:
- Designing system components
- Modeling data
- Planning APIs
- Selecting dependencies
- Defining integration boundaries
- Evaluating technical tradeoffs
- Reducing implementation risk
Inputs
Expected inputs:
- Scoped requirements
- Non-goals
- Success criteria
- Functional requirements
- Non-functional requirements
- Constraints
- Existing system context
- Feasibility findings
Inputs usually come from scoping, goal-setting, and validation. If the
requirements are not clear enough to design against, use scoping first.
Architecture Principles
Always optimize for:
- Clear ownership boundaries
- Simple data flow
- Explicit tradeoffs
- Compatibility with existing systems
- Reversibility where uncertainty is high
Avoid optimizing solely for:
- Novel technology
- Premature abstraction
- Over-generalization
- Local elegance at system cost
- Ignoring operational constraints
Process
Step 1: Clarify Requirements
Determine:
- User-facing behavior
- Data requirements
- Integration points
- Performance expectations
- Security or compliance constraints
- Operational needs
Flag requirements that are ambiguous or contradictory.
Step 2: Define System Boundaries
Identify:
- Components
- Services
- Data stores
- APIs
- External systems
- Ownership boundaries
Make explicit what each component owns and does not own.
Step 3: Model Data and Interfaces
Specify:
- Core entities
- Relationships
- State transitions
- API contracts
- Event flows
- Migration needs
Use structured models or schemas when available.
Step 4: Evaluate Tradeoffs
Assess options across:
| Factor | Questions |
|---|
| Simplicity | Can the team understand and operate it? |
| Scalability | Does it meet expected load and growth? |
| Reliability | What fails and how is it recovered? |
| Security | What data or access risks exist? |
| Reversibility | How hard is this to change later? |
Choose the simplest design that satisfies the real constraints.
Step 5: Produce Architecture Decision
Generate:
- Recommended design
- Component responsibilities
- Data model or interface outline
- Key tradeoffs
- Risks
- Follow-up decisions
Anti-Patterns
Avoid:
- Designing before scope is stable enough
- Choosing dependencies without clear need
- Ignoring migration and rollout
- Treating diagrams as decisions
- Hiding unresolved tradeoffs
- Overbuilding for hypothetical scale
Reviewer Checklist
Before finalizing architecture:
- Are boundaries clear?
- Are data ownership and APIs defined?
- Are operational risks visible?
- Are major tradeoffs documented?
- Can
decomposition use the design to create tasks?
Escalation Guidance
Escalate when:
- Requirements conflict
- Security or compliance impact is unclear
- Build versus buy decisions are material
- Existing system constraints block the design
- The design requires cross-team ownership changes
Example
Input:
- Scoped onboarding checklist
- Existing account setup service
- Requirement: Persist progress per workspace
Expected architecture:
- Store checklist progress on workspace setup state
- Expose read/update endpoints for checklist items
- Emit completion event for analytics and support reporting
Recommended next skill:
- Use
decomposition to convert the design into implementation tasks.
