architecture-decision-records
Records architectural decisions with context, alternatives, and consequences using the ADR format. Use when making or reviewing significant design choices that affect multiple modules or packages.
Best use case
architecture-decision-records is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Records architectural decisions with context, alternatives, and consequences using the ADR format. Use when making or reviewing significant design choices that affect multiple modules or packages.
Teams using architecture-decision-records should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/architecture-decision-records/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How architecture-decision-records Compares
| Feature / Agent | architecture-decision-records | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Records architectural decisions with context, alternatives, and consequences using the ADR format. Use when making or reviewing significant design choices that affect multiple modules or packages.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Architecture Decision Records (ADR) ## Rule Anchor - `AGENTS.md` > "Development Patterns" - `AGENTS.md` > "Build Requirements" ## Use This Skill When - A design choice affects multiple packages or modules. - There are two or more viable alternatives with meaningful trade-offs. - A Gate checkpoint is being passed. - A previous decision needs to be revisited or superseded. - Onboarding requires understanding "why was this done this way?" ## Core Principles 1. One ADR per decision (not per feature or per meeting). 2. Immutable once accepted; superseded by a new ADR, never edited. 3. Lightweight: short context, clear decision, concrete consequences. 4. Stored in version control alongside code. ## File Convention - Location: `.design/decisions/` - Naming: `ADR-NNN-short-title.md` (e.g., `ADR-001-runtime-event-prefix-system.md`) - Status values: `proposed`, `accepted`, `superseded`, `deprecated`, `rejected` ## Template ```markdown # ADR-NNN: Short Title ## Status accepted | superseded by ADR-NNN | rejected ## Context What is the problem or question? Why does it need a decision now? ## Alternatives Considered 1. **Option A**: description — pros / cons 2. **Option B**: description — pros / cons 3. **Option C**: description — pros / cons ## Decision Which option was chosen and why. ## Consequences - What becomes easier or possible. - What becomes harder or impossible. - What follow-up work is needed. ## References - Related ADRs, specs, or rule anchors. ``` ## Workflow 1. Identify that a decision is being made (not just an implementation detail). 2. Write the ADR using the template above. 3. Review: does the decision align with existing rules and principles? 4. Merge the ADR file into the repository. 5. When a decision is superseded, create a new ADR and mark the old one as `superseded by ADR-NNN`. ## Checklist - [ ] Context clearly states the problem, not just the solution. - [ ] At least two alternatives are documented with trade-offs. - [ ] Decision states the chosen option and the primary reason. - [ ] Consequences include both positive and negative impacts. - [ ] ADR is stored in `.design/decisions/` with correct naming. - [ ] Related Gate checkpoints reference the ADR. ## Anti-Patterns - Recording trivial implementation details as ADRs. - Editing accepted ADRs instead of superseding them. - Writing ADRs after the fact without reconstructing alternatives. - ADRs that describe "what" without "why". - No ADR for Gate-level decisions.