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.
AI coding agents (Claude Code, 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.
| 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) |
/decide which testing framework to useAdd 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
---
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 pluginsSee agdr-template.md for the full template.
| 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, 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 |
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].
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
| Tool | Format | Location |
|---|---|---|
| Claude Code | /decide skill |
tools/claude-code/ |
| Cursor | .cursor/rules/agdr.mdc |
tools/cursor/ |
| GitHub Copilot | .github/copilot-instructions.md + .instructions.md |
tools/copilot/ |
| Windsurf | .windsurf/rules/agdr.md |
tools/windsurf/ |
| Any AI | System prompt | tools/system-prompts/ |
| Git | Pre-commit hook | tools/git-hooks/ |
The /decide skill triggers structured decision-making: tools/claude-code/decide.md
MDC rule with alwaysApply: true for Cursor's modern .cursor/rules/ format. Also includes legacy .cursorrules for backward compatibility: tools/cursor/
Repository-wide instructions (.github/copilot-instructions.md) plus path-specific instructions for AgDR files (.github/instructions/agdr.instructions.md): tools/copilot/
Cascade rule with trigger: always_on for Windsurf's .windsurf/rules/ format: tools/windsurf/
Generic prompts for any AI assistant: tools/system-prompts/
Pre-commit hooks to enforce AgDR creation: tools/git-hooks/
Real-world AgDRs from production projects (anonymised):
| Example | Domain | Key Decision |
|---|---|---|
| Auth Provider Choice | Auth / Serverless | Cognito vs Auth0 vs Firebase vs Custom |
| DynamoDB Key Design | Database | Workspace-partitioned vs entity-first keys |
| Data Migration Strategy | Migration | Copy-on-login vs script vs lazy dual-read |
| MVVM Architecture | Mobile | MVVM vs MVI vs MVP for Android |
| Release Workflow | CI/CD | Manual dispatch vs tag-triggered vs Fastlane |
| Image Loading Library | Mobile | Coil vs Glide for Compose |
Create an AgDR when the AI agent:
| Trigger | Example |
|---|---|
| Compares options | "Should we use X or Y?" |
| Chooses a library | Adding a new dependency |
| Selects a pattern | "Let's use the repository pattern" |
| Makes architecture choices | "I'll structure this as microservices" |
| Picks a convention | "We'll use kebab-case for file names" |
Don't create AgDRs for:
- Trivial choices (variable names, formatting)
- Following existing project conventions
- Bug fixes with obvious solutions
Organizations using AgDR:
| Organization | Description |
|---|---|
| ApexScript | AI-first software consultancy |
Want to be listed? Open a PR!
We welcome contributions! See CONTRIBUTING.md for guidelines.
Ideas for contribution:
- Templates for specific domains (security, data, ML)
- Integrations with other AI tools
- Translations to other languages
- Case studies and examples
AgDR builds on the foundational work of:
- Architecture Decision Records by Joel Parker Henderson - The comprehensive ADR resource that inspired this project
- MADR - Markdown Any Decision Records format
- Michael Nygard - Original ADR proposal (2011)
- ADR GitHub Organization - Community standards for ADRs
CC BY 4.0 - Creative Commons Attribution 4.0 International
You are free to share and adapt this material with appropriate credit.
Created by me2resh