Kleio vs ADRs in Git
ADRs are great.
The friction means most decisions never get captured.
Architecture Decision Records work for deliberate, high-stakes decisions. But most engineering decisions are too small for a formal ADR and too important to lose.
Where ADRs in Git work well
- Version-controlled alongside code — decisions live where the code lives.
- Established formats (MADR, Nygard) provide consistent structure.
- Great for intentional, high-stakes architecture decisions that deserve ceremony.
- Searchable via grep within the repository.
- Open-source tooling (adr-tools, log4brains) with community support.
Where ADRs break down
- High friction — someone has to stop, open a file, pick a template, and write. Most decision context never gets captured.
- Only captures deliberate Big Decisions. The daily micro-decisions that shape the codebase are missed entirely.
- Goes stale quickly — the ADR says one thing, the code evolved differently, nobody updated it.
- No queryability beyond grep. You can't ask "what did we decide about auth?" and get a synthesized answer.
- Non-technical stakeholders can't access or search decisions locked in a Git repo.
- AI agents don't write ADRs. In AI-assisted workflows, decision context vanishes with the session.
How Kleio is different
- Zero-friction capture via MCP — decisions are captured inline as you work, no template ceremony required.
- Captures the full spectrum: from architecture calls to micro-decisions made mid-session.
- Queryable via kleio_ask — ask questions in natural language and get answers grounded in your decision history.
- ADR import path lets you bootstrap with existing ADRs, then add the living layer they miss.
- Signal links connect decisions to the PRs, commits, and checkpoints that implemented them.
- Accessible via web app — non-technical stakeholders can review decisions without repo access.
See it in action
An agent plans a migration. Kleio captures every signal along the way.
Agent Plan
Task: Migrate auth from Firebase to Clerk
- 1.Scaffold Clerk provider and session hooks
- 2.Replace Firebase login/signup flows
- 3.Update API middleware for Clerk JWT validation
Press Build to run the capture demo.
Your AI agents already make decisions. Kleio makes sure they're remembered. Try it free →
Side-by-side
| Capability | ADRs in Git | Kleio |
|---|---|---|
| Capture friction | High (manual) | Zero (automatic) |
| Decision spectrum | Big-A Architecture only | Full spectrum |
| Queryable (NL) | ||
| Linked to code changes | Manual references | Automatic signal links |
| Survives squash/rebase | ||
| Non-technical access | ||
| AI agent compatible | ||
| Staleness risk | High | Low |
Better together or full replacement?
Complementary. Kleio can import your existing ADRs and add the living layer that formal ADRs miss. Keep ADRs for the 5% of decisions that deserve full ceremony. Let Kleio capture the other 95% automatically.
Related comparisons
Ready to try Kleio?
Start free, connect your workspace, and stop losing the \u201cwhy.\u201d