Agent Decision Records (AgDR)
A standard for documenting technical decisions made by AI coding agents.
AgDR extends the proven Architecture Decision Record (ADR) format for AI-assisted software development. When AI agents make technical choices—selecting libraries, choosing patterns, designing architecture—those decisions need the same rigor and traceability as human decisions.
Why AgDR?
AI coding agents (Claude Code, Codex, GitHub Copilot, Cursor, Windsurf, etc.) increasingly make technical decisions autonomously. Without documentation:
- Decisions are invisible - No record of why the agent chose React over Vue
- Context is lost - Next session starts fresh with no memory
- Teams can't audit - PR reviews miss the reasoning behind choices
- Knowledge doesn't transfer - Onboarding devs can't understand AI-made decisions
AgDR solves this by requiring agents to document decisions in a structured, human-readable format that lives with your code.
Key Differences from ADR
| Aspect | ADR | AgDR |
|---|
| Author | Human architect | AI agent |
| Trigger | Design meetings, RFCs | Detected decision patterns during coding |
| Timing | Before/after implementation | Real-time, as decisions are made |
| Metadata | Optional | Required (model, session, timestamp) |
| Enforcement | Manual process | Automated via hooks, skills, or prompts |
| Location | docs/adr/ | docs/agdr/ (per-project) |
Quick Start
Install as Claude Code Plugin
/plugin marketplace add me2resh/agent-decision-record
/plugin install agent-decision-record@agent-decision-record
Then use:
/agent-decision-record:decide which testing framework to use
Using Claude Code (manual)
Copy commands/decide.md to your project's .claude/commands/decide.md:
/decide which testing framework to use
Using Codex
$agdr-decide which testing framework to use
Using System Prompts (any AI)
Add to your AI assistant's context:
Before making any technical decision (choosing libraries, patterns, or architecture),
create an AgDR document following the template at:
https://github.com/me2resh/agent-decision-record
Output
---
id: AgDR-0001
timestamp: 2026-01-30T18:45:00Z
agent: claude-code
model: claude-opus-4-5-20251101
trigger: user-prompt
status: executed
---
# Use Vitest for unit testing
> In the context of a new TypeScript project, facing the need for fast test execution,
> I decided to use Vitest to achieve rapid feedback loops, accepting that it's newer
> than Jest with a smaller ecosystem.
## Context
- New TypeScript monorepo with Vite build system
- Team prioritizes fast feedback during development
- Existing Jest knowledge on team
## Options Considered
| Option | Pros | Cons |
|--------|------|------|
| Jest | Industry standard, huge ecosystem | Slower, complex config with ESM |
| Vitest | Native Vite support, fast, Jest-compatible API | Newer, smaller ecosystem |
## Decision
Chosen: **Vitest**, because it integrates natively with our Vite setup and provides
significantly faster test execution while maintaining Jest API compatibility.
## Consequences
- Tests run 3-5x faster than Jest equivalent
- Team can reuse Jest knowledge (compatible API)
- May need workarounds for some Jest plugins
AgDR Template
See agdr-template.md for the full template.
Required Fields
| Field | Description | Example |
|---|
id | Unique identifier | AgDR-0001 |
timestamp | ISO-8601 with time | 2026-01-30T18:45:00Z |
agent | Agent that made the decision | claude-code, codex, copilot, cursor |
model | Model identifier | claude-opus-4-5-20251101 |
trigger | What initiated the decision | user-prompt, hook, automation |
status | Decision status | proposed, executed, superseded |
The Y-Statement
Every AgDR must include a one-line summary following the Y-statement format:
In the context of [situation], facing [concern], I decided [decision] to achieve [goal], accepting [tradeoff].
Directory Structure
AgDRs are stored per-project, not centralized:
your-project/
├── docs/
│ └── agdr/
│ ├── AgDR-0001-use-vitest-for-testing.md
│ ├── AgDR-0002-jwt-for-authentication.md
│ └── README.md # Index of decisions
├── src/
└── ...
Why per-project?
- Decisions travel with the code they affect
- Each project has its own ID sequence
- PRs can reference AgDRs in the same repo
- History preserved if project is forked
Tools & Integrations
me2resh