agent-decision-record Cursor Rules

# Agent Decision Records (AgDR) — Cursor Rules

# PURPOSE
# Forces structured documentation of technical decisions made during AI-assisted coding.
# Creates auditable records at docs/agdr/ for every non-trivial choice.
# See: https://github.com/me2resh/agent-decision-record

# DECISION DETECTION
# Before writing any code, scan your planned response for these patterns:
# - "I'll use X" or "Let's go with X" → STOP, document decision first
# - Comparing "X vs Y" or "X or Y" → STOP, document decision first
# - Choosing a library, framework, or tool → STOP, document decision first
# - Picking an implementation approach → STOP, document decision first
# - Making an architectural choice → STOP, document decision first
# - Adding a new dependency → STOP, document decision first

# TEST: If someone asked "why did you choose X over Y?" and you'd need to explain
# trade-offs, that's a decision. Document it.

# WHEN TO CREATE AN AgDR
# - Library/framework selection (e.g., "use Zustand over Redux")
# - Architecture pattern choice (e.g., "use repository pattern")
# - Database/schema design decisions
# - API design decisions (REST vs GraphQL, auth approach)
# - Infrastructure choices (hosting, CI/CD, deployment)
# - Testing strategy decisions
# - Any choice between 2+ viable alternatives

# WHEN NOT TO CREATE AN AgDR
# - Trivial choices (variable names, formatting)
# - Following existing project conventions already documented
# - Bug fixes with a single obvious solution
# - Code style that matches the existing codebase

# AgDR FORMAT
# Create files at: docs/agdr/AgDR-{NNNN}-{slug}.md
# To find the next number:
#   ls docs/agdr/AgDR-*.md 2>/dev/null | sort -V | tail -1
#   Increment by 1, or start at 0001

# TEMPLATE (copy and fill in):
#
# ---
# id: AgDR-{NNNN}
# timestamp: {YYYY-MM-DDTHH:MM:SSZ}
# agent: cursor
# model: {model-id}
# trigger: user-prompt
# status: executed
# ---
#
# # {Short descriptive title}
#
# > In the context of {situation}, facing {concern}, I decided {decision}
# > to achieve {goal}, accepting {tradeoff}.
#
# ## Context
# - {What problem are we solving?}
# - {What constraints exist?}
#
# ## Options Considered
# | Option | Pros | Cons |
# |--------|------|------|
# | **Option A** | Pro 1, Pro 2 | Con 1, Con 2 |
# | **Option B** | Pro 1, Pro 2 | Con 1, Con 2 |
#
# ## Decision
# Chosen: **{Option}**, because {specific justification}.
#
# ## Consequences
# - {What changes as a result}
# - {What tradeoffs we accept}

# RULES
# 1. ALWAYS create AgDR BEFORE implementing the decision
# 2. Compare at least 2 real options (no strawmen)
# 3. Y-statement summary is required (the > blockquote line)
# 4. "because" clause is mandatory in the Decision section
# 5. Be specific — "3x faster" beats "much faster"
# 6. Document real tradeoffs — every decision has downsides
# 7. Create docs/agdr/ directory if it doesn't exist

# WORKFLOW
# 1. Detect decision point in your response
# 2. STOP — don't write implementation code yet
# 3. Present options to user with pros/cons table
# 4. Get confirmation on the choice
# 5. Create the AgDR file
# 6. Then proceed with implementation

# CODE REVIEW INTEGRATION
# When reviewing code, flag these as missing AgDRs:
# - New dependencies in package.json, build.gradle, requirements.txt, etc.
# - New architectural patterns not previously used
# - New modules or service boundaries
# - Infrastructure or deployment changes