12KB
Context Engineering — Chapter-13: ADRs
- Source: /library/Context Engineering/source-file.pdf
- PDF pages: 82–89
- Pages without text: none
ADRs The question that closed the previous chapter does not stay unanswered for long. On a Tuesday, you ask the agent for an analysis of VilaSchedule’s architecture before you plan the next quarter, and the report comes back with one proposal highlighted, well argued and full of good intentions: replace the fixed 30-minute intervals with a free-form schedule, where each appointment has a duration of its own. The agent lists the gains fluently. Short appointments would stop wasting minutes of the interval; long procedures would fit in the schedule; the data model would get more flexible. It even offers a migration plan, in phases, with an estimate per phase. It is the kind of proposal that passes in a planning meeting if nobody in the room remembers why things are the way they are. And nobody remembers. You ask on the team channel why the schedule uses fixed intervals and you get three answers: “it has always been that way,” “I think it was Ricardo’s call,” and a link to a Slack thread from 2024 that the workspace’s retention plan has since deleted. Ricardo left the company a year ago. The living doc from chapter 9 says, with a test behind it, that the interval runs 30 minutes; the work-in spec records that the clinical coordinator capped work-ins, the extra appointments squeezed into a full schedule, at two per day. No artifact in the project says why fixed intervals beat the free-form schedule, which alternatives lost and what was accepted as a cost. The decision exists in the system and exists nowhere a context window can reach.
Notice the exact risk in that void, because it grew when agents entered the cycle. Among humans, the unrecorded decision cost archaeology: a meeting to rebuild the why, a lunch with somebody who was there. An agent does not set up meetings. It reads the code, sees the constraint without seeing the reason, and by this point in the book you know what models do with gaps: they fill them with the most likely pattern from training. And the most likely pattern, faced with a constraint that has no visible reason, is to treat it as technical debt to remove. Tuesday’s proposal is not an error by the model; it is the correct answer to the input it received, an input where the constraint was present and the motivation was not. A decision whose why is not in the window is one well-meaning refactor away from being undone. A record for the why The missing artifact has a name, a format and a precise origin. In 2011, Michael Nygard published “Documenting Architecture Decisions” (cognitect.com/blog) and proposed the architecture decision record (ADR): a short document, one per decision, kept in the repository next to the code, with five parts: title, status, context, decision and consequences. Nygard’s proposal grew out of the same scenario as your Tuesday, with no AI anywhere in it: teams that inherit systems full of decisions whose rationale evaporated with the people, and that therefore swing between two errors: accepting everything blindly or changing everything blindly. See the format in action on the decision the agent wanted to undo. VilaSchedule’s ADR-001 opens by laying out the forces at play at the time:
Context
Vila Nova Clinic needs a per-provider schedule in VilaSchedule. Two approaches were discussed with the clinical coordinator:
- Free-form schedule: each appointment has its own duration, set when it is scheduled, and the schedule is a continuous timeline.
- Fixed intervals: the day is divided into blocks of a single duration and each appointment takes exactly one block. The front desk schedules appointments by phone, on average one every two minutes at peak hours, and often gets the duration wrong when the system asks for that field. The clinic's specialties have appointments of similar duration (20 to 35 minutes). The largest insurance plan audits the schedule by number of appointments, not by minutes. The free-form schedule ties openings, work-ins and utilization to arithmetic over time ranges; the clinic's two previous systems, which used a free-form schedule, produced
overlaps that the front desk resolved by hand. That is the paragraph the deleted Slack thread contained, and notice what it has that no code will ever have: the losing alternative. VilaSchedule’s code shows fixed intervals working; only the ADR shows that the free-form schedule was considered, and that it lost for reasons that are not technical: the front desk that gets duration wrong on the phone, the insurance plan that audits by appointment, two previous systems that failed the other way. None of that is derivable from the repository, because none of it is in the repository; it was born in a conversation with the clinical coordinator, like the business rules of chapter 8. The difference is what each one records: the spec records what the team decided to build, and the ADR records why it decided that way instead of the other. The decision itself is short, and it should be:
Decision
Each provider's schedule will be composed of fixed 30-minute intervals, generated from the weekly schedule. A regular appointment takes exactly one interval. Extra appointments do not use an interval: they come in as work-ins, with a duration and limits of their own defined by the clinical coordinator.
And then comes the section that separates a mature ADR from a defensive justification, the one that lists the consequences, including the bad ones:
Consequences
- Scheduling becomes trivial for the front desk: pick a free block, with no duration to enter. Overlap becomes impossible by construction.
- Utilization and reports count intervals, aligned with the insurance plan's audit.
- Short appointments waste minutes of the interval; we accept that cost in exchange for predictability.
- Procedures longer than 30 minutes do not fit the model and stay outside VilaSchedule; if the clinic starts to offer them, this decision has to be revisited (a new ADR, not an edit to this one).
- Same-day demand finds no free interval in a full schedule; the
escape hatch is the work-in mechanism, handled in its own spec. Admitting in writing that short appointments waste minutes looks like weakness and is the opposite. For a human, that is what gives the record credibility: nobody trusts a decision with no cost. For a model, that is direct ammunition against Tuesday’s proposal: the gain the agent “discovered” was already counted as an accepted cost, and the ADR says what the clinic gets in exchange. Better still, the fourth consequence defines the condition for revision. If one day the clinic offers long procedures, the decision no longer holds, and the document itself says what comes next: a new ADR that supersedes this one, never an edit to what was accepted. ADRs are immutable like commits; the status field in the header (proposed, accepted, superseded by ADR-N) carries the history, and the sequence of ADRs forms the timeline of the system’s decisions, readable from the first to the last. Now redo Tuesday with the file docs/adr/001-fixed-intervals.md in the repository. The agent that combs the project before it analyzes the architecture finds the ADR the same way it found the living doc in chapter 9, and the analysis changes in kind. Instead of “fixed intervals are rigid, I propose a free-form schedule,” something like “the fixed-interval decision (ADR-001) assumes appointments of similar duration and an audit by appointment; if those premises still hold, the decision still holds.” The proposal to undo it was not ruled out by a prohibition, but by context: the model is now responding to a decision whose motivation is in the window, and proposing a reversal requires attacking the premises, not just pointing to the rigidity. It is the difference between a consultant on their first day and one who has read the meeting minutes.
“ADRs are bureaucracy” The objection comes fast when you propose this to the team, and it comes from somebody who has already been burned by process: one more mandatory document, one more template to fill out, one more step between the decision and the code. Two answers. The first is about size and frequency. ADR-001 in full runs under a page, and the template I use in VilaSchedule fits in twenty lines of instruction; writing it costs minutes, on the day of the decision, while the context is fresh and free. And it is not one document per feature, nor per sprint: it is one per architecture decision, the ones with a real cost of reversal, which in a typical team show up a few times per quarter. ThoughtWorks recommended the practice in the 2017 Technology Radar under the name “Lightweight Architecture Decision Records” (thoughtworks.com/radar) and drew exactly that line: plain text, in the repository, with no new tool and no committee. The adjective “lightweight” is in the title because the heavy version, the fifty-page architecture document approved in committee, is the bureaucracy the objection rightly fears. The ADR is what was left after cutting that bureaucracy down to the minimum that still preserves the why. The community templates at adr.github.io show variations, and all of them fit on a page. The second answer is the math of not writing one. The ADR’s cost is visible and small: minutes of writing today. The cost of its absence is invisible and compounding: the archaeology meeting when somebody asks, the decision undone by whoever did not know, and now, with agents in the cycle, every analysis session that runs into the same “rigidity” and proposes the same reversal all over again, burning the tokens chapter 6 taught you to count, only to botch the reconstruction of a rationale ten lines would have recorded. Bureaucracy is a document nobody reads
protecting a process nobody defends. The agent read ADR-001 in the very first session after it was written, and it changed the output. A document with a reader and an effect has another name: context. Three artifacts, three questions With this chapter, the division of labor Part II has been assembling closes a triangle. “What we are going to build and under what rules” is the spec, a dated record of intent, chapter 8. “What is true in the system today” is the living doc, verified against the source, chapter 9. “Why the system is this way and not another” is the ADR, immutable like the decision it records. In VilaSchedule, the three cite each other without duplicating each other: the living doc points to the ADR for the why behind the rules, in its “what this document does not cover” section; the ADR points to the work-in spec; and none of the three runs over a page. When a piece of information lands on your desk, those three questions say where it lives; if it answers none of them, maybe it does not deserve an artifact. But the three artifacts share one trait: they record decisions big enough for somebody to have stopped and decided. A good deal of what makes code predictable never went through a decision at all. camelCase or snake_case for variable names, tests next to the file or in a folder of their own, migrations written by hand or generated, commit messages in one format or another: rules the team follows without thinking, that nobody decided in a meeting and that for that reason have no spec, no doc and no ADR. You do not notice them until you see a pull request that violates all of them at once, written by somebody who never read them anywhere, because they were never written down. In 2026, that somebody is usually an agent. What to do with the invisible rules is the next chapter.