architectural-decision-records
Skill9 starsChanged 3 months agoMITView on GitHub
Use when documenting, drafting, reviewing, or updating architectural decisions, ADRs, decision logs, tradeoffs, rationale, consequences, alternatives, or architecture decision history.
4 other projects use a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- cedaniel200/atlas-templateedited, first seen Nov 1, 2026
- intent-driven-dev/intent-driven-templateword for word, first seen Oct 15, 2026
- techfleetworks/enterprise-software-AI-skillstheir own version, first seen Oct 13, 2026
- silvertakana/worldwideviewtheir own version, first seen Oct 8, 2026
Other versions4 projects use a version of this.
Word for word · 1
- intent-driven-dev/intent-driven-template★ 185100% same
Edited · 1
- cedaniel200/atlas-template★ 378% same
Wrote their own version · 2
- silvertakana/worldwideview★ 1.9ksame name
- techfleetworks/enterprise-software-AI-skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository9 other files it gives its agents.
- acceptance-test-authoringSkill
- c4-diagramsSkill
- discoverySkill
- gherkin-authoringSkill
- glossarySkill
- grill-meSkill
- openspec-git-disciplineSkill
- spec-as-sourceSkill
- test-driven-developmentSkill
The file
We split this skill into the rules it gives an agent
9 rules. 0 are common, 4 are distinctive, and 5 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Use when creating, updating, reviewing, or explaining an ADR, architecture decision, decision log, tradeoff analysis, rationale, …
- Distinctive: line 16
Do not use ADRs for transient implementation details, meeting notes, or insignificant decisions.
- Very specific: line 21
Check preferences.md for preferred-style.
- Very specific: line 22
If preferred-style: unset, ask the user which style to use, then record it in preferences.md before drafting.
- Very specific: line 23
Use the matching file under templates/.
- Very specific: line 25
If facts are missing, mark them as Unknown or ask a focused question.
- Distinctive: line 26
Write honest consequences: benefits, downsides, follow-up.
- Distinctive: line 51
If no preference is recorded, ask:
- Very specific: line 55
After the user answers, update preferences.md with the selected preferred-style.
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Architectural Decision Records
Overview
An Architectural Decision Record captures one architecturally significant decision, its rationale, tradeoffs, and consequences. Optimize for future readers reconstructing decision history.
When to Use
Use when creating, updating, reviewing, or explaining an ADR, architecture decision, decision log, tradeoff analysis, rationale, consequences, alternatives, or status.
Do not use ADRs for transient implementation details, meeting notes, or insignificant decisions. If significance is unclear, ask what future maintainers will need to know.
Workflow
- Identify the single decision. Split multiple decisions into multiple ADRs.
- Check
preferences.mdforpreferred-style. - If
preferred-style: unset, ask the user which style to use, then record it inpreferences.mdbefore drafting. - Use the matching file under
templates/. - Capture known facts only: context, requirements, constraints, options, rationale, decision makers, consequences.
- If facts are missing, mark them as
Unknownor ask a focused question; do not invent context, options, or quality attributes. - Write honest consequences: benefits, downsides, follow-up.
- Preserve history: supersede old accepted ADRs; do not rewrite them away.
Template Choice
| Situation | Template |
| Detailed tradeoff record | templates/madr-full.md |
| Concise tradeoff record | templates/madr-minimal.md |
| Classic lightweight ADR | templates/nygard.md |
| One-sentence summary | templates/y-statement.md |
| Project-specific style | templates/custom.md |
| Too little evidence | ADR review notes/questions, not accepted ADR |
Status Values
| Status | Use when |
| Proposed | Under review |
| Accepted | Team committed |
| Deprecated | Historically relevant but no longer recommended |
| Superseded | Replaced by another ADR; link it |
Preference Prompt
If no preference is recorded, ask:
Which ADR style should I use and remember for this project: MADR full, MADR minimal, Nygard, Y-Statement, or custom?
After the user answers, update preferences.md with the selected preferred-style. Do not ask again unless the user asks to change style.
Review Checklist
- One decision, not a bundle
- Significant: affects structure, quality attributes, constraints, or evolution
- Context explains why it existed
- Rejected options/tradeoffs are explicit
- Rationale is tied to requirements, not preference
- Downsides and follow-up work are recorded
- Status is clear
- Unknowns are marked, not invented
Example
# ADR-012: Use PostgreSQL for Orders
## Status
Accepted
## Context
Orders need relational constraints, consistency, and reporting joins. The team operates PostgreSQL well.
## Considered Options
- PostgreSQL: integrity, SQL reporting, familiar operations; migrations required.
- MongoDB: flexible schema; weaker fit for consistency and joins.
## Decision
We will use PostgreSQL because consistency, joins, and operational familiarity matter more than schema flexibility.
## Consequences
- Positive: Integrity and reporting align with needs.
- Negative: Schema changes need migrations.
- Follow-up: Define migration practice.Common Mistakes
| Mistake | Fix |
| Several decisions in one ADR | Split them. |
| Sales pitch | Include rejected options and negative consequences. |
| Invented context | Mark unknowns or ask. |
| Treating status as decoration | Use status to show lifecycle and link superseding ADRs. |
| Rewriting history | Keep old ADR; create/link superseding ADR. |
| Omitting alternatives under pressure | Include at least the rejected option and why it lost. |
Sources
adr.github.io: home, ADR templates, AD practices. See templates/ for captured template variants.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

