<- all tokdocs

Dated Design Decisions for Coding Agents: The ADR Practice Behind It

By , founder of Mavric and Apso

View on TikTok ->

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 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 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", 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 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 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), 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 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

Published October 7, 2026. Based on a TikTok by @breakingagents. Full video notes (markdown)