adr-generator
A Claude skill that retroactively generates MADR architectural decision records from git history and annotates code with inline @ADR tags — so coding agents know *why* a codebase looks the way it does.
The problem
Coding agents work great on greenfield projects. On existing codebases, they're flying blind. They see what the code does, not why it looks the way it does. Why Redis here instead of Postgres? Why is this service async? Why did the team move away from REST?
That context lives in the heads of engineers who wrote the code, or buried in PRs nobody reads. New developers ramp up slowly. Agents make decisions that contradict ones already made.
ADRs solve this — but nobody writes them retroactively by hand for a three-year-old codebase.
What I built
A Claude skill that reads a repo's git history, detects architectural decisions, generates a MADR file per decision, and places @ADR inline tags on the relevant functions and classes. A coding agent can now grep -r "@ADR" and surface every architectural decision site in the codebase.
How
Git history analysis
Reads commit-by-commit, detects workflow type (merge, squash, rebase/linear, mixed), groups commits into logical decision chunks.
Cross-PR clustering
Clusters related chunks across PR boundaries — one decision spread over several PRs becomes a single ADR, not three redundant ones.
Hallucination guardrails
Considered Options only lists alternatives evidenced in the diff. Rationale is drawn from commit messages, not inferred. If unclear, the MADR says so.
Deterministic verification
judge.py re-checks citations via exact SHA + file-change lookups — no LLM on the verification path. Fabricated options are dropped.
Inline @ADR tags
Tags placed directly on affected functions and classes so agents find the decision log at the code it changed.
Three run modes
Quick (default for <500 commits), Autonomous (full loop, large repos), and Assisted (pauses at each step for human review).
Output
MADR files written to docs/decisions/ — each with context, considered options (citation-grounded), outcome, and links back to original commits. Code gets @ADR inline tags at every affected site:
# @ADR-0002-async-event-queue: switched from sync to async event processing — see docs/decisions/0002-async-event-queue.md
async def process_events(self, batch: list[Event]) -> None:Pass --json to analyze.py for machine-readable candidates — each entry includes score, classification, and a diff_summary so the agent can triage without running git diff manually.
Where it landed
Built as a Claude skill — install is a single cp -r into ~/.claude/skills/. The only runtime dependency is Python 3 stdlib; no pip install needed. Ships with a deterministic citation verifier (judge.py) that catches hallucinated options before they land in the docs.