Open any article about agent workflows these days and you'll hit the same advice: put a DESIGN.md in your repo as context for the model. I believed it and wrote one seriously for a month. Verdict first: mostly useless — unless you write it right.

1. How it turns into waste paper

Week one, I wrote it devoutly: project structure, each directory's responsibility, how modules call each other, diagrams and all.

Week two, two features shipped and the doc started drifting from reality.

Week three, the truly surreal part: the agent began playing multiple choice between "the doc says A" and "the code says B." Sometimes it trusted the doc and wrote against a structure that didn't exist. Sometimes it trusted the code and treated the doc as air. Either way, the doc lost every single round.

A month in, I got it: any doc that describes "what it is" is doomed. The code itself is the most accurate description of "what it is," and today's models read code faster than you and understand it better than you did. Writing a manual to compete with the code is fighting someone's strength with your weakness.

2. What the surviving version looks like

The version that survives only writes what the code cannot show:

  • Why option X was rejected back then (leave it out, and the agent will enthusiastically reinvent it for you six months later);
  • Which things are invariants where touching them detonates something ("en.ts is the canonical shape of the dictionaries; zh.ts keys must stay in sync");
  • Historical baggage and minefields ("don't touch this function; upstream bug").

Notice: all three are constraints. Not one is a description.

This very blog's AGENTS.md is a live example: the useful lines are the "must" and "don't" ones, not the project-structure intro up top — the structure the agent figures out by glancing at the directory anyway.

And length: one screen is the cap. A DESIGN.md longer than a screen is, functionally, a decoration nobody finishes reading.

3. How to keep it fresh

Humans shouldn't maintain docs; humans should maintain judgment. Two methods that actually work:

One, let the agent tend it itself: have it rewrite the page at the end of each task — it just finished groping through the code anyway. Two, generate on demand: before starting work, have the agent read the code and write a fresh one, then throw it away. Expiry problem solved by construction.

4. Closing

So is DESIGN.md useful? Yes — but only when it speaks plainly, states constraints, and stays forever fresh.

Its best form is a page of taboos, not a manual. The code is already a manual. Don't write a second one.