Matt Pocock shows how a good ADR prevents agents from making wrong assumptions

mattpocockuk · x · 2026-11-21

Matt Pocock shares an ADR titled "A Thumbnail Diagram is not a Diagram", born from a long grilling-session battle over naming and data relationships. The ADR documents keeping Thumbnail and Diagram models separate: a Thumbnail owns its own Thumbnail Diagram (a tldraw document) with no snapshots and no Playground Home presence; shapes copied into it record their source with content-hash dedup so later merges stay cheap; the face belongs to the Thumbnail, thumbnails are archived never hard-deleted, and clipboard-pasted shapes deliberately record no source. His point: imagine what assumptions an AI coding agent would make if this ADR didn't exist — good ADRs matter for agents.

Original post →

More from coding & agent

coding & agent channel →