# Adr Template

> Structures an Architecture Decision Record (ADR) to capture context, decision, and consequences of significant architectural choices, ensuring decisions are documented with sufficient detail for future teams.

- Skill: `cloudthinker-ai/adr-template` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cloudthinker-ai/adr-template`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cloudthinker-ai/adr-template/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing, Coding & Dev Tools, Technical Writing
- Tags: Adr, Architecture Decision Record, Decision Log, Documentation
- Author: cloudthinker-ai (https://skillmd.com/u/cloudthinker-ai)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/cloudthinker-ai/adr-template

---


# Architecture Decision Record

## Phase 1: Context

Define the situation that motivates this decision.

1. - [ ] Describe the technical or business context
2. - [ ] Identify the forces at play (technical, political, organizational)
3. - [ ] List any constraints or assumptions
4. - [ ] Reference related ADRs or design documents
5. - [ ] State the urgency and timeline for the decision

**Status:** Proposed / Accepted / Deprecated / Superseded

**Date:** ___

## Phase 2: Options Analysis

Enumerate and evaluate all viable options.

| Option | Description | Pros | Cons | Effort | Risk |
|--------|------------|------|------|--------|------|
| A      |            |      |      |        |      |
| B      |            |      |      |        |      |
| C      |            |      |      |        |      |

**Evaluation Criteria:**

| Criterion | Weight | Option A | Option B | Option C |
|-----------|--------|----------|----------|----------|
| Performance | | | | |
| Maintainability | | | | |
| Cost | | | | |
| Team familiarity | | | | |
| Ecosystem maturity | | | | |
| Scalability | | | | |
| **Weighted Total** | | | | |

## Phase 3: Decision

- [ ] State the chosen option clearly
- [ ] Explain the primary rationale
- [ ] Note any dissenting opinions and how they were addressed
- [ ] Specify the scope and boundaries of this decision

## Phase 4: Consequences

Document the expected outcomes of this decision.

**Positive consequences:**
- [ ] List expected benefits

**Negative consequences:**
- [ ] List expected drawbacks or trade-offs

**Risks:**
- [ ] Identify risks introduced by this decision
- [ ] Define mitigation strategies for each risk

**Reversibility:**
- [ ] Is this decision easily reversible? Y/N
- [ ] What would reversal cost? (effort, time, risk)
- [ ] Under what conditions should this decision be revisited?

## Phase 5: Implementation Notes

- [ ] Key implementation steps or considerations
- [ ] Migration plan (if replacing existing approach)
- [ ] Timeline for implementation
- [ ] Success metrics to validate the decision

## Counter-Rationalizations

| Shortcut | Counter | Why |
|----------|---------|-----|
| "We can skip some steps for this case" | Adapt the workflow steps, don't skip them | Skipped steps are where incidents and oversights originate |
| "The user seems to already know what to do" | Complete all workflow phases with the user | The workflow catches blind spots that experience alone misses |
| "This is a minor case, full process is overkill" | Scale the process down, don't turn it off | Minor cases become major when unstructured; the process scales, not disappears |
| "I'll fill in the details later" | Complete each section before moving on | Deferred details are forgotten; real-time capture is more accurate |
| "The template output isn't necessary" | Always produce the structured output format | Structured output enables comparison, audit trails, and handoff to other teams |

## Output Format

### ADR Summary

- **ADR:** ___
- **Title:** ___
- **Status:** ___
- **Date:** ___
- **Deciders:** ___
- **Decision:** One-sentence summary of the decision

### Action Items

- [ ] Update relevant system design documents
- [ ] Communicate decision to affected teams
- [ ] Create implementation tickets
- [ ] Schedule decision review at ___ (if time-bounded)
- [ ] Update ADR index/registry