Better with Kent · draft

Turn your agent on auto-pilot

with ADRs

Hook

The agent asked again

You already answered that last week

Why it's useful

Decisions die in chat

  • You decide in a thread
  • The thread is gone
  • You become the memory

Why it's useful

Next agent starts from zero

  • No inherited product memory
  • Same question · new chat
  • Or it invents a new surface

So

Write them down

If it isn't in the repo, it didn't happen

What it is

A short record of a decision

Already made · not a design doc in progress

Nygard's ADR post

Anatomy

Context · decision · consequences

Why now → What we chose → Revisit if

Half a page. Kody template

How it solves it

Agents inherit the repo

AGENTS.md → docs/decisions/ → Check first

One line: don't propose what we already decided against

Start here

Write the nos you keep repeating

  • Product-shaped · not “we use TypeScript”
  • “We will not build X”
  • Revisit if Y

Good

What a good ADR looks like

  • A no you would otherwise re-argue
  • Half a page · one open
  • Linked from AGENTS.md

Receipts

Agents changed the answer

Opened the nos · kept the primitive

Missing no

Without a file, they re-litigate

Write the no before the next agent

Ten seconds

Don't write these

  • Essays nobody opens
  • UI diaries that last a week
  • An ADR on every PR

Epic Stack essays · 0010 · 0028

Homework

Start this week

Sample: adr-template.md

Template

# 0001: We will not build X

## Context
The question that keeps coming back.

## Decision
We will not build X. Revisit if Y.

## Consequences
Next agent proposes the existing path.

Full template

Better with Kent

Turn your agent on auto-pilot

Write the first ADR you already made

Like · comment · subscribe · get better with me