adr-kit
Architecture decisions your AI coding agents actually follow.
adr-kit turns Architecture Decision Records from passive documentation into active guardrails. Your agent gets the relevant decisions injected while it codes, every commit is checked against the accepted decisions, and a guardian watches for decisions that go stale. One toolkit covers the whole lifecycle: capture, enforce, maintain, retire.
Works as a Claude Code plugin and as plain files for Cursor, GitHub Copilot, OpenAI Codex CLI, Claude Cowork, and any agent that supports the Agent Skills format. The engines are dependency-free Python 3.9+ (stdlib only, no build step, no API key required for any default path).
Pre-1.0: functional and in daily use, but conventions may still evolve before v1.0.0. Pin a tag if you need stability across upgrades.
Why
AI coding agents are fast, confident, and have no memory of why your system is built the way it is. Left alone, they will cheerfully reintroduce the database driver you migrated away from, bypass the repository layer you standardized on, and make new architectural decisions without telling anyone. Human teams have the same failure mode, just slower.
ADRs are the established answer: short markdown files in your repo that record the problem, the decision, the alternatives rejected, and the consequences accepted. What was always missing is enforcement. A decision nobody re-reads is a decision nobody follows.
adr-kit closes that loop three times over:
- Before the agent edits: the decisions relevant to the task are ranked and injected as context.
- While the agent edits: a hook nudges it the moment a change touches files governed by a decision.
- When the work lands: declarative rules from each ADR are checked against the diff at commit time and in CI, deterministically and key-free.
And because decisions age, a periodic guardian flags drift between code and decisions, retirement candidates, and decisions that were made but never recorded.
Install
Claude Code (recommended): four commands
/plugin marketplace add rvdbreemen/adr-kit
/plugin install adr-kit@rvdbreemen-adr-kit
/reload-plugins
/adr-kit:init
The first three install the plugin. The fourth is the one-shot per-project bootstrap: it wires a slim stub into your CLAUDE.md (full guide lands at .claude/adr-kit-guide.md), audits your existing codebase for decisions already in effect (the database you chose, the framework you committed to, the patterns you standardized on) and walks you through recording them as Accepted ADRs in batches, then installs the pre-commit enforcement hook. Idempotent: safe to re-run.
That is the whole setup. From the next session on, your agent knows the decisions, gets nudged when it touches them, and cannot commit a violation without it being flagged.
Prefer a lighter start? /adr-kit:setup writes only the CLAUDE.md stub and guide, skipping the audit and the hook; you can add those later with /adr-kit:init or /adr-kit:install-hooks.
OpenAI Codex CLI, Cursor, GitHub Copilot, Claude Cowork, others
The same skill, agent, and instruction files install as plain files; only the directory layout differs per tool. INSTALL.md documents every path and ships a one-shot script (scripts/install-adr-kit.sh style) that lays the files down for all four tool families at once. Quick orientation:
| Tool | Target layout |
|---|
| OpenAI Codex CLI | .codex/skills/, .codex/agents/, .codex/instructions/ (or paste into AGENTS.md) |
| Cursor | .cursor/skills/, .cursor/rules/*.mdc |
| GitHub Copilot | .github/skills/, .github/agents/, .github/instructions/ |
| Claude Cowork | shares the .claude/ convention with Claude Code |
| Anything else | file-based config dir, or paste SKILL.md into the system prompt |
On top of the file install, every tool that speaks MCP (Cursor, Cline, Windsurf, Copilot, Codex) can connect to the bundled MCP server for the enforcement and context tools; see below.
The CLI engines under bin/ run anywhere with Python 3.9+, no pip install, so enforcement in CI works regardless of which editor your team uses.
Upgrading
Three layers, each with a clear path:
