# Generating Arc42

> Use when asked to generate, create, write, scaffold, or bootstrap arc42 architecture documentation for any software codebase, repository, service, library, or component — including a doc/architecture folder or arc42 chapters derived from source code.

- Skill: `alicommit-malp/generating-arc42` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add alicommit-malp/generating-arc42`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alicommit-malp/generating-arc42/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: alicommit-malp (https://skillmd.com/u/alicommit-malp)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alicommit-malp/generating-arc42

---


# Generating arc42 Documentation

## Overview

Generate an arc42 architecture-documentation **base** for a repository, derived
from its **source code**, using **Mermaid-only** diagrams. Vendor-neutral: built
on the open [arc42](https://arc42.org) template, usable on any project including
open-source.

**Core principle:** document only what the source supports. Generate as much as
the code, config, and history evidence; leave a `TODO:` everywhere the answer can
only come from a human. A flagged gap is better than a confident fabrication.

## When to use

- "Generate / write / scaffold the arc42 docs for this repo."
- "Create the `doc/architecture` chapters for this service or library."
- Bootstrapping architecture documentation for an undocumented codebase.
- Refreshing/extending an existing arc42 base from current source.

Not for: editing one existing chapter's prose, or non-arc42 documentation.

## Workflow

1. **Read the conventions first.** Read `arc42-conventions.md` (in this skill
   directory) IN FULL and follow it exactly — folder structure, chapter set,
   style, Mermaid colour code, and per-chapter guidance. It is the source of
   truth for *how* to write the docs.
2. **Study the real repository.** README, build/config files, manifests, CI,
   and the actual source folders. Derive components, external systems, actors,
   protocols, and runtime scenarios from what you can point to in the code.
3. **Scale depth to the evidence.** Rich codebase → full chapters; small library
   → the core chapters as short stubs (use the stub skeleton defined in
   `arc42-conventions.md`). Don't pad.
4. **Write into `doc/architecture/`**, wrapping each generated chapter body in
   `<!-- arc42:generated -->` / `<!-- /arc42:generated -->` markers. On a refresh,
   replace only what's inside those markers; treat any prose outside them — or any
   chapter that lacks them — as human-authored. Never overwrite it; report the
   conflict instead. Stamp the generation provenance into `README.md` (see the
   conventions).
5. **Verify, then report.** Run the *Quick checklist* in `arc42-conventions.md`
   and fix every failure. Then end with a summary: what you generated, and every
   `TODO:` a human must complete, grouped by chapter.

## Quick reference

Chapters (note the intentional gaps): `01_introduction_and_goals`,
`03_context_and_scope`, `04_solution_strategy`, `05_building_block_view`,
`06_runtime_view`, `07_deployment_view`, `08_crosscutting_concepts/`
(index + the concepts the system actually has, e.g. `001_security`,
`002_domain_model`), `09_architecture_decision_records/` (index + template +
ADRs), `12_glossary`. Plus `README.md` (index) and `pdf.yaml`. **Core chapters
to always produce: 1, 3, 5, 12.** Add 6/7/8 when the system warrants them.
Expect chapter 1's quality goals and stakeholders to be largely `TODO:` when only
the source is available — those aren't derivable from code, and a flagged gap
there is the correct outcome, not a failure.

Mermaid block colours via `classDef`: **blue** = developed here, **green** =
separately-released component with its own docs (link, don't zoom in),
**white** = 3rd-party / external dependency you don't own.

## Common mistakes

- **Inventing facts.** Never fabricate requirement IDs, people's names/emails,
  or owners/identifiers — leave `TODO:`.
- **Speculative ADRs.** ADRs record *history* and rationale, which isn't in the
  code. Author one only when its rationale is evidenced (commits, comments,
  design docs, config that proves a choice); otherwise list it as a `TODO:`
  candidate topic in the ADR index. A made-up ADR reads as settled history.
- **Wrong diagram tool.** Mermaid only. No PlantUML, no draw.io, no `diagrams/`
  subfolder — diagrams are inline fenced ```mermaid blocks.
- **Over-producing.** Don't write chapters the source can't support; stub them.
- **Skipping the reference.** The per-chapter detail in `arc42-conventions.md`
  is required reading, not optional background.