Chapter 18: The proof

Decision records as evidence

A short dated note of a decision: what you chose, what you rejected, and why. As evidence, it shows a person made a call the agent couldn't make alone, and it lets someone ask you about it a year later.

An agent will happily produce options and has nothing riding on the outcome. Choosing between them is the job that stays yours. Be careful with these, though: an agent can write twenty backdated ones in a minute, and they fall apart the moment someone asks what you would do differently now.

Say it to your agent

“Write docs/adr/0004-queue-choice.md in Nygard's format: context, decision, status, consequences. List the two options I rejected and my reasons, in my words from this conversation. Date it today. If you don't know a reason, ask me, and don't invent one.”

The workshop

Name a word, or describe what you mean in everyday language.