Skip to main content

Design Doc and ADR Katas

Focused, repeatable exercises that produce the capstone's written deliverables. Each kata has a time box; finish inside the box. If you can't, the artifact is too big -- cut, don't extend.

Kata 1: The 12-Section Design Doc Skeleton​

Time limit: 30 minutes
Goal: produce the design doc skeleton with every section filled at least minimally.
Setup: a new library/raw/design-doc.md in your capstone repo.

Create the 12-section structure from concept 10. Paste in the artifacts you already have (problem, MVP, risks, glossary, subdomains, characteristics, style decision). For sections not yet written (ADRs, C4, fitness functions, schedule), use TODO markers.

Repeat until: you can scroll through the doc and every section is non-empty by end of week 1.

Kata 2: C4 at Three Levels in Mermaid​

Time limit: 30 minutes
Goal: draw Context, Container, and Component diagrams in Mermaid.
Setup: the design doc skeleton from Kata 1.

Draw:

  • Level 1 (Context): your system as one box, with users and external systems around it. 3-7 boxes total.
  • Level 2 (Container): deployable / runtime units inside your system. For a modular monolith this is often 3-5 boxes. Labels use glossary terms.
  • Level 3 (Component): decompose only the core subdomain into 5-10 components.

Embed all three in the design doc's Diagrams section. Commit the Mermaid source (not PNGs).

Repeat until: you can redraw all three on a whiteboard without reference in under 5 minutes.

Kata 3: Three ADRs in Nygard Format​

Time limit: 45 minutes (15 per ADR)
Goal: write ADR-001 (style), ADR-002 (datastore), ADR-003 (deployment topology).
Setup: a library/raw/adr/ folder and the canonical structure from concept 12.

For each ADR, fill:

  • Title -- noun phrase.
  • Status -- Accepted, with date.
  • Context -- reuses language from your characteristics file and risk register.
  • Decision -- stated as a claim.
  • Consequences -- at least one positive, at least one negative, at least one foreclosed option.
  • Alternatives -- named, each rejected with a one-sentence reason.

Link each ADR from the design doc's ADR index.

Repeat until: each ADR fits on one page and can be read in two minutes.

Kata 4: The 5-Minute Architecture Defense​

Time limit: 20 minutes (rehearsal) + 5 minutes (delivery)
Goal: give a clean 5-minute walkthrough with anticipated-question answers ready.
Setup: all three diagrams plus the three ADRs visible on one screen.

Structure:

  • 60 seconds: context (what, for whom, what it proves).
  • 2-3 minutes: walkthrough using Context -> Container -> Component, citing ADRs as you go.
  • 60-90 seconds: trade-offs (what you chose, what you rejected, what you'd change with more time).

Then: draw 3 random questions from your library/raw/defense.md anticipated-question list. Answer each from memory.

Repeat until: you can deliver the 5 minutes cold, without the design doc visible, and hit your anticipated answers for 8 of 10 questions.

Kata 5 (optional): ADR Critique​

Time limit: 20 minutes
Goal: sharpen your own writing by critiquing someone else's.
Setup: find one real ADR in the wild -- the joelparkerhenderson/architecture-decision-record GitHub has a catalog of examples.

Read one. Write a one-paragraph critique: what is strong about it, what is missing, what would you add. Then reread one of your own ADRs and apply the same critique to it.

Repeat until: your own ADRs improve measurably between drafts.

Completion Standard​

  • Design doc has 12 sections, each non-empty.
  • Three C4 diagrams are embedded and have Mermaid source in the repo.
  • Three ADRs are written and linked from the design doc.
  • You can give the 5-minute defense from memory, cold.
  • You can answer 8 of 10 anticipated questions without looking at the doc.