Last week my former colleague Doug Todd asked a question about recording decisions on BlueSky:

Of course I replied suggesting Architecture Decision Records (ADRs), with a pointer to the at_protocol GitHub repo where we use them.

A few days back Doug demoed how he’s using ADRs with his coding assistant (Claude and Claude Code), and I feel like this is going to transform the uptake of the approach. It’s such an obviously good way to provide context to a coding assistant – enough structure to ensure key points are addressed, but in natural language, which is perfect for things based on Large Language Models (LLMs).

ADRs right now might be an ‘elite’ team thing (in DORA speak), but I can see them becoming part of a boilerplate approach to working with AI coding assistants. That probably becomes more important as we shift to agent swarm approaches[1], where you’re effectively managing a team, which (back in the human world) is exactly the sort of environment that ADRs were created for.

Note

[1] It feels like my LinkedIn feed these days is 10% stuff from rUv where friends are commenting on his adventures with agent swarms using ‘claude-flow‘. I’ve been intruiged by Adrian Cockcroft’s comments that working with swarms is more like managing a team (than being an individual contributor), and that the code produced might be as important as the bytecode or machine language that we get compilers (e.g. something that we approximately never actually need to look at).