---
title: "Dated Design Decisions for Coding Agents: The ADR Practice Behind It"
date: "2026-10-07"
video_id: "7693960135151996173"
tiktok_url: "https://www.tiktok.com/@breakingagents/video/7693960135151996173"
creator: "@breakingagents"
category: "Coding"
tags: ["architecture decision records", "adr-tools", "madr", "claude code", "design docs"]
excerpt: "Writing a decision, a reason and a date for each design rule is Architecture Decision Record practice. Here is where the date came from and what it can't fix."
---
Writing every design decision as a decision, a reason and a date is Architecture Decision Record (ADR) practice. The date field was added by tooling: Nat Pryce's adr-tools has stamped an ISO 8601 `Date:` on every record since 2016. The habit helps stop a coding agent from reopening settled questions, but the 1985 paper the video cites argues that documents alone cannot carry a program's design.

## What the video recommends

A TikTok from @breakingagents describes a Mac menu-bar app built with coding agents. Each new agent session starts empty, sees an orange dot, and proposes "make it red," even though that choice was settled days earlier. The fix shown is a `docs/DESIGN.md` file where each line has three parts: the decision, the reason and the date. The example on screen reads `09-16  Red only at 90% disk`, and the file lists thirteen dated lines.

The auto-generated transcript renders this rule as "Read only when the disk is full." The on-screen cards settle it: the rule reserves the color red for a disk that is 90% full. It has nothing to do with read-only mode.

## Where architecture decision records come from

Michael Nygard published [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) on 15 November 2011. He opens with "One of the hardest things to track during the life of a project is the motivation behind certain decisions." His template has five sections: Title, Status, Context, Decision and Consequences. It has no date field.

## When did ADRs get a date field?

The date arrived through adr-tools. Its shipped [`template.md`](https://github.com/npryce/adr-tools/blob/master/src/template.md) puts `Date: DATE` on the second line, and the `adr-new` script fills it in with `date=${ADR_DATE:-$(date +%Y-%m-%d)}`. The repo's own ADR 0001 is dated 2016-02-12.

Its [ADR 0008, "Use ISO 8601 Format for Dates"](https://github.com/npryce/adr-tools/blob/master/doc/adr/0008-use-iso-8601-format-for-dates.md), dated 2017-02-21, gives the reason: "An important component of the history is the time at which a decision was made." The `2026-09-16` format in the video is the same ISO 8601 choice.

Joel Parker Henderson's [ADR collection](https://github.com/joelparkerhenderson/architecture-decision-record) states the general rule in its README: "Timestamps: Identify when each item in the ADR is written. This is especially important for aspects that may change over time, such as costs, schedules, scaling, and the like."

## MADR's date means something different

[MADR](https://adr.github.io/madr/) reached version 4.0.0 on 17 September 2024. Its template lists an optional `date: {YYYY-MM-DD when the decision was last updated}`. That records the last update. The video's date records when the decision was first made, which is the version that stops an agent from relitigating it.

## What Naur's 1985 paper actually says

The video quotes "Peter Naur. Programming is theory building," and a card reads "A PROGRAM IS THE THEORY IN ITS BUILDERS' HEADS." The paper's title is "Programming as Theory Building" (a [reprint is hosted at gwern.net](https://gwern.net/doc/cs/algorithm/1985-naur.pdf)), and the card line is a paraphrase. Naur's own sentence is that "an essential part of any program, the theory of it, is something that could not conceivably be expressed, but is inextricably bound to human beings." He borrows the word "theory" from Gilbert Ryle's *The Concept of Mind*.

Naur ties a program's death to the whole team, not one person leaving: "The death of a program happens when the programmer team possessing its theory is dissolved."

His conclusion also cuts against the video's fix. He writes that "program revival, that is reestablishing the theory of a program merely from the documentation, is strictly impossible," and that a new programmer needs "the opportunity to work in close contact with the programmers who already possess the theory." A dated line in `DESIGN.md` is a cheap guard against one specific failure, an agent reopening a settled question. Naur would not call it a way to carry the theory.

## Do coding agents remember past sessions?

No. Anthropic's [Claude Code memory documentation](https://code.claude.com/docs/en/memory) opens with "Each Claude Code session begins with a fresh context window." It names CLAUDE.md files and auto memory as the two ways knowledge carries over.

The same page adds a caveat the video skips: "Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead." A dated rule makes it more likely the agent leaves the decision alone. For decisions that are expensive to reopen, Anthropic points to a hook.

## What could not be checked

The speaker's claims to be a staff engineer and to have built two apps with coding agents this year have no public artifact behind them. The `DESIGN.md` screen is a stylized graphic, and the app is not named. Treat those details as unverified.

## Bottom line

Dating each decision with a reason is established ADR practice, and adr-tools has automated the date since 2016. It is a useful guard against agents reopening settled choices. It does not solve the problem Naur described, and for rules that must hold, Anthropic recommends a PreToolUse hook over a markdown line.

## Sources

- [Documenting Architecture Decisions, Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions): the 2011 origin of ADRs and the five-section template.
- [adr-tools `src/template.md`](https://github.com/npryce/adr-tools/blob/master/src/template.md): the template with `Date: DATE` under the title.
- [adr-tools ADR 0008](https://github.com/npryce/adr-tools/blob/master/doc/adr/0008-use-iso-8601-format-for-dates.md): the 2017 rationale for ISO 8601 dates.
- [MADR template](https://adr.github.io/madr/): the optional last-updated `date` field.
- [joelparkerhenderson/architecture-decision-record](https://github.com/joelparkerhenderson/architecture-decision-record): the "Timestamps" guidance.
- [Naur, Programming as Theory Building (reprint PDF)](https://gwern.net/doc/cs/algorithm/1985-naur.pdf): the paper's title, definitions and conclusion.
- [Claude Code memory documentation](https://code.claude.com/docs/en/memory): fresh context per session and the PreToolUse hook caveat.
- [Source video](https://www.tiktok.com/@breakingagents/video/7693960135151996173): the TikTok from @breakingagents.


## Video description and verification notes

**The clip runs 109.269 seconds at 720x1280 (9:16, 30 fps) in an MP4/QuickTime container, carrying HEVC video (hvc1 tag, Main profile, level 120, yuv420p, 241,597 bps, 3,276 frames) and HE-AACv2 audio (44.1 kHz stereo, 48,083 bps, 2,357 frames), for an overall 296,225 bps and a 4,046,027-byte file, pulled as yt-dlp format `bytevc1_720p_296222-1`. All container and codec values come from `ffprobe` on the downloaded `video.mp4`. TikTok's metadata puts the post at 2026-10-07 16:15:18 UTC from uploader `breakingagents`, channel nickname "Breaking Agents", with audio credited to "original sound - Breaking Agents" and a 324-character description. At capture on 2026-10-08 the counters read 588 views, 25 likes, 1 comment, 3 reposts, and 11 saves, roughly thirteen hours after posting. I read the full 255-word transcript and 23 of the 55 extracted frames (frames 1, 4, 8, 12, 16, 19, 22, 25, 28, 31, 34, 36, 37, 40, 42, 43, 44, 45, 46, 50, 52, 53, 55, sampled evenly across the 2-second grid). The visuals alternate between a talking-head shot and a graph-paper title card. The speaker sits at a desk in front of two monitors, holding an orange RØDE foam-capped handheld mic, wearing a plain black tee. The left monitor shows a dark marketing page reading "Understand how to run any repository." with an orange accent button; I could not identify that product from a web search and leave it unnamed. Burned-in captions track the audio one phrase at a time ("let's talk about", "UI decisions", "that's the one", "change it"). The card overlays are monospaced and build line by line: "MY DESIGN DOC HAS DATES." over a blue-boxed `decided 2026-09-16`; "A MAC MENU-BAR APP" over a drawn menu bar reading `10:24` with an orange dot appearing on the active icon and the label "something to do"; "NEXT SESSION · EMPTY" filling in `sees  orange dot`, `proposes  "make it red"`, `decided  × 2 days ago`; "EVERY DECISION · 3 PARTS" filling in `decision  red only`, `reason  disk 90% full`, `date  2026-09-16`; a file listing headed `docs/DESIGN.md    13 decided` with thirteen dated one-liners from `09-12 Name 3 risk levels` to `09-23 Design for light mode`, with `09-16 Red only at 90% disk` boxed in blue; "WHY THE DATE WORKS / 1985"; a "NAUR, 1985" card building to "A PROGRAM IS THE THEORY IN ITS BUILDERS' HEADS. / THE CODE ALONE CAN'T CARRY IT."; "WITH AGENTS, A BUILDER LEAVES EVERY SESSION. / THE DATE STAYS."; and a closing "YOUR RULES FILE" card reading `one rule  × no date  × no reason  → that's the one`. An orange "+ Follow" pill appears over the talking head near frame 46.**

## The auto-transcript mangles the one rule the whole video is built around

Whisper renders the example rule as "Read only when the disk is full. Decided September 16." The on-screen text settles it three different ways. The "EVERY DECISION · 3 PARTS" card reads `decision  red only` and `reason  disk 90% full`. The `docs/DESIGN.md` listing reads `09-16  Red only at 90% disk`. The rule is about reserving the color red for a 90-percent-full disk, not about read-only mode. Anyone quoting this clip from a transcript alone will get the example backwards.

## Nygard's original 2011 ADR template has no date field, and the video's format is closer to adr-tools than to the canonical template

The video presents "decision, reason, date" as a personal discovery. The practice has a documented lineage with a specific order. Michael Nygard published [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) on 15 November 2011, opening with "One of the hardest things to track during the life of a project is the motivation behind certain decisions." His template is Title, Status, Context, Decision, Consequences. It has no date field. The date arrived through tooling. Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools) ships a [`template.md`](https://github.com/npryce/adr-tools/blob/master/src/template.md) whose second line is literally `Date: DATE`, and `src/adr-new` fills it with `date=${ADR_DATE:-$(date +%Y-%m-%d)}`. That repo's own ADR 0001 is dated 2016-02-12, and [ADR 0008, "Use ISO 8601 Format for Dates"](https://github.com/npryce/adr-tools/blob/master/doc/adr/0008-use-iso-8601-format-for-dates.md), dated 2017-02-21, states the reasoning directly: "An important component of the history is the time at which a decision was made." The video's `2026-09-16` and `09-16` are that same ISO 8601 choice.

The community standard caught up later. [MADR](https://adr.github.io/madr/) reached 4.0.0 on 17 September 2024 (release date read from the GitHub API on `adr/madr`), and its template front matter lists `date: {YYYY-MM-DD when the decision was last updated}` as an optional field. Note the divergence. MADR's date records when the decision was last updated. The video's date records when the decision was originally made. Those answer different questions, and the video's version is the one that stops re-litigation. Joel Parker Henderson's widely used [ADR collection](https://github.com/joelparkerhenderson/architecture-decision-record) states the general rule in its README: "Timestamps: Identify when each item in the ADR is written. This is especially important for aspects that may change over time, such as costs, schedules, scaling, and the like."

## Naur's 1985 paper is titled "Programming as Theory Building," and his own conclusion argues against the video's remedy

The video says "Peter Naur. Programming is theory building," and the card reads "A PROGRAM IS THE THEORY IN ITS BUILDERS' HEADS." Reading the paper itself (via the [reprint hosted at gwern.net](https://gwern.net/doc/cs/algorithm/1985-naur.pdf), introduced there as written in 1985 and reprinted in Naur's collection *Computing: A Human Activity*, 1992), the title is "Programming as Theory Building," and the builders'-heads line is a paraphrase rather than a quotation. Naur's actual sentence is that "an essential part of any program, the theory of it, is something that could not conceivably be expressed, but is inextricably bound to human beings." He borrows the word "theory" from Gilbert Ryle's *The Concept of Mind*, defining what a programmer possesses as "a theory of how certain affairs of the world will be handled by, or supported by, a computer program."

The video's "when the builders leave, the theory dies" compresses a more specific claim. Naur writes: "The death of a program happens when the programmer team possessing its theory is dissolved." Death is dissolution of the team, not the departure of one person, and Naur adds that "a dead program may continue to be used for execution in a computer and to produce useful results."

The sharper problem is that Naur's conclusion points the other way from the video's fix. He writes that "program revival, that is reestablishing the theory of a program merely from the documentation, is strictly impossible," and that a new programmer needs "the opportunity to work in close contact with the programmers who already possess the theory." The paper argues that a document cannot carry the theory. The video cites the paper as support for a document that carries the theory. The dated line in `docs/DESIGN.md` is better described as a cheap guard against one specific failure, which is an agent re-opening a settled question, than as a solution to the problem Naur named.

## The empty-context premise checks out against Anthropic's own docs, and explains why the file alone is not enough

The video's premise is that each agent session starts with no memory of the last one. Anthropic's [Claude Code memory documentation](https://code.claude.com/docs/en/memory) states it in the first line: "Each Claude Code session begins with a fresh context window. Two mechanisms carry knowledge across sessions: CLAUDE.md files ... [and] Auto memory." The same page adds the caveat the video does not mention: "Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead." A dated rule raises the odds the agent drops the argument. It does not guarantee it. For decisions where re-opening the question is actually expensive, the first-party guidance points at a hook rather than a line in a markdown file.

## Several of the video's supporting claims cannot be checked

"I'm a staff software engineer," "I have built two applications with coding agents this year," and "20 minutes of going back and forth in the prompt" are first-person claims with no public artifact behind them. The `docs/DESIGN.md` screen is a stylized graphic rather than a screen recording of a real file, so the "13 decided" count is consistent with the spoken "thirteen of those lines so far" and with the thirteen rows visible on the card, and nothing more. The underlying menu-bar app is not named and I found no repository for it. Treat all of these as unverified.

## Key Takeaways

- **Verified:** Michael Nygard published "Documenting Architecture Decisions" on 15 November 2011, and his template is Title, Status, Context, Decision, Consequences, with no date field.
- **Verified:** adr-tools stamps an ISO 8601 `Date:` automatically via `date=${ADR_DATE:-$(date +%Y-%m-%d)}`, and its ADR 0008 of 2017-02-21 records the reason as "An important component of the history is the time at which a decision was made."
- **Verified:** Anthropic's own documentation states "Each Claude Code session begins with a fresh context window," which supports the video's empty-context premise.
- **Correction:** The auto-transcript's "Read only when the disk is full" is wrong. The on-screen text reads `red only`, `disk 90% full`, and `09-16 Red only at 90% disk`.
- **Correction:** The paper is "Programming as Theory Building," not "Programming is theory building." The card's "A program is the theory in its builders' heads" is a paraphrase. Naur wrote that the theory "could not conceivably be expressed, but is inextricably bound to human beings."
- **Partial correction:** Naur's death condition is team dissolution, not a single builder leaving, and his conclusion that "program revival ... merely from the documentation, is strictly impossible" cuts against using a dated design doc as the remedy he would endorse.
- **Clarification:** MADR 4.0.0 (17 September 2024) does include an optional `date`, but it is defined as "when the decision was last updated," which is not the same field the video is describing.
- **Context:** Anthropic's memory page notes CLAUDE.md is "context, not enforced configuration," and points at a PreToolUse hook when a decision must actually be enforced.
- **Context:** The video is small at capture, with 588 views and 25 likes about thirteen hours after posting, so engagement is not evidence the practice is widespread.

## Resources

- [Documenting Architecture Decisions, Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) establishes the 15 November 2011 origin of ADRs and the five-section template with no date field.
- [adr-tools `src/template.md`](https://github.com/npryce/adr-tools/blob/master/src/template.md) establishes that the shipped ADR template puts `Date: DATE` directly under the title.
- [adr-tools ADR 0008, Use ISO 8601 Format for Dates](https://github.com/npryce/adr-tools/blob/master/doc/adr/0008-use-iso-8601-format-for-dates.md) establishes the 2017-02-21 rationale for dating decisions in ISO 8601.
- [MADR template](https://adr.github.io/madr/) establishes that the current community template treats `date` as optional and defines it as the last-updated date.
- [joelparkerhenderson/architecture-decision-record](https://github.com/joelparkerhenderson/architecture-decision-record) establishes the "Timestamps" guidance for ADR quality.
- [Naur, Programming as Theory Building (1985 paper, reprint PDF)](https://gwern.net/doc/cs/algorithm/1985-naur.pdf) establishes the exact title, the Ryle-derived definition of theory, the program death and revival passage, and the "strictly impossible" claim about rebuilding theory from documentation.
- [Claude Code memory documentation](https://code.claude.com/docs/en/memory) establishes that every session starts with a fresh context window and that memory files are context rather than enforced configuration.
- [Source video](https://www.tiktok.com/@breakingagents/video/7693960135151996173) establishes the on-screen text, the thirteen dated lines, and the engagement figures quoted above.
