Prepare for arc42 in a Day

01Before the day

Setup checklist

• A laptop with a Markdown editor that previews Mermaid diagrams, or a shared document your team can edit
• An empty file named arc42-team.md (we’ll paste the skeleton in together)
• One system your team could explain from memory, picked or shortlisted
• Your system’s name, a one-sentence purpose and three likely users, written down
• Nothing confidential: no passwords, keys, personal data or client material

Your ticks are saved in this browser only.

02Preparation

Prepare at your level

03Reading

Free and open material

• arc42 documentationThe official guide to each of the twelve sections, with tips.
• arc42 FAQShort answers to common questions, including when not to use arc42.
• Why arc42 and how it is structuredAn overview of the template and where everything lives.
• The arc42 template on GitHubGet it in Markdown or AsciiDoc and keep it in your repository.
• arc42 examplesWorked examples of real documentation.
• arc42 quality modelQuality labels and example scenarios to start from.
• The C4 modelContext, containers, components and code: the zoom levels we use.
• MADRA lean Markdown template for architecture decision records.
• Mermaid documentationText-based diagrams: graphs and sequence diagrams.
• Mermaid live editorTry diagrams in your browser with nothing to install.
• Markdown basic syntaxHeadings, lists, tables and code blocks in one page.
• Architecture as Code, an exampleOne team’s approach combining arc42, C4, ADRs and Mermaid.
• AGENTS.mdAn open format for giving coding agents project instructions.
• What goes in AI context filesA practical write-up on keeping them short, citing a 2026 ETH Zurich study.

Links point to third-party sites that we don’t control. If one has moved, searching for its title will find it.

04Outputs

What you will produce

05Template

Team skeleton

Paste this into arc42-team.md on the day.

# <System name> — arc42 skeleton
## 1. Introduction and Goals
### 1.1 Requirements overview
### 1.2 Quality goals (top 3–5, each with a scenario)
### 1.3 Stakeholders (role, expectation)
## 2. Constraints (ID, constraint, why, effect)
## 3. Context and Scope
### 3.1 Business context (diagram)
### 3.2 Technical context (table)
## 4. Solution Strategy (goal, approach, why, trade-off)
## 5. Building Block View
### 5.1 Level 1 (diagram + table)
### 5.2 Contract: <block>
## 6. Runtime View (scenario + failure branch)
## 7. Deployment View (environments, mapping table)
## 8. Crosscutting Concepts
## 9. Architecture Decisions (ADR-0001…)
## 10. Quality Requirements (tree + scenarios)
## 11. Risks and Technical Debt
## 12. Glossary

Mermaid in 30 seconds

```mermaid
graph LR
  A[Customer] --> B[Order app]
  B -->|HTTPS| C[Payment provider]
```

```mermaid
sequenceDiagram
  Customer->>App: place order
  App-->>Customer: confirmation
```

06Vocabulary

Key terms

Stakeholder and concern

A stakeholder is anyone with an interest in the system. A concern is something they care about, such as recovering a lost order.

Quality scenario

A testable statement of stimulus, response and metric, such as “95% of confirmations appear within 3 s at 300 orders per minute”.

Container and component

A container is something you start: an application or data store. A component is a grouping of related functionality behind an interface inside a container.

Contract

What a block promises and expects: pre-conditions, post-conditions, invariants and error modes.

ADR

An architecture decision record: one significant decision with its context, options, decision and consequences.

Idempotency

Repeating a request has the same effect as doing it once.

07Ground rules

Rules for AI today

Write a human draft first. Then ask AI why, and what’s missing, not only to write it. You decide: give every AI line a verdict of accepted, rejected or edited, with a reason. Use only your workshop case, and never paste passwords, keys, personal data or client-confidential details.

08Self-check

Check before you leave

• All 12 headings present, even rough
• Every quality goal has a scenario with a number
• Every block in section 5 traces to a strategy or goal
• Section 6 participants match section 5 names
• At least one ADR with an alternative and a negative consequence
• IDs (C1, ADR-0001) are referenced somewhere else

09After

Your 30 days

Week 1: finish sections 1–4 with your real team. Week 2: sections 5–6, one contract per critical block. Week 3: three ADRs, five scenarios, risks. Week 4: try the agent experiment (no docs, a short index plus two contracts, or the full arc42) and share what you find.