---
id: irahardianto/awesome-agv/adr
version: "42194e04"
license: MIT
install: manual
updated: 2026-07-17
---

# adr — The ADR skill helps you record major architectural choices in a structured format that captures the reasoning behind decisions, not just the outcome. It stores numbered records in your project's docs folder and guides you through context, trade-offs, and consequences so your team can understand why decisions were made.

Publisher: irahardianto · Stars: 150 · Updated: 2026-07-17

Install (manual): `git clone https://github.com/irahardianto/awesome-agv`

## SKILL.md

# Architecture Decision Record (ADR) Skill

## Purpose
Document significant architectural decisions so institutional knowledge persists across conversations and team members. ADRs capture the **why**, not just the **what**.

## When to Invoke
- During Research phase (`phase-research.md`) when a significant architecture decision is identified
- When user explicitly asks to document a decision
- When choosing between 2+ viable approaches
- When introducing a new dependency or pattern
- When changing existing architecture

## ADR Storage
ADRs are stored in `docs/decisions/` as numbered files:
```
docs/decisions/
├── 0001-use-postgresql-for-storage.md
├── 0002-adopt-feature-based-structure.md
├── 0003-use-testcontainers-for-integration.md
└── NNNN-short-title.md
```

## ADR Template

Create the ADR file at `docs/decisions/NNNN-short-title.md`:

```markdown
# NNNN. Short Title

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by NNNN

## Context
What is the issue that we're seeing that is motivating this decision?
Include technical constraints, business requirements, and relevant context.

## Options Considered

### Option A: {name}
- **Pros:** ...
- **Cons:** ...
- **Effort:** Low/Medium/High

### Option B: {name}
- **Pros:** ...
- **Cons:** ...
- **Effort:** Low/Medium/High

### Option C: {name} (if applicable)
- **Pros:** ...
- **Cons:** ...
- **Effort:** Low/Medium/High

## Decision
We chose **Option X** because...

## Consequences

### Positive
- What becomes easier or possible as a result

### Negative
- What becomes harder as a result
- Technical debt introduced (if any)

### Risks
- What could go wrong with this decision
- Mitigation strategies

## Related
- Links to relevant rules, previous ADRs, or external resources
```

## Process Guidelines

1. **Number sequentially** — check existing ADRs in `docs/decisions/` for the next number
2. **Keep titles short** — descriptive enough to identify the decision at a glance
3. **Status lifecycle:** `Proposed` → `Accepted` (after approval) → optionally `Deprecated` or `Superseded`
4. **Never delete ADRs** — if a decision is reversed, mark as `Superseded by NNNN` and create a new ADR
5. **Use Sequential Thinking skill** if the trade-off analysis is complex

## Rule Compliance
ADRs should reference applicable rules:
- Architectural Patterns @architectural-pattern.md
- Core Design Principles @core-design-principles.md
- Project Structure @project-structure.md


[View on SkillFed](https://skillfed.io/irahardianto/awesome-agv/adr) · [View on GitHub](https://github.com/irahardianto/awesome-agv)