@mattpocockuk: Writing ADR's for agents has been such a good decision Capturing all the non-obvious decisions in a codebase makes ever…
Summary
Matt Pocock recommends writing Architecture Decision Records (ADRs) for agents to capture non-obvious decisions, making agents in the stack smarter with minimal documentation.
View Cached Full Text
Cached at: 05/30/26, 04:03 AM
Writing ADR’s for agents has been such a good decision
Capturing all the non-obvious decisions in a codebase makes every agent in your stack that touches the stack smarter
It’s the thinnest layer of docs that captures the stuff code can’t
Similar Articles
@mattpocockuk: Another layer of documentation I'm considering (along with CONTEXT.md and ADR's) is a list of all the agreed test seams…
Matt Pocock proposes documenting agreed test seams in apps, arguing that AI agents cannot be trusted to make good testing decisions, often leading to fragile tests that break on implementation changes.
@bibryam: Using Agents, Keeping Agency. https://devindickerson.dev/posts/using-agents-keeping-agency/…
A blog post warns that AI coding agents often default to popular but unsuitable technologies, incurring technical debt, and urges developers to retain agency in architectural decisions.
@kentcdodds: Agents write code. @rasmic says old engineering books help you steer them better.
Kent C. Dodds shares Rasmic's insight that old engineering books can help steer AI agents that write code.
@elldeeone: Have been using @mattpocockuk's /improve-codebase-architecture skill now for a couple of months and it's amazing. I don…
Matt Pocock's repository of agent skills for coding assistants improves codebase architecture and developer alignment.
AI agents recreate the “rockstar developer” problem, just faster
The post compares AI agents to 'rockstar developers' who create clever but unmaintainable code, pointing out that agents lack memory of their own actions. It recommends using visible conventions like AGENTS.md, ADRs, and tests to keep agent-generated code understandable by the team.