This skill should be used when the user asks to "create arc42 documentation", "document architecture", "arc42 template", "initialize architecture docs", "update arc42", "architecture documentation template", "building block view", "deployment view", "runtime view", "crosscutting concepts", "architecture decisions", or needs guidance on creating, updating, or reviewing software architecture documentation following the arc42 format.
Generate, update, and review software architecture documentation following the arc42 template -- a pragmatic, proven framework for communicating and documenting software architectures.
Arc42 organizes architecture documentation into 12 sections, each serving a distinct purpose:
| # | Section | Purpose |
|---|---|---|
| 1 | Introduction and Goals | Requirements overview, quality goals, stakeholders |
| 2 | Architecture Constraints | Technical, organizational, and political constraints |
| 3 | Context and Scope | Business and technical context with external interfaces |
| 4 | Solution Strategy | Technology decisions, decomposition approach, quality strategies |
| 5 | Building Block View | Static decomposition of the system (most important section) |
| 6 | Runtime View | Key scenarios showing building blocks in action |
| 7 |
| Deployment View |
| Infrastructure, environments, and mapping to building blocks |
| 8 | Crosscutting Concepts | Domain models, security, patterns, operational concerns |
| 9 | Architecture Decisions | ADRs or decision log with rationale and consequences |
| 10 | Quality Requirements | Quality tree and concrete quality scenarios |
| 11 | Risks and Technical Debt | Known risks, debt items, and mitigation plans |
| 12 | Glossary | Domain and technical terms with definitions |
Arc42 is pragmatic, not bureaucratic. Not every section is mandatory. Adapt depth and breadth to the project.
Three profiles control which sections to generate:
docs/adr/, docs/decisions/, doc/architecture/decisions/).This section is broad and varied. Typical subcategories include:
To extract architectural information from a codebase, follow this six-step process:
README.md, package manifests (package.json, *.csproj, pyproject.toml, Cargo.toml), and project files to identify name, purpose, and tech stack.src/main/, src/lib/, src/app/), and public API surfaces to identify building blocks..env.example, config objects, feature flags, and CI/CD configs to understand deployment environments and constraints.Dockerfile, docker-compose.yml, Kubernetes manifests, Terraform/Pulumi files, and CI/CD pipelines for deployment topology.CHANGELOG.md, and architecture-related comments.Map each discovered artifact to specific arc42 sections using the analysis guide reference.
Generate one markdown file per section, numbered with zero-padded prefixes:
architecture/
├── README.md # Index with section links and status
├── 01-introduction-and-goals.md
├── 02-architecture-constraints.md
├── 03-context-and-scope.md
├── ...
└── 12-glossary.md
Include Mermaid diagrams inline for:
Create a README.md index file linking all sections with completion status and last-updated dates.
When updating existing arc42 documentation:
<!-- arc42-generated --> ... <!-- /arc42-generated --> -- Content safe to replace with updated generated content.<!-- arc42-manual --> ... <!-- /arc42-manual --> -- Content written by humans. Preserve entirely. Never modify.Check for .claude/arc42-doc-generator.local.md in the project root. If present, parse YAML frontmatter for:
output_directory -- Target directory for arc42 files (default: architecture/)profile -- Documentation depth: essential, lean, or thorough (default: lean)sections_to_skip -- Array of section numbers to omitauto_diagrams -- Whether to generate Mermaid diagrams (default: true)Command arguments override settings file values, which override defaults.
For detailed templates, analysis methodology, and quality criteria, consult:
references/section-templates.md -- Full markdown templates for all 12 arc42 sections with subsections, placeholder tables, and Mermaid diagram blocksreferences/analysis-guide.md -- Comprehensive mapping of 30+ project artifact types to specific arc42 sections and subsectionsreferences/quality-checklist.md -- Per-section completeness criteria across essential/lean/thorough profiles with rating scalereferences/diagram-templates.md -- Mermaid diagram patterns for context, building block, deployment, runtime, quality tree, and C4 views