liveBook · Manning

Architecture decision record

As explained in Claude at Work

An architecture decision record is a document that captures a significant software architecture decision, its rationale, consequences, and alternatives.

An architecture decision record (ADR) is a short, structured document that records a significant technical decision and why it was made. It preserves the reasoning, trade-offs, and alternatives so the decision remains understandable later. section 4.3

A practical ADR can capture:

Switching from .NET to Python

An ADR can record the choice to use Python because the team is comfortable with both languages, expects quicker development, and has more experience with Python in Claude Code. The record can also spell out consequences and alternatives. section 4.5

A focused custom skill can turn decision points into repeatable ADRs, for example saving them under docs/adr/{yymmdd}-{title}.md. Review the result: request clarification when needed, and consider whether more research or a challenge to the proposed decision would improve the record. section 4.4 section 4.5

How Claude at Work covers it

How deep it goes
Defines a concise record structure and demonstrates generation, but leaves deeper decision research and challenge as possible extensions.
Examples
Uses Redis Streams over Kafka and a switch from .NET to Python as decision examples.
What it assumes
Provide a decision and its reasoning; clarify missing details when needed.
What you can do after
Apply the adr-writer skill to generate an ADR in a project’s docs/adr directory.
How it connects
Links technical decisions to rationale, consequences, and alternatives.

Also explained in

Compare how 7 books explain architecture decision record →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Claude at Work. The section links point to the parts of the book it draws on.