Arc42 Documentation

arc42 Architecture Documentation

Purpose

Generate complete, structured architecture documentation following the proven arc42 template (https://arc42.org/). The template provides 12 standardized sections covering all aspects of software architecture, from stakeholder requirements to technical implementation details.

When to Use This Skill

• Starting a new project that needs comprehensive architecture documentation
• Documenting existing systems that lack structured architecture descriptions
• Creating architecture overviews for stakeholders with different technical levels
• Preparing architecture documentation for certification (e.g., iSAQB)
• Establishing a consistent documentation standard across multiple projects

arc42 Template Overview

The arc42 template consists of 12 sections:

1. Introduction and Goals - Requirements overview, quality goals, stakeholders
2. Constraints - Technical and organizational limitations
3. Context and Scope - System boundaries, external interfaces
4. Solution Strategy - Fundamental architectural decisions
5. Building Block View - Static decomposition (components, modules)
6. Runtime View - Dynamic behavior (scenarios, workflows)
7. Deployment View - Infrastructure and technical environment
8. Crosscutting Concepts - Recurring patterns and principles
9. Architecture Decisions - Important ADRs with rationale
10. Quality Requirements - Quality tree and scenarios
11. Risks and Technical Debt - Known issues and limitations
12. Glossary - Domain and technical terminology

Hard Rules

Must

• Use the todo tool to track progress through the arc42 documentation workflow
• Prefer search/*, read/*, and edit/* tools over terminal commands for file operations
• Create documentation in docs/architecture/arc42/ directory
• Use the template structure provided in templates/arc42-template.md
• Fill in all 12 sections (mark sections as "TBD" if information is not yet available)
• Include references to existing ADRs in Section 9 (Architecture Decisions)
• Update docs/architecture.md to reference the new arc42 documentation
• Tailor content to the specific project context (remove boilerplate explanations)
• Use Mermaid diagrams for visual representations (context, building blocks, deployment)
• Keep stakeholder-focused sections (1, 3, 10) accessible to non-technical readers
• Minimize terminal approvals by using editor tools instead of shell commands
• Ensure arc42 documentation stays synchronized with existing ADRs and feature specifications
• Ask the user for clarification when information is missing or unclear (one question at a time)
• Base all documented requirements, constraints, and quality goals on actual specifications or user input

Must Not

• Use terminal commands for file editing when edit/* tools are available
• Skip using the todo tool for multi-step workflows
• Copy arc42 help text verbatim into the final document
• Create documentation that duplicates existing ADRs without adding value
• Skip sections without marking them as "TBD" or "Not Applicable"
• Use arc42 as a substitute for code-level documentation
• Create arc42 docs for trivial features (use standard ADRs instead)
• Invent or fabricate requirements, constraints, quality goals, or technical details
• Proceed with incomplete information when user clarification is available

Actions

1. Initialize Todo Tracking

Create a todo list with the todo tool to track your progress through the arc42 workflow:

• Assess documentation scope
• Create directory structure
• Generate arc42 document from template
• Fill core sections (1, 3, 4, 5)
• Add visual diagrams
• Link existing ADRs
• Validate completeness
• Update documentation index
• Commit documentation

2. Assess Documentation Scope

Ask the maintainer one question at a time:

• Is this for the entire system or a specific subsystem/feature?
• Are there existing ADRs that should be referenced in Section 9?
• What level of detail is needed (high-level overview vs. detailed technical spec)?
• Who are the primary stakeholders (developers, architects, management)?

3. Create Directory Structure

Use edit/createFile tool (not terminal commands) to create the directory and initial file.

4. Generate arc42 Document

• Use read/* tool to read templates/arc42-template.md
• Use edit/createFile to create the customized version at docs/architecture/arc42/architecture.md
• Do NOT use terminal commands like cp or cat - prefer editor tools