2-day on-site workshop for engineering teams
Primary goal: learn to make strong architecture decisions as a team
ADRs and requirement clarity – deliver what the customer actually needs
ADRs are not the end goal here; they are a byproduct. The core outcome is a team that can make clear, aligned architecture decisions together.
Day 1 – How decisions are made (and broken)
Goal: learn how to make strong architecture decisions as a team; ADR documentation is a consequence, not the objective.
09:00–10:15 - The problem of invisible decisions
Build shared language around why decision rationale disappears.
- "Who decided this?" as the classic end-of-project question.
- Typical symptoms: "It has always been this way", "Previous team decision", "We don't touch this anymore".
- ADR as memory, conflict prevention, and onboarding accelerator.
Exercise: Bring one real decision from your project that nobody remembers clearly anymore.
10:30–12:30 - What an ADR really is (and what it is not)
Practice the minimal structure of a useful ADR.
- ADR is not a design doc, not a ticket comment, and not post-factum justification.
- Core anatomy: Context, Decision, Options considered, Consequences.
- Depth levels: micro-ADR, normal ADR, architectural line in the sand.
Exercise: Write 3 ADR variants with different depth for the same decision.
13:30–15:00 - When to write ADRs, and when not to
Define practical boundaries so ADRs stay useful.
- Decision matrix: reversible/irreversible, local/system-wide, cheap/expensive to change.
- YAGNI vs ADR: when to document up front and when later.
- Anti-patterns: ADR for everything, ADR never.
Exercise: Classify backlog items: ADR needed / not needed / later.
15:15–16:30 - Ownership and decision rights
Define ownership and approval flow for ADRs.
- Who can write ADRs, who approves, and what happens without consensus.
- ADR as a lightweight decision contract.
Exercise: Draw the flow: idea -> discussion -> ADR -> implementation -> review.
Day 2 – ADRs in a living system
Goal: embed shared decision-making into daily work, with documentation as a practical byproduct.
09:00–10:30 - Building systems with ADRs
Practice under time pressure with real trade-offs.
- Project choices: monorepo vs multirepo, sync vs async, database, auth.
- Every major decision gets an ADR under time pressure.
- Learn what truly slows down and what speeds up delivery.
10:45–12:00 - ADR lifecycle
Learn to keep ADRs current and useful over time.
- Draft -> Accepted -> Superseded -> Deprecated.
- How to avoid building an ADR graveyard.
- Superseding ADRs as evolution, not failure.
Exercise: Supersede an older ADR and write a new one.
13:00–14:30 - ADR and delivery flow
Integrate ADRs into daily delivery.
- Connection to tickets, PRs, and releases.
- Minimum integration: ADR link in PR, ADR ID in commit.
- When ADR should not be a delivery gate.
Exercise: Design a team-specific ADR workflow.
14:45–16:00 - AI, agents, and ADR
Separate useful and harmful AI use around ADRs.
- ADR as prompt input and institutional memory for agents.
- Useful use-cases: decision summarization and impact analysis.
- Non-goal: "let AI write the ADR for us".
Exercise: From one ADR, create onboarding summary and a "why is this like this?" answer.
16:00–16:30 - Closing: what changes from Monday?
Define minimum policy the team can adopt immediately.
- ADR policy v0: when mandatory, where it lives, ownership.
- One thing to start, one thing to stop.
- Workshop retro.
What you take back on Monday
By the end of the workshop, your team has a shared decision-making operating model where useful ADRs emerge naturally.
- Decision matrix for choosing options and identifying when formal decisions are needed.
- Simple ownership model for preparation, review, and decision authority.
- Lifecycle rules for superseding and deprecating ADRs.
- Minimum PR and commit integration guidelines.
