James opened a blank document. After tracing pivots and identifying invariants, 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.
"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?"
Emma set down her coffee. "Write it down. 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 Module 9.3 and analyzed its economics in Module 9.4. You traced the six pivots. But unless you write that reasoning down in a structured format, it lives only in your head.
An Architecture Decision Record (ADR) is a lightweight way to capture the reasoning behind significant choices. The standard format has six sections:
The power of this format is that it separates Context (what was true then) from the Decision (what we chose). It forces honesty about Consequences—the trade-offs that marketing materials usually hide.
Watch how James structures the TutorClaw journey into a professional record.
ADR-001: Use MCP-First Architecture for TutorClaw Status: Accepted
The operator needed to deliver AI tutoring to PIAIC learners. Three goals operated on different timelines: current cohort needs (weeks), book curriculum (one quarter), and revenue validation (ongoing).
Six architectures were considered. We found that every learner already had OpenClaw installed as a course prerequisite. This meant the learner's machine already provided the runtime, LLM connection, and gateway.
Use a remote MCP server as the intelligence layer. Learners install a shim skill that connects their local agent to our remote server. Tools (logic/gating) stay server-side; content lives on R2. The learner's own API key pays for tokens.
An ADR isn't static. It tracks the project's evolution through its status:
[!IMPORTANT] Deprecated ADRs are early warning signals. They say: "This was the right choice once, but the platform dependency risk we identified has started to materialize."
James finished his ADR. "This is like our warehouse change logs. Protection against amnesia. Without this, someone would move the cold storage back to Bay 7 and the pipes would freeze again, because the reason we moved it was invisible."
Emma nodded. "I once shipped a service using polling instead of a queue. It absorbed burst spikes. Six months later, a new hire replaced it with RabbitMQ because 'polling is bad.' Throughput dropped 40%. He reversed a correct decision because I didn't write down the why."
"ADR-001 is your insurance," she said. "Now, how do you maintain the product versioning?"