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: Introduction and Goals - Requirements overview, quality goals, stakeholders Constraints - Technical and organizational limitations Context and Scope - System boundaries, external interfaces Solution Strategy - Fundamental architectural decisions Building Block View - Static decomposition (components, modules) Runtime View - Dynamic behavior (scenarios, workflows) Deployment View - Infrastructure and technical environment Crosscutting Concepts - Recurring patterns and principles Architecture Decisions - Important ADRs with rationale Quality Requirements - Quality tree and scenarios Risks and Technical Debt - Known issues and limitations 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: Use search/ tools to find relevant content in docs/spec.md and feature specifications Start with Section 1 (Introduction and Goals) - easiest to fill from spec.md Add Section 3 (Context and Scope) - define system boundaries Document Section 4 (Solution Strategy) - key architectural decisions Complete Section 5 (Building Block View) - component structure 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

add

docs/architecture/arc42/ docs/architecture.md

git

commit

-m

"docs: add arc42 architecture documentation"

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

Resource

Description

arc42.org

Official arc42 website with downloads and examples

arc42 Docs

Detailed explanations of each section with practical tips

arc42 by Example

Real-world architecture documentation examples

arc42 on GitHub

Template source repository

iSAQB Curriculum

Certification program that uses arc42

Tips for Success

Start small

Fill sections 1, 3, 4 first, then expand

Use diagrams

A good context diagram is worth 1000 words

Link, don't duplicate

Reference existing ADRs, don't copy them

Tailor to audience

Adjust detail level per section based on stakeholders

Keep it current

Update when architecture changes, not on a schedule

Version control

Commit documentation with related code changes