| name | arc42-architecture-design |
| description | Decompose high-level design documentation into detailed Arc42 architecture documentation. Use when the user asks to create architecture documentation, generate Arc42 documents, analyze a codebase for architecture patterns, or convert existing design docs to Arc42 format. This skill analyzes repositories, identifies architectural components, validates context and assumptions through user questions, and produces comprehensive Arc42-compliant documentation. |
Arc42 Architecture Design Generator
Transform high-level design documentation into comprehensive Arc42 architecture documentation through systematic analysis, validation, and generation.
Overview
Arc42 is a pragmatic, structured template for documenting software architectures with 12 sections covering everything from goals to glossary. This skill guides the process of:
- Analyzing existing repositories and documentation
- Extracting architectural patterns and components
- Validating assumptions through structured user questions
- Generating complete Arc42-compliant documentation
Documentation Structure Best Practices
Progressive Disclosure for AI Agents
Arc42 documentation should be structured for progressive disclosure—enabling AI agents to load only the context they need:
docs/architecture/arc42/
├── README.md # Index (~200 tokens) - Load first
├── 01-introduction-goals.md # Section 1 (~500-1000 tokens)
├── 02-constraints.md # Section 2 (~300-500 tokens)
├── 03-context-scope.md # Section 3 (~500-800 tokens)
├── 04-solution-strategy.md # Section 4 (~600-1000 tokens)
├── 05-building-blocks.md # Section 5 (~800-1500 tokens)
├── 06-runtime-view.md # Section 6 (~600-1000 tokens)
├── 07-deployment-view.md # Section 7 (~500-800 tokens)
├── 08-crosscutting-concepts.md # Section 8 (~600-1000 tokens)
├── 09-architecture-decisions.md # Section 9 (~300 tokens, links to ADRs)
├── 10-quality-requirements.md # Section 10 (~500-800 tokens)
├── 11-risks-technical-debt.md # Section 11 (~400-600 tokens)
└── 12-glossary.md # Section 12 (~300-500 tokens)
Key Principles for AI-Friendly Documentation
- Lightweight Index: README.md provides navigation with 1-2 sentence summaries per section
- Self-Contained Sections: Each document is complete without requiring other sections
- Token Budget: Keep individual documents under 1500 tokens where possible
- Cross-References: Use relative links
[Section 5](05-building-blocks.md) for navigation
- Frontmatter Metadata: Include section number, title, and last-updated date
- Diagrams First: Lead with visual representations; details follow
Document Template
Each section document should follow this structure:
# Section N: Title
> One-sentence summary for index extraction.
**Last Updated**: YYYY-MM-DD
**Related Sections**: [Link1](file.md), [Link2](file.md)
---
[Content organized for quick comprehension]
Arc42 Sections Summary
| Section | Purpose | Key Content |
|---|
| 1. Introduction & Goals | Business context | Requirements overview, quality goals (top 3-5), stakeholders |
| 2. Constraints | Boundaries | Technical, organizational, and convention constraints |
| 3. Context & Scope | System boundaries | Business context diagram, technical context diagram |
| 4. Solution Strategy | Core decisions | Technology choices, architecture patterns, key approaches |
| 5. Building Block View | Static structure | Hierarchical whitebox/blackbox decomposition (Level 1, 2, 3+) |
| 6. Runtime View | Dynamic behavior | Key scenarios, interaction sequences, workflows |
| 7. Deployment View | Infrastructure | Hardware, environments, deployment mapping |
| 8. Crosscutting Concepts | Shared patterns | Security, logging, error handling, domain models |
| 9. Architecture Decisions | ADRs | Important decisions with rationale (use ADR format) |
| 10. Quality Requirements | Quality tree | Quality scenarios, quality tree structure |
| 11. Risks & Technical Debt | Known issues | Prioritized risks, technical debt items |
| 12. Glossary | Terminology | Domain and technical terms with definitions |
Workflow
Execute these phases in order:
Phase 1: Repository Analysis
Analyze the codebase to understand the existing architecture:
1. Examine project structure
- Directory layout and organization patterns
- Configuration files (package.json, pom.xml, Dockerfile, etc.)
- Entry points and main modules
2. Identify key documentation
- README files, ARCHITECTURE.md, design docs
- API specifications (OpenAPI, GraphQL schemas)
- Database schemas and migrations
3. Map technical stack
- Languages, frameworks, libraries
- External services and integrations
- Infrastructure as code (Terraform, CloudFormation)
4. Trace component relationships
- Import/dependency graphs
- Service communication patterns
- Data flow paths
Phase 2: Context Validation
CRITICAL: Validate ALL assumptions with user before proceeding.
Use the structured question approach in references/validation-questions.md to gather:
- Business context and goals
- Stakeholder expectations
- Quality priorities
- Constraint clarifications
- Missing architectural context
Ask questions in batches of 3-5 to avoid overwhelming the user. Start with highest-priority gaps.
Phase 3: Architecture Extraction
Extract architectural elements from analyzed sources:
Building Blocks (Section 5)
- Level 1: Top-level system decomposition
- Level 2: Component internals for critical blocks
- Level 3: Only for complex/risky components
Runtime Scenarios (Section 6)
- Primary use cases (happy path)
- Error handling flows
- Integration touchpoints
Deployment (Section 7)
- Production environment topology
- Development/staging differences if significant
Phase 4: Documentation Generation
Generate Arc42 documentation following references/arc42-template.md.
Output Structure (Default - Progressive Disclosure):
docs/architecture/arc42/
├── README.md # Lightweight index with navigation
├── 01-introduction-goals.md # Requirements, quality goals, stakeholders
├── 02-constraints.md # Technical, organizational, conventions
├── 03-context-scope.md # Business and technical context diagrams
├── 04-solution-strategy.md # Technology choices, patterns
├── 05-building-blocks.md # System decomposition (Level 1, 2)
├── 06-runtime-view.md # Key scenarios and workflows
├── 07-deployment-view.md # Infrastructure and installation
├── 08-crosscutting-concepts.md # Security, logging, error handling
├── 09-architecture-decisions.md # Links to ADRs with summaries
├── 10-quality-requirements.md # Quality tree and scenarios
├── 11-risks-technical-debt.md # Known risks and debt items
└── 12-glossary.md # Domain and technical terms
Document Guidelines:
- README.md: <200 tokens, summaries only, navigation links
- Individual sections: 500-1500 tokens each
- Self-contained: Each section readable without others
- Diagrams first: Lead with visuals, follow with details
Quality Checks:
- Verify all 12 sections addressed (sections may be marked "not applicable" with justification)
- Ensure diagrams are described or created
- Cross-reference between sections using relative links
- Validate consistency of terminology with glossary
- Check token budget compliance for each document
Key Principles
Document What Matters
Arc42 is flexible—not every section needs exhaustive content. Focus on:
- Sections most relevant to stakeholders
- Areas with highest risk or complexity
- Information not obvious from code
Quality Goals Drive Architecture
The top 3-5 quality goals (Section 1.2) should influence:
- Solution strategy choices (Section 4)
- Crosscutting concepts (Section 8)
- Architecture decisions (Section 9)
- Quality scenarios (Section 10)
Building Block Hierarchy
Level 0: Context (System as blackbox)
↓
Level 1: Whitebox of entire system (major components as blackboxes)
↓
Level 2: Whitebox of selected Level-1 components
↓
Level 3+: Only for complex/risky areas
Blackbox vs Whitebox
- Blackbox: Responsibility + interfaces (what it does)
- Whitebox: Internal structure + contained blackboxes (how it's built)
Diagram Conventions
When describing diagrams, use clear textual notation:
Context Diagram:
[External System A] --> [Our System] --> [External System B]
| |
v v
[Database] [Message Queue]
Building Block Diagram:
+------------------+
| Our System |
| +------------+ |
| | Component A|--|---> [External API]
| +------------+ |
| | |
| v |
| +------------+ |
| | Component B| |
| +------------+ |
+------------------+
Use Mermaid, PlantUML, or ASCII art based on user preference.
References
