architecture-decision-records – Coding skill for AI agents

Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.

CodingSKILL.mdClaude Code · Codex · Hermes · DeepSeek

Install the architecture-decision-records skill with one command

Pick the tool you use, copy the command and paste it in your terminal. The skill lands in that tool's skills folder and is ready in your next session.

Claude Code

mkdir -p ~/.claude/skills && curl -fsSL https://skill.dn1nguoi.com/z/architecture-decision-records-28c36.tgz | tar xz -C ~/.claude/skills

Call it in Claude Code: /architecture-decision-records – then describe the task you want done.

Codex

mkdir -p ~/.codex/skills && curl -fsSL https://skill.dn1nguoi.com/z/architecture-decision-records-28c36.tgz | tar xz -C ~/.codex/skills

Call it in Codex: $architecture-decision-records – then describe the task you want done.

Hermes Agent

mkdir -p ~/.hermes/skills && curl -fsSL https://skill.dn1nguoi.com/z/architecture-decision-records-28c36.tgz | tar xz -C ~/.hermes/skills

Call it in Hermes Agent: /architecture-decision-records – then describe the task you want done.

DeepSeek

mkdir -p ~/.deepcode/skills && curl -fsSL https://skill.dn1nguoi.com/z/architecture-decision-records-28c36.tgz | tar xz -C ~/.deepcode/skills

Call it in DeepSeek: /architecture-decision-records – then describe the task you want done.

SKILL.md content

Architecture Decision Records

Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.

When to Use This Skill

Making significant architectural decisions
Documenting technology choices
Recording design trade-offs
Onboarding new team members
Reviewing historical decisions
Establishing decision-making processes

Core Concepts

1. What is an ADR?

An Architecture Decision Record captures:

Context: Why we needed to make a decision
Decision: What we decided
Consequences: What happens as a result

2. When to Write an ADR

| Write ADR | Skip ADR |

| -------------------------- | ---------------------- |

| New framework adoption | Minor version upgrades |

| Database technology choice | Bug fixes |

| API design patterns | Implementation details |

| Security architecture | Routine maintenance |

| Integration patterns | Configuration changes |

3. ADR Lifecycle

Proposed → Accepted → Deprecated → Superseded
              ↓
           Rejected

Before drafting a standard, lightweight, or Y-statement ADR, read [decision templates](references/decision-templates.md).

Before drafting a deprecation ADR or RFC, read [deprecation and RFC templates](references/deprecation-rfc-templates.md).

ADR Management

Directory Structure

docs/
├── adr/
│   ├── README.md           # Index and guidelines
│   ├── template.md         # Team's ADR template
│   ├── 0001-use-postgresql.md
│   ├── 0002-caching-strategy.md
│   ├── 0003-mongodb-user-profiles.md  # [DEPRECATED]
│   └── 0020-deprecate-mongodb.md      # Supersedes 0003

ADR Index (README.md)

# Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) for [Project Name].

## Index

| ADR                                   | Title                              | Status     | Date       |
| ------------------------------------- | ---------------------------------- | ---------- | ---------- |
| [0001](0001-use-postgresql.md)        | Use PostgreSQL as Primary Database | Accepted   | 2024-01-10 |
| [0002](0002-caching-strategy.md)      | Caching Strategy with Redis        | Accepted   | 2024-01-12 |
| [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles          | Deprecated | 2023-06-15 |
| [0020](0020-deprecate-mongodb.md)     | Deprecate MongoDB                  | Accepted   | 2024-01-15 |

## Creating a New ADR

1. Copy `template.md` to `NNNN-title-with-dashes.md`
2. Fill in the template
3. Submit PR for review
4. Update this index after approval

## ADR Status

- **Proposed**: Under discussion
- **Accepted**: Decision made, implementing
- **Deprecated**: No longer relevant
- **Superseded**: Replaced by another ADR
- **Rejected**: Considered but not adopted

Automation (adr-tools)

# Install adr-tools
brew install adr-tools

# Initialize ADR directory
adr init docs/adr

# Create new ADR
adr new "Use PostgreSQL as Primary Database"

# Supersede an ADR
adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"

# Generate table of contents (to a separate file, so the hand-written
# index and guidelines in README.md are not overwritten)
adr generate toc > docs/adr/toc.md

# Link related ADRs
adr link 2 "Complements" 1 "Is complemented by"

Review Process

## ADR Review Checklist

### Before Submission

- [ ] Context clearly explains the problem
- [ ] All viable options considered
- [ ] Pros/cons balanced and honest
- [ ] Consequences (positive and negative) documented
- [ ] Related ADRs linked

### During Review

- [ ] At least 2 senior engineers reviewed
- [ ] Affected teams consulted
- [ ] Security implications considered
- [ ] Cost implications documented
- [ ] Reversibility assessed

### After Acceptance

- [ ] ADR index updated
- [ ] Team notified
- [ ] Implementation tickets created
- [ ] Related documentation updated

Best Practices

Do's

Write ADRs early - Before implementation starts
Keep them short - 1-2 pages maximum
Be honest about trade-offs - Include real cons
Link related decisions - Build decision graph
Update status - Deprecate when superseded

Don'ts

Don't change accepted ADRs - Write new ones to supersede
Don't skip context - Future readers need background
Don't hide failures - Rejected decisions are valuable
Don't be vague - Specific decisions, specific consequences
Don't forget implementation - ADR without action is waste

Related skills

architecture-patterns – Implement proven backend architecture patterns including Clean Architecture, Hexagonal…
gh-address-comments – Help address review/issue comments on the open GitHub PR for the current branch using gh…
airtable – Airtable REST API via curl. Records CRUD, filters, upserts.
claude-api – Reference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming…
code-simplification – Simplifies code for clarity. Use when refactoring code for clarity without changing…
astropy – Core Python library for astronomy and astrophysics workflows that need Astropy APIs…
async-python-patterns – Master Python asyncio, concurrent programming, and async/await patterns for…
gh-fix-ci – Inspect GitHub PR checks with gh, pull failing GitHub Actions logs, summarize failure…

← Browse all skills