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

5. Fill Core Sections (Iteratively)

Update your todo list as you complete each section.

Work through sections in recommended order:

1. Use search/* tools to find relevant content in docs/spec.md and feature specifications
2. Start with Section 1 (Introduction and Goals) - easiest to fill from spec.md
3. Add Section 3 (Context and Scope) - define system boundaries
4. Document Section 4 (Solution Strategy) - key architectural decisions
5. Complete Section 5 (Building Block View) - component structure
6. Fill remaining sections based on available information

Progressive approach: It's acceptable to mark sections as "TBD" and fill them over time. The document is a living artifact.

Use edit/editFiles to make changes, NOT terminal text editors or sed/awk commands.

6. Add Visual Diagrams

Update your todo as you add diagrams.

For key sections, create Mermaid diagrams using edit/editFiles:

• Section 3: Context diagram (C4 Level 1)
• Section 5: Component diagram (C4 Level 2/3)
• Section 6: Sequence diagrams for critical scenarios
• Section 7: Deployment diagram

Use the mcp-mermaid tool to preview diagrams before committing.

7. Link Existing ADRs

Update your todo when complete.

Use search/codebase to find all ADR files matching adr-*.md, then in Section 9 (Architecture Decisions):

• List all existing ADRs
• Provide a brief summary of each decision
• Link to the full ADR file

Use edit/editFiles to update the section.

8. Validate Completeness

Review and check your todo list:

• All 12 sections exist (even if marked TBD)
• At least sections 1, 3, 4, 5 are filled with meaningful content
• Diagrams are included for context and building blocks
• Glossary includes domain-specific terms
• No arc42 help text remains in the document

9. Update Documentation Index

Use edit/editFiles to add reference to the arc42 document in docs/architecture.md:

## Comprehensive Architecture Documentation
 
For a complete architecture overview following the arc42 standard, see:
- [arc42 Architecture Documentation](architecture/arc42/architecture.md)

10. Commit the Documentation

Mark your todo complete, then use terminal for git operations only:

git

Maintenance Guidelines

The arc42 document should be:

• Updated when: Major architectural changes occur, new quality requirements emerge, significant risks are identified
• Reviewed: During sprint planning or architecture review meetings
• Versioned: Commit changes with clear messages linking to features/ADRs
• Evolved: It's better to have incomplete sections marked "TBD" than to skip documentation entirely

References

Tips for Success

1. Start small: Fill sections 1, 3, 4 first, then expand
2. Use diagrams: A good context diagram is worth 1000 words
3. Link, don't duplicate: Reference existing ADRs, don't copy them
4. Tailor to audience: Adjust detail level per section based on stakeholders
5. Keep it current: Update when architecture changes, not on a schedule
6. Version control: Commit documentation with related code changes