DESIGN.md: the file after AGENTS.md

Matt Connor, chief executive of the hosting company SSD Nodes, proposes a DESIGN.md file that records settled decisions so that coding agents stop undoing them.

Matt Connor founded and runs SSD Nodes, a company that rents virtual private servers. He describes coding agents that replace patterns they do not recognise, such as a hand-written cache, while the tests still pass. His answer is a short file at the root of the code repository that records what must stay true and why.

• The file lists the rules that must stay true, each with its reason, and the rejected alternatives with conditions for revisiting them. It also lists high-risk boundaries, such as schemas and deploy settings, and a vocabulary mapping code terms to business terms.
• AGENTS.md tells an AI agent how to work in a repository, while DESIGN.md tells it why the code is shaped as it is.
• Connor advises updating the file in the same commit that changes a decision, and adding a line only when an agent makes a mistake that one sentence would have prevented.
• He advises testing the file by giving the agent a task that touches a protected rule and checking whether the agent cites it.

A team can make the person who changes a settled decision responsible for recording it in the same commit. Connor names no owner for the file, so who approves changes to it remains open; that observation is an inference.

Derived by Working Surface from the article; more in the Playbook. Source line: DESIGN.md tells it why the code is shaped that way, so it stops undoing your decisions.

11 October 2026: AI agents depend on written context that goes stale, and the teams in these pieces review agent changes more firmly than they keep that context current.