Lockstep vs ADR files
ADRs are the right instinct (write decisions down) with the wrong reader: a markdown file can't brief an AI agent or stop a conflicting merge. Lockstep is the ADR promise made operational: decisions captured automatically, approved by owners, delivered to every engineer and agent, and enforced at the PR.
What ADR files is good at
ADRs in the repo are a great, version-controlled way to record why an architectural choice was made.
Where Lockstep is different
ADRs still rely on someone writing them, and nothing feeds them to an AI agent before it codes. Lockstep captures decisions automatically wherever they happen, gets one-click approval, briefs every agent via MCP, and catches drift before merge.
ADR files vs Lockstep at a glance
| ADR files | Lockstep | |
|---|---|---|
| Authoring | An engineer writes the ADR by hand, after the fact | Captured automatically from Slack, PRDs, tickets, and PRs |
| Coverage | Architecture decisions someone bothered to file | Product and engineering decisions across allowlisted sources |
| Delivery | Sits in the repo; read if someone looks | Briefed to every engineer and agent before they touch the code |
| Enforcement | None | PR check flags changes that collide with approved decisions |
| Cost to maintain | Discipline; the log dies when filing stops | No filing; owners approve with one click |
When to use each
They aren't mutually exclusive. Keep ADR files for architecture decision records; add Lockstep as the layer that captures the decisions automatically, gets them approved, and enforces them against both engineers and AI coding agents. See the full pipeline.
Frequently asked questions
- Should we stop writing ADRs if we use Lockstep?
- Not necessarily. ADRs remain a good long-form record of why a hard architectural call was made. Lockstep captures the decision itself, keeps it enforced, and links back to the ADR as the source; the two compose.
- When are plain ADR files the better choice?
- For a small team with strong writing discipline, few repos, and no AI agents in the loop, a well-kept ADR log in the repo is free and version-controlled. The approach breaks down when filing discipline fades or agents need the context mid-session.
- Why can't an AI agent just read our ADR folder?
- It can, if it knows to, if the ADRs are current, and if the relevant one fits in context. In practice ADR logs are incomplete and stale, and nothing checks the agent's output against them. Lockstep ranks approved decisions by the surface being touched and enforces them at the PR.
More comparisons