ADR-driven development workflow for Claude Code and OpenAI Codex. Add this as a git submodule to any repo and get a structured, document-centric development process — commands, rules, templates, and governance — in a single versioned package.

Most teams adopt AI coding assistants reactively — ask a question, get code, paste it in. This works for isolated tasks but breaks down on anything requiring more than one session: the AI has no memory of what was decided, why a particular approach was chosen, or what still needs to be done. Every session starts from scratch.

adr-kit takes a different approach. Claude Code operates within a structured, document-driven process before it writes a single line of code. The foundation is the Architecture Decision Record (ADR) — a format borrowed from traditional software architecture practice, adapted to serve as the specification, conversation log, and approval gate for every non-trivial change.

The goal is not to slow things down. It is to make sure that when Claude implements something, it is implementing the right thing — approved by a human, with full traceability back to the decision that justified it — and that any team member or new session can pick up exactly where things left off.

• Claude Code — 14 slash commands (/adr-init, /adr-new-adr, /adr-continue, and more), auto-loaded rules, settings template
• OpenAI Codex — AGENTS.base.md with all workflow rules and guidance inline, no commands needed
• 10 standing rules — commit approval, ADR workflow, KISS, surgical changes, and more
• Templates — ADR, execution plan, backlog item, parallel work brief, ADR index
• Stack detection — auto-generates Python, TypeScript, and .NET convention rules on init
• Git worktree support — isolated parallel feature development out of the box
• npx installer — npx @tiagoasta/adrkit init --claude or --codex

npx @tiagoasta/adrkit init --claude

This adds the submodule, then prompts you to run one command inside Claude Code:

@.claude/adr-kit/commands/adr-init.md

That single command bootstraps commands, rules, docs structure, CLAUDE.md, and settings.json.

npx @tiagoasta/adrkit init --codex

This adds the submodule, creates AGENTS.md (auto-loaded by Codex at every session), and scaffolds docs/. No further setup needed — the workflow is driven conversationally:

"Create an ADR for [feature description]"
"Create an execution plan for ADR-[ID]"
"Resume the current feature"

npx @tiagoasta/adrkit update

Pulls the latest submodule. For Claude Code, also run /adr-update inside Claude Code to refresh command shims and rules.

git submodule add https://github.com/tiagoastak/adr-kit.git .claude/adr-kit
git submodule update --init

Then for Claude Code: @.claude/adr-kit/commands/adr-init.md For Codex: create AGENTS.md with Read '.claude/adr-kit/AGENTS.base.md' for workflow instructions. as the first line.

1. Fill in CLAUDE.md — repo name, Quick Commands (run/test/lint), Architecture Overview
2. Review .claude/settings.json — add your stack's tool permissions
3. Commit:

git add .claude/ docs/ CLAUDE.md
git commit -m "chore: initialize adr-kit workflow"

Every feature follows the same path, enforced by rules and slash commands:

Feature description
    ↓
/adr-new-adr  →  ADR created (Status: Proposed)
               Claude generates clarifying questions
               You answer them directly in the ADR
    ↓
You set Status: Accepted  ◄── GATE 1: no plan until accepted
    ↓
/adr-new-plan  →  Execution Plan created (Status: Draft)
               Claude designs the implementation:
               file tree, type signatures, test strategy — no code yet
    ↓
You approve the plan  ◄── GATE 2: no code until approved
    ↓
/adr-continue  →  Implementation
               Claude writes code, runs tests,
               shows diffs before every commit
    ↓
You review and approve each commit  ◄── GATE 3: explicit approval required
    ↓
/adr-archive-plan  →  Plan archived, ADR updated

Silence is never approval. Passing tests are never approval. Only explicit words — "commit it", "go ahead", "looks good" — unlock a commit. This is enforced by the commit-approval.md rule loaded at every session.

ADRs live at docs/adrs/{ID}-title-adr.md where {ID} is a random 6-digit number. They are permanent records — once accepted, only superseded by a newer ADR that references them.

When an ADR is created, Claude generates clarifying questions — typically 5–10 covering security, data model, error handling, API design, and backward compatibility. You answer each one directly in the markdown file. Each answer becomes a permanent row in the Clarifications Log with the decision and rationale.

The execution plan is the session state for an in-progress feature — committed to git after every session so state is never lost.

The execution plan answers one question at the start of every session: "What do I do right now?" Any team member — or a completely fresh Claude session — can resume the feature in under two minutes.

Claude Code has a finite context window. Load too much and earlier content gets pushed out. Load too little and Claude makes assumptions.

The ADR workflow solves this deliberately. Rather than letting Claude explore freely, it defines exactly what to load and in what order:

1. CLAUDE.md — loaded automatically every session. Contains the "Active Work" pointer.
2. The ADR — provides the why: decisions made, tradeoffs, constraints.
3. The Execution Plan — provides the what right now: current step, files to load, next action.

The result is a tightly scoped session — roughly 1,500 lines — compared to 10,000+ from unrestricted exploration. Smaller context means sharper focus, more predictable output, and easier review.

Commands are entirely optional. Every step can be driven through natural conversation with Claude — "create an ADR for this feature", "draft an execution plan", "resume the current feature". Commands are shortcuts that ensure consistency, not a prerequisite.

Rules are Markdown files in .claude/rules/ that Claude reads at the start of every session. They define non-negotiable standing instructions.

Repo-specific rules (you add these): stack conventions (python-conventions.md, typescript-conventions.md, dotnet-conventions.md), testing framework specifics, deployment rules.

The settings.json philosophy: automate the safe and reversible; gate the consequential.

Pre-approved (Claude runs freely): git, gh, standard Unix utilities, plus your stack's tools.

Approval required (prompts every time): git add, git commit — enforces human-in-the-loop.

Denied entirely: rm -rf *, git push — no auto-push, no catastrophic deletes.

Commits follow the Conventional Commits format:

<type>(<scope>): <subject>

<optional body>

Types: feat | fix | refactor | test | docs | chore | build | perf

Two features can run simultaneously without interference using Git worktrees. Each worktree is an isolated checkout on its own branch, sharing the same .git directory.

git worktree add .claude/worktrees/feature-abc story/feature-abc
cd .claude/worktrees/feature-abc
claude

When two parallel features touch shared interfaces, a parallel work brief defines frozen interface contracts and file ownership boundaries so neither worktree breaks the other.

Commands = shim files. Each .claude/commands/adr-*.md contains one line: @.claude/adr-kit/commands/adr-continue.md. Updating a command in adr-kit takes effect across all consuming repos the next time they run /adr-update.

Rules = copied files. Unlike commands, rules are loaded automatically at session start — not user-invoked. adr-init copies them into .claude/rules/. adr-update refreshes the copies, flagging local modifications before overwriting.

CLAUDE.md = @ import + repo sections. The first line of every repo's CLAUDE.md is @.claude/adr-kit/CLAUDE.base.md. Everything repo-specific (Quick Commands, Active Work, Architecture Overview, Code Conventions) comes after.

settings.json is repo-owned. Permissions are security-sensitive and require explicit human review per repo. settings.base.json is a reference document; adr-init uses it as a starting template.

Submodule is pinned. Each consuming repo pins to a specific adr-kit commit. No surprise workflow changes — updates are deliberate.

Found a bug in a command? A rule that conflicts with how your team works? A missing template section?

Open an issue: github.com/tiagoastak/adr-kit/issues

Use issues for:

• Bug reports (command does the wrong thing, rule fires incorrectly)
• Workflow improvements (a step is unclear, a gate is in the wrong place)
• New command requests
• Template gaps

Pull requests are welcome. If the change is non-trivial, open an issue first — changes to base rules and commands affect every repo using adr-kit, so a quick alignment conversation is worth it.

If adr-kit saves you time, consider buying me a coffee — it helps fund continued development of this and other open-source tools.

MIT — see LICENSE.