Write Your First ADR
James opened a blank document. After six lessons of tracing pivots, identifying invariants, and distilling meta-lessons, he had a clear picture of why TutorClaw was built the way it was. The MCP-first architecture was not obvious. It was the sixth design. Four alternatives had been seriously considered and rejected for specific reasons.
"I could explain this to someone in conversation," he said. "But what happens in six months when I have forgotten the details? Or when someone new joins the project and asks why TutorClaw uses an MCP server instead of a custom backend?"
Emma set down her coffee. "Write it down."
"I know how to write documentation," James said. "Feature specs, user guides, READMEs. But those describe what the system does. They do not capture why it was built this way instead of another way."
"That is exactly the problem," Emma said. "The code shows you WHAT was built. The README tells you HOW to use it. Nothing in the repository explains WHY. And the why is the first thing that disappears."
You are doing exactly what James is doing. You built TutorClaw in Chapter 58. You analyzed its economics in Chapter 59. You traced the six pivots that shaped its architecture in this chapter. You can explain why it is built this way. But unless you write that reasoning down in a structured format, it lives only in your head, and heads forget.
If you have been maintaining your Architecture Decision Worksheet since Lesson 3, open it now. Your six-row table of constraints, changes, survivors, invariant/variant classifications, and themes is the raw material for the ADR you are about to write.
Start Writing Before You Have a Template
James started typing. No template. No format guide. Just what he knew.
He wrote:
We chose to build TutorClaw as a remote MCP server instead of a custom brain backend or a container-per-learner system. The main reason was economics: the MCP approach shifts LLM costs to the learner's own API key, which drops our cost from thousands of dollars per month to under a hundred. We also needed IP protection, which Markdown skills could not provide because they are plain text. The MCP server is a black box. And we needed code execution, which only works server-side.
He looked at it. It captured the decision and some of the reasoning. But something was missing.
"This does not explain what you considered and rejected," Emma said, reading over his shoulder. "Someone reading this knows you chose MCP. They do not know you seriously evaluated Custom Brain, NanoClaw, the Hybrid approach, and Markdown skills. They do not know what made each alternative insufficient."
James nodded. "And it does not capture the constraints that existed at the time. The PIAIC cohort needing tutoring in weeks. The book needing to teach NanoClaw. The revenue data question."
"Those constraints shaped the decision," Emma said. "In a year, the constraints might change. If someone reads only your decision without the constraints, they might think MCP was always obviously correct. It was not. It was correct given specific circumstances."
James realized his paragraph needed structure. Not more prose, but sections that separated what the team was facing from what they decided from what alternatives they rejected. He needed a format that made each piece of reasoning findable.
The ADR Format
The format James needed already existed. Architecture Decision Records were introduced by Michael Nygard as a lightweight way to capture the reasoning behind significant architecture choices. The format has six sections:
| Section | What It Captures |
|---|---|
| Title | A short, numbered name for the decision (e.g., "ADR-001: Use MCP-First Architecture") |
| Status | Current state: Proposed, Accepted, Deprecated, or Superseded |
| Context | The situation that existed when the decision was made: constraints, goals, pressures |
| Decision | What was decided and why |
| Consequences | What follows from the decision: benefits gained, trade-offs accepted, risks created |
| Alternatives Considered | What else was evaluated and why each alternative was rejected |
The power of this format is that it separates concerns. The Context section captures information that disappears fastest: what was true at the time. The Alternatives section captures what the code will never show: the paths not taken. The Consequences section forces the author to name trade-offs explicitly, not just benefits.
Notice what the ADR does NOT capture: implementation details. An ADR does not describe API endpoints, database schemas, or deployment configurations. Those belong in technical documentation. The ADR captures the layer above implementation: the reasoning that explains why those specific endpoints, schemas, and configurations exist.
James Writes ADR-001
With the format in front of him, James rewrote his paragraph as a proper ADR. Watch how each section draws from the analysis he did in the previous six lessons.
Title
ADR-001: Use MCP-First Architecture for TutorClaw
A clear, specific title. Not "Architecture Decision" or "Server Choice." The title names the actual decision so someone scanning a list of ADRs can find it without reading the full document.
Status
Accepted
The MCP-first architecture is live in production. The decision has been implemented. This is not a proposal under discussion; it is a decision that has been acted on.
Context
James drew from the pivot analysis in Lessons 1 through 4:
Panaversity needed to deliver AI tutoring to learners in the PIAIC program. Three goals operated on different timelines: the current cohort needed a working tutoring system within weeks, the book needed to teach the better architecture pattern over one quarter, and the business model needed real revenue data on an ongoing basis.
Six architectures were considered across six pivots. Each was triggered by a discovery: platform limitations (OpenClaw's single-tenant security model), SDK redundancy (agent loops inside agent loops), scale constraints (sixteen thousand learners on a four-device limit), engineering timeline conflicts (two to four months for the better architecture), and infrastructure cost assumptions (provider builds and operates everything).
The team's core constraint was that every PIAIC learner already had OpenClaw installed as a course prerequisite. This meant the learner's machine already had an agent runtime, an LLM connection, and a messaging gateway.
The Context section captures what was true when the decision was made. In a year, the PIAIC program might change, OpenClaw might not be a prerequisite, or the team might have different cost constraints. This section preserves the circumstances so a future reader can evaluate whether the decision still applies.
Decision
Use a remote MCP server as TutorClaw's intelligence layer. Learners install a shim skill from ClawHub that connects their OpenClaw agent to the remote server. All pedagogical intelligence, code execution, assessment, and monetization gating live server-side. Content lives on Cloudflare R2 with a Worker gate. The learner's own API key provides the LLM, so Panaversity bears no LLM cost.
The Decision section is deliberately concise. It states what was chosen, not why. The why lives in the Context (the circumstances) and the Alternatives (what was rejected and for what reason).
Consequences
James drew from the economics analysis in Chapter 59 and the invariant/variant analysis from Lesson 5:
Benefits gained:
- LLM cost to Panaversity is zero (learner's API key, learner's cost)
- Infrastructure cost is fifty to seventy dollars per month (single VPS, R2 free tier, Worker free tier)
- Gross margin approaches 99.5%
- IP is fully protected (MCP server is a black box; pedagogical engine is not exposed)
- Code execution is possible (server-side sandbox via submit_code tool)
- Monetization gating is enforceable (tool-level access control per API key)
Trade-offs accepted:
- Platform dependency: TutorClaw only works for learners who have OpenClaw installed
- Protocol dependency: if OpenClaw changes its MCP protocol, TutorClaw must adapt
- Competition surface: competitors can build on the same platform, competing on intelligence quality rather than infrastructure
Risks created:
- Single-platform risk: no fallback if OpenClaw becomes unavailable
- Shim skill maintenance: tool surface changes require a shim update pushed through ClawHub
The Consequences section forces honesty. Listing only benefits is marketing, not architecture documentation. The trade-offs and risks are the sections a future decision-maker will read most carefully, because those are the sections that tell them where the decision might break.
Alternatives Considered
James drew from the four architectures evaluated across the six pivots:
Markdown Skill (Architecture 1): Delivered intelligence as plain-text Markdown. Failed: IP fully exposed (anyone could copy the skill), no code execution capability, REST API calls from Markdown failed on non-frontier models. Rejected because the intelligence could not be protected or extended.
Custom Brain (Architecture 2): WhatsApp Cloud API + FastAPI + PostgreSQL + OpenRouter + Stripe. All learners served by one process. Could ship in weeks. Failed: LLM cost exceeded twelve thousand dollars per month, no code execution sandbox, no per-learner isolation. Rejected because the economics were unsustainable at scale.
NanoClaw-Native (Architecture 3): Container-per-learner isolation with Claude Code Router for multi-model routing. Better architecture, better isolation. Failed: required two to four months of engineering before a single learner could use it. Rejected because the timeline did not match the PIAIC cohort's needs.
Hybrid (Architecture 4): Ship Custom Brain now, teach NanoClaw in book, migrate when data justifies. A deliberate meta-strategy with parallel tracks. Superseded by the Platform Inversion insight: all three tracks assumed Panaversity must build infrastructure, but learners already had the infrastructure.
Each alternative gets a fair description, a specific failure mode, and a clear reason for rejection. This is what makes the Alternatives section valuable: a future reader can see that the team did not ignore these options. They evaluated them and found specific, documented reasons to choose differently.
The Living Document
An ADR is not a gravestone. It does not mark a dead decision. It marks a living one, and living decisions change.
Four status values track an ADR's lifecycle:
| Status | When It Applies |
|---|---|
| Proposed | The decision is under discussion. The team has not committed yet. |
| Accepted | The decision has been made and implemented. This is the active status. |
| Deprecated | The decision is still in place, but conditions have changed and the team should revisit it. The current approach works but may not be the best choice anymore. |
| Superseded | A new decision has replaced this one. The ADR links to the new ADR that replaces it. |
The distinction between Deprecated and Superseded matters. A Deprecated ADR says: "This still works, but we should probably revisit it." A Superseded ADR says: "We made a new decision. Read ADR-007 instead."
For TutorClaw's MCP-first architecture, the status is Accepted. But imagine two scenarios:
If OpenClaw announces that MCP support will be removed in the next major version, the status changes to Deprecated. The decision still works today, but the platform dependency risk identified in the Consequences section has materialized, and the team needs to evaluate alternatives.
If the team builds a new delivery mechanism (perhaps a browser-based client that does not require OpenClaw at all), they write a new ADR explaining that decision and change ADR-001's status to Superseded, with a link to the new ADR.
The status field turns a static document into a decision trail. A new team member reading through the ADR history can trace how the architecture evolved and why, without needing to reconstruct the reasoning from code archaeology.
Your Turn: Write an ADR for Your TutorClaw
You built your own TutorClaw in Chapter 58. You made architecture decisions: which tools to implement, how to structure the MCP server, how to handle content delivery, how to implement gating. Pick one of those decisions and write an ADR for it.
Choose a decision that had alternatives. Something where you considered at least two approaches and chose one for specific reasons. If you are not sure which decision to document, start with the most consequential one: the decision that, if reversed, would require the most rework.
Use the six-section format. Fill in each section from your own experience, not from James's example. The Context section should capture what YOU were facing when you made the decision. The Alternatives section should describe what YOU considered and rejected.
This is not a template exercise. This is a professional practice. Every architecture decision you make in your career will benefit from this format. The five minutes you spend writing an ADR save the five hours a future team member (or your future self) would spend reconstructing the reasoning from code.
Try With AI
Exercise 1: Write an ADR for a Different Decision
Pick an architecture decision from a project you are working on or have worked on. It does not need to be an AI project. Any decision where you chose one approach over alternatives qualifies. Use this prompt:
I need to write an Architecture Decision Record (ADR) for a
decision I made on a project. Here is the decision:
What I chose: [describe the approach you implemented]
What I considered instead: [describe 1-2 alternatives]
Why I chose it: [your reasoning]
What constraints I was facing: [timeline, budget, team size, etc.]
Help me structure this as a proper ADR with six sections:
Title, Status, Context, Decision, Consequences, and
Alternatives Considered. Make sure the Context captures
the constraints that existed at the time, and the
Consequences section lists both benefits AND trade-offs.
What you are learning: The ADR format works for any architecture decision, not just AI or MCP projects. By writing an ADR about your own project, you practice separating the decision (what you chose) from the reasoning (why you chose it) and the trade-offs (what you gave up). This separation is what makes an ADR useful six months later when the reasoning has faded from memory.
Exercise 2: Evaluate an ADR for Completeness
Take the TutorClaw ADR-001 from this lesson (or your own ADR from the exercise above) and evaluate whether it would help a new team member understand the decision. Use this prompt:
Here is an Architecture Decision Record:
[Paste the ADR]
Evaluate this ADR as if you are a new team member who just
joined the project. For each section, answer:
1. Context: Do I understand what situation the team was in?
What is missing that I would need to ask about?
2. Decision: Is the decision clear and specific? Could I
implement it from this description?
3. Consequences: Are the trade-offs honest? Are there risks
that should be listed but are not?
4. Alternatives: Are the rejections fair? Would I want to
re-evaluate any of the rejected alternatives?
Give me specific suggestions for what to add, remove,
or clarify.
What you are learning: Writing an ADR is half the skill. Evaluating one is the other half. A new team member reading your ADR will have questions you did not anticipate. By evaluating your own ADR from an outsider's perspective, you find the gaps before someone else does. The best ADRs are the ones that leave no follow-up questions about the reasoning.
Exercise 3: Convert a Verbal Rationale into an ADR
Think of an architecture decision at work or in a personal project where the reasoning exists only in someone's head (or only in a Slack conversation, or only in meeting notes). Use this prompt to convert it into a structured ADR:
I have an architecture decision that was never formally
documented. Here is what I know about it:
The decision: [what was built]
The reasoning (as best I remember): [why it was built this way]
What I think the alternatives were: [what else was considered]
What I am unsure about: [gaps in my understanding]
Help me convert this into a proper ADR. For the parts I am
unsure about, suggest what I should investigate or who I
should ask. Flag any section where the reasoning seems
incomplete or where a future reader would have questions.
What you are learning: Most architecture decisions are never documented. They live in conversations, Slack threads, and the memories of people who may leave the team. Converting a verbal rationale into an ADR is a practical skill you will use repeatedly. The prompt helps you identify what you know, what you have forgotten, and what you need to ask about. The gaps it reveals are exactly the information that will be lost if you do not document it now.
James finished his ADR and read it through. Six sections. The Context captured the constraints from six pivots. The Alternatives listed four architectures with specific reasons for rejection. The Consequences named both the benefits and the trade-offs.
"This is like what we did at the warehouse with process change logs," he said. "Every time we changed a shipping route or a storage layout, we were supposed to write down why. Not just what changed, but why we changed it. The operations manager called it 'protection against amnesia.'"
He paused. "Most people skipped the log. They thought it was paperwork. Then three months later, someone would ask why we stopped using Bay 7 for cold storage, and nobody could remember. So someone would move cold storage back to Bay 7, and the pipes would freeze again, because the whole reason we moved it was the pipe insulation problem. The change log would have saved them ten minutes of reading and two days of cleanup."
Emma was quiet for a moment. "I should tell you something about that. On a previous project, I shipped a service with a custom event-routing architecture. The routing was unusual: instead of a message queue, we used a shared-state table with polling. It worked, and it was fast, and the team stopped thinking about it. I never wrote down why we chose polling over a queue."
She looked at the wall. "Six months later I moved to a different team. The engineer who took over the service saw the polling pattern and assumed it was a mistake. Polling is generally considered worse than push-based queues. So he replaced it with RabbitMQ. The migration took two weeks. And the throughput dropped by forty percent, because the whole reason we used polling was that our write pattern had bursty spikes that overwhelmed the queue's acknowledgment protocol. The shared-state table absorbed bursts without backpressure."
"He reversed your decision because he did not know your reasoning," James said.
"Because I did not write it down," Emma said. "The decision looked wrong without the context. Polling looks like a shortcut. It was an optimization for a specific load pattern. If I had written a one-page ADR with Context and Consequences, he would have seen the burst-absorption rationale and either kept the architecture or made a more informed choice to replace it."
James looked at his ADR-001. "The decision document is not bureaucracy."
"It is insurance," Emma said. "Against your future self forgetting why, and against the next person assuming you made a mistake." She stood up. "You have documented why TutorClaw is built this way. Now: how do you maintain it over time? The shim skill you built in Chapter 58 has a version number. What does that version mean?"