Architecture Planning Skill Skill

Architecture Planning Skill

Purpose

Produce consistent, thorough architecture documentation for system design.

When to Use

Planning significant feature implementations
Making technology or pattern decisions
Designing new modules or services
Before major refactoring efforts
System integration planning

Templates

Main Templates

templates/architecture-doc.md - Full architecture document
templates/decision-record.md - ADR (Architecture Decision Record) format
templates/risk-assessment.md - Risk matrix template

Pattern Library

Reference established architectural patterns:

patterns/microservices.md - Microservices architecture
patterns/monolith.md - Monolithic architecture
patterns/serverless.md - Serverless architecture

Decision Framework

When to Create an ADR

Create a formal Architecture Decision Record when:

Choosing between technologies (database, framework, library)
Selecting architectural patterns (monolith vs microservice)
Defining integration approaches (sync vs async)
Making security model changes
Decisions that are hard to reverse

ADR Format (Lightweight)

# ADR-[N]: [Title]
**Status:** Proposed | Accepted | Deprecated | Superseded
**Date:** [YYYY-MM-DD]

## Context
[Why is this decision needed? What's the situation?]

## Decision
[What was decided?]

## Consequences
[What follows from this decision?]

Risk Assessment Matrix

Use this matrix to categorize risks:

| Probability ↓ / Impact → | Low | Medium | High | |---------------------------|-----|--------|------| | High | Medium | High | Critical | | Medium | Low | Medium | High | | Low | Low | Low | Medium |

Risk Categories

Technical: Technology limitations, complexity, performance
Timeline: Schedule impacts, dependencies
Integration: External system dependencies, API changes
Security: Vulnerabilities, compliance requirements
Operational: Deployment, monitoring, maintenance

Architecture Document Sections

Required Sections

Overview - High-level description
Design Decisions - Key choices with rationale
Component Design - Responsibilities and interfaces
Risk Assessment - Identified risks and mitigations

Optional Sections (as needed)

Data Flow diagrams
Integration Points
Security Considerations
Performance Requirements
Migration Strategy

Quality Checklist

Before finalizing an architecture document:

[ ] All major decisions documented with options considered
[ ] Rationale provided for each decision
[ ] Trade-offs explicitly stated
[ ] Risks identified with mitigation strategies
[ ] Aligns with existing codebase patterns (from research)
[ ] Integration points clearly defined
[ ] Component responsibilities are clear and non-overlapping
[ ] Security implications considered
[ ] Performance requirements addressed

Output Location

Save architecture documents to: docs/plans/architecture-{session}.md Save ADRs to: docs/plans/adr-{number}-{title}.md

Integration with Workflow

Research phase provides codebase context and patterns
Questioning phase provides validated requirements
Architecture planning creates design documents (this skill)
Task breakdown converts architecture to executable tasks
Implementation follows the approved plan

Agent Skills: Architecture Planning Skill

Install this agent skill to your local

Skill Files