Back to Guides

A short AI-narrated film with English captions. Pressing play loads the YouTube player. Watch on YouTube

Guide Origin: Community

/arckit-arc42:arc42 writes an arc42 architecture description for a project. arc42 is a 12-section template for documenting the architecture of one software system, widely used by solution and software architects. The command does not design anything: it assembles each section from the artefacts ArcKit has already produced, cites them by Document ID, and lists the sections no artefact covers yet. The command is part of the arckit-arc42 overlay, which needs the core arckit plugin.

The adapted template, including its structure, headings and guidance, is licensed under CC BY-SA 4.0, based on arc42 by Peter Hruschka and Gernot Starke. ArcKit changed the explanatory text and added Document Control, source citations, a Gap Register, a Source Artefacts table and assumptions for optional information. Every copied or embedded template retains this licence and attribution. Original ArcKit implementation code remains MIT-licensed. Project-specific content and cited artefacts retain their own licences and confidentiality rules: as arc42's licence page puts it, publishing an architecture document in arc42 structure does not place your content under CC BY-SA. Each generated description therefore keeps the template's written attribution notice but not its licence metadata (the template's frontmatter and SPDX tag).

When to Use

Use when any of these apply Do not use when
A delivery team, reviewer or supplier expects architecture documentation in arc42 form The project has no requirements, stakeholder analysis, HLD review, diagrams or ADRs yet: there is nothing to assemble
You want one readable description of a system, instead of pointing readers at a dozen artefacts You need to make architecture decisions (use /arckit:adr) or review a design (use /arckit:hld-review)
You want to see which parts of the architecture are still undocumented You want an enterprise-level view across many systems (use /arckit:framework or the TOGAF ADM overlay)

Inputs

An existing project is required. The command uses the project ID or name supplied, a project named earlier in the conversation, or the sole existing non-global project. 000-global is never a target: it holds enterprise-wide artefacts, not the architecture of one system. It never allocates project numbers or creates project folders. If the project is missing or ambiguous, it stops without writing files and explains how to initialise source artefacts or re-run with an explicit ID.

No single artefact is mandatory. The command stops if the project has none of requirements, stakeholder analysis, HLD review, diagrams or ADRs. Global architecture principles feed sections 2 and 4 but are not enough on their own, because almost every repository has them. Run /arckit:stakeholders <project-name> and /arckit:requirements <project-name> first when starting a project, with /arckit:principles for global principles.

Optional Information and Unattended Runs

The command follows ArcKit's interview pattern and needs no interview. It uses the owner in the arguments or project metadata, otherwise [PENDING]. If no external documents are supplied, it proceeds with existing ArcKit artefacts. Defaults are recorded in the document's Assumptions section and closing summary; they never supply architecture decisions. Headless and recipe-worker runs do not wait for optional answers.

To add an external architecture description later, place it in the project's external/ folder and re-run the command. To change a pending owner, supply the owner in the arguments or project metadata and re-run.

Artefact Feeds arc42 section
Requirements (ARC-<id>-REQ-v*.md) 1 Introduction and Goals, 2 Constraints, 10 Quality Requirements
Stakeholder analysis (ARC-<id>-STKE-v*.md) 1.3 Stakeholders
Business case (ARC-<id>-SOBC-v*.md) 1 Introduction and Goals
Architecture principles (ARC-000-PRIN-v*.md) 2 Constraints, 4 Solution Strategy
Architecture strategy, Wardley maps 4 Solution Strategy
Diagrams (diagrams/ARC-<id>-DIAG-*.md, DFD) 3 Context, 5 Building Blocks, 6 Runtime, 7 Deployment
HLD and DLD reviews, vendor HLD/DLD 4, 5, 8
ADRs (decisions/ARC-<id>-ADR-*.md) 4 Solution Strategy, 9 Architecture Decisions
Data model (ARC-<id>-DATA-v*.md) 5 Building Blocks, 8 Crosscutting Concepts
Platform design, DevOps strategy, operational readiness 5, 7 Deployment View, 8
Secure by Design (ARC-<id>-SECD-v*.md) 8 Crosscutting Concepts (security)
Crosscutting concepts (ARC-<id>-CONC-v*.md, from /arckit-arc42:arc42-concepts) 8 Crosscutting Concepts
Quality scenarios (ARC-<id>-QUAL-v*.md, from /arckit-arc42:arc42-quality) 1.2 Quality Goals, 10 Quality Requirements
Risk register, codebase audit, conformance assessment 11 Risks and Technical Debt
Technical debt register (ARC-<id>-DEBT-v*.md, from /arckit-arc42:arc42-debt) 11.2 Technical Debt
Glossary (ARC-<id>-GLOS-v*.md) 12 Glossary
Project and enterprise external documents Any section, with citations

Command

Claude Code

/arckit-arc42:arc42 <project ID or name>

Codex CLI

$arckit-arc42 <project ID or name>

Both commands write projects/<id>-<name>/ARC-<id>-ARC42-v1.0.md.

If an arc42 description already exists, the command writes the next version beside it instead of overwriting it.

Building the Source Artefacts

The arc42-full recipe uses the Claude Code only build harness to generate the source artefacts, including the quality scenarios and crosscutting concepts, and then assemble the description:

/arckit:build <project-name> --recipe arc42-full --plan   # wave-plan dry run
/arckit:build <project-name> --recipe arc42-full          # full build

Add --exclude SECD to skip the Secure by Design assessment; the security concept in section 8 is then recorded as a gap. Add --enable DEBT for an existing system to consolidate its technical debt for section 11.2, and --enable SDDH to write an SDD handover pack after the description.

Evidence the recipe never needs to generate is read when it already exists: an existing backlog (BKLG), codebase audits (CDAU), conformance assessment (CONF), HLD and DLD reviews (HLDR, DLDR) and principles compliance assessment (PRIN-COMP). These optional targets are off by default, so the harness adopts any that exist and passes them to the description, the concepts, the debt register and the handover; it never builds one just to satisfy a dependency. --enable one to build a new one instead of reading the existing one, or --exclude it to ignore an existing one. When adopted evidence changes, such as a new audit or a later version of the backlog, the next --resume rebuilds the documents that read it. A rebuilt document also reads its own previous version, so technical debt IDs and feature numbers stay stable.

In Codex, run the source commands individually before $arckit-arc42. Start with $arckit-principles, $arckit-stakeholders and $arckit-requirements if the project has no source artefacts. Add the sources for the sections you need; the Inputs table shows which command outputs each section uses.

For example, to build the recipe's sources for an appointment-booking system in project 001, run these commands in order, completing each artefact before continuing:

$arckit-principles
$arckit-stakeholders appointment-booking
$arckit-requirements appointment-booking
$arckit-adr 001 Top-level decomposition and technology approach
$arckit-adr 001 Deployment topology and hosting
$arckit-data-model 001
$arckit-diagram 001 C4 context
$arckit-diagram 001 C4 container
$arckit-diagram 001 sequence for the primary user journey
$arckit-diagram 001 deployment
$arckit-secure 001
$arckit-risk 001
$arckit-glossary 001
$arckit-arc42-quality 001
$arckit-arc42-concepts 001
$arckit-arc42 001

For an existing system, run $arckit-arc42-debt 001 before $arckit-arc42. To hand the result to Spec Kit, run $arckit-arc42-handover 001 after it.

Reuse source artefacts that already exist. A complete source set is not required to run the assembly command: missing sections are recorded in the Gap Register.

How Sections Are Filled

  • Summarised, not copied. Each section summarises its sources and cites them. The cited artefacts remain authoritative, so when an ADR changes you update the ADR and re-run /arckit-arc42:arc42.
  • Diagrams reproduced unchanged. Context, container, sequence and deployment diagrams are copied from their DIAG artefacts. The command never draws a diagram no artefact backs.
  • Gaps recorded, not filled. A section with no source says "Not yet documented." and appears in the Gap Register with the command that would fill it, such as /arckit:diagram sequence <scenario> for an empty Runtime View.
  • Dedicated sources preferred. Where /arckit-arc42:arc42-concepts, /arckit-arc42:arc42-quality or /arckit-arc42:arc42-debt has written its document, sections 8, 10 and 11.2 summarise and cite it instead of deriving the content again.
  • Inferences marked. Quality scenarios derived from NFRs with measurable targets are marked "Inferred", with the NFR they came from.
  • Conflicts reported. Where two artefacts disagree, the section cites both instead of choosing one silently.

Deliverable Snapshot

Section Contents
Document Control Document ID, owner, status, classification; sections complete and sources read
1–12 The arc42 sections, each summarising and citing its sources
Gap Register Each empty or partial section, what is missing, and the command that would fill it
Source Artefacts Every artefact read, its version, and the sections it fed
Assumptions Defaults used for optional metadata and external documents
External References Document Register and citations for external documents

Keeping It Current

The description is a view over the project's artefacts, so it goes out of date when they change. The Source Artefacts table records the version of each artefact it was built from. When a newer version of any of them exists, re-run /arckit-arc42:arc42 to produce the next version of the description. /arckit:health flags a description that has fallen behind its sources as STALE-VIEW.

Review Checklist

  • All 12 arc42 sections are present, in order, with their arc42 numbers.
  • Every populated section cites at least one source by Document ID.
  • No section contains content without a source; empty sections are in the Gap Register.
  • Diagram code matches the cited DIAG artefact.
  • "Inferred" items have been checked by the architects who own the source artefacts.
  • The adapted template's CC BY-SA 4.0 licence, attribution and changes notice are still in the document, and no license: frontmatter or SPDX tag was copied from the template.

Next Steps

  • /arckit:diagram - Fill an empty Context, Building Block, Runtime or Deployment view.
  • /arckit:adr - Record a decision the Solution Strategy relies on but no ADR covers.
  • /arckit:risk - Add risks or technical debt the description surfaced.
  • /arckit:glossary - Build the glossary the arc42 Glossary section summarises.
  • /arckit:traceability - Check requirements trace through to the building blocks described.
  • /arckit-arc42:arc42-quality, /arckit-arc42:arc42-concepts, /arckit-arc42:arc42-debt - Fill sections 10, 8 and 11.2 with dedicated source documents.
  • /arckit-arc42:arc42-handover - Hand the described architecture to a Specification Driven Development tool such as Spec Kit.