Arc42 Architecture Documentation Skill

Guide for using the arc42-mcp-server MCP server to create and maintain architecture documentation following the proven arc42 template. The server provides 6 tools, supports 11 languages and 2 output formats (AsciiDoc, Markdown).

Prerequisites

The arc42-mcp-server MCP server must be configured and running. See setup instructions for installation and configuration.

Workflow: Starting Fresh

1. Load the guide → arc42-workflow-guide — understand the full arc42 structure and what belongs in each section
2. Initialize workspace → arc42-init — creates directory structure with all 12 section files, config.yaml, and README
3. Check status → arc42-status — see current progress, completeness percentage, and which sections need work
4. Generate template → generate-template — get the detailed structure and guidance for a specific section before writing
5. Write content → update-section — write or append content to a section
6. Review content → get-section — read back existing content with metadata (word count, last modified)

Workflow: Existing Documentation

1. Check status → arc42-status — assess current state and identify gaps
2. Read sections → get-section — review what's already documented
3. Generate template → generate-template — understand expected structure for incomplete sections
4. Update sections → update-section — fill gaps or improve existing content

Tool Reference

1. arc42-workflow-guide

Load the comprehensive arc42 documentation workflow guide. Always call this first when starting a new documentation effort — it explains what information belongs in each section.

Returns: Complete workflow guide text with section explanations, available languages, supported formats, and workspace root path.

2. arc42-init

Initialize the arc42 documentation workspace. Creates arc42-docs/ directory with all 12 section files, config.yaml, README, and a main documentation file.

Returns: Workspace root path, sections created count, config (including arc42 template reference version, date, and commit SHA).

Created structure:

<targetFolder>/arc42-docs/
├── README.md
├── arc42-documentation.adoc (or .md)
├── config.yaml
├── sections/
│   ├── 01_introduction_and_goals.adoc (or .md)
│   ├── 02_architecture_constraints.adoc (or .md)
│   └── ... (all 12 sections)
└── images/

3. arc42-status

Check documentation completion status. Shows per-section progress with word counts, completeness percentages, and overall progress.

Returns: Project name, initialized state, language and format info, arc42 template reference version, per-section status (exists, word count, completeness 0-100%, last modified), and overall completeness percentage.

4. generate-template

Generate a detailed template for a specific section. Always use this before writing content — it provides the expected structure, subsections, and guidance for what information to include.

Returns: Complete template content with guidance, section metadata (title, description, order), format details.

5. update-section

Write content to a specific section. Format is auto-detected from existing files or config.yaml.

Returns: Section title, file path, detected format, word count, and write mode used.

Important: Use mode: "append" when adding ADRs (Section 9) or adding incremental content to avoid overwriting existing entries.

6. get-section

Read content from a specific section, including metadata.

Returns: Section content, language, format, title, description, and file metadata (path, last modified timestamp, word count, file size in bytes).

The 12 Arc42 Sections

Recommended Documentation Order

Start with the most impactful sections. You do NOT need to document all 12 sections sequentially.

Behavioral Guidelines

Before Writing Any Section

1. Generate the template first — call generate-template for the section to understand the expected structure and subsections
2. Ask clarifying questions — never assume project details; ask the user about their specific context, technologies, and decisions
3. Check existing content — call get-section to see if there's already content to build upon
4. Respect the configured format — call arc42-status to check whether the project uses AsciiDoc or Markdown, then write content in that format

Content Quality

• Document WHY, not just WHAT — focus on rationale and trade-offs behind decisions
• Include diagrams — use Mermaid or PlantUML syntax for context diagrams, building block views, deployment views, and sequence diagrams
• Be specific — use concrete technology names, version numbers, and measurable quality attributes
• Keep sections focused — each section has a distinct purpose; avoid duplicating information across sections
• Use proper formatting — match the output format (AsciiDoc uses = headings, admonitions with NOTE:, TIP:; Markdown uses # headings)

ADR Best Practices (Section 9)

• Always use mode: "append" when adding new ADRs to avoid overwriting existing ones
• Always call get-section first to read existing ADRs and determine the next ADR number
• Follow a consistent ADR structure: Title with number, Status, Context, Decision, Consequences (positive and negative)

Using Tool Responses

Every tool response includes:

• success — boolean indicating whether the operation succeeded
• message — human-readable summary of what happened
• data — structured response data (varies by tool)
• nextSteps — array of suggested follow-up actions; use these to guide the user on what to do next

Multi-Language Support

11 languages are supported. Set the language during arc42-init; it persists in config.yaml and applies to all subsequent operations.

Multi-Format Support

Set the format during arc42-init. The update-section tool auto-detects the format from existing files or config.yaml. Format aliases (md/adoc) are accepted anywhere a format parameter is used.

Examples

See references/examples.md for detailed usage examples covering:

• Starting a new project from scratch
• Documenting a specific section (e.g., deployment view)
• Adding Architecture Decision Records (ADRs) with proper append mode
• Documenting cross-cutting concepts
• Multi-language documentation
• Reviewing and improving existing documentation
• Re-initializing an existing workspace