adr-writer
Skill0 starsChanged 5 months agoMITView on GitHub
Write Architecture Decision Records in the Nygard format — context, decision, consequences, and alternatives. Use when recording a significant technical decision or populating a docs/decisions/ directory.
13 other projects use a version of this.
Adopted by
Most recently taken up by
- imtiazrayhan/agentscamp-librarytheir own version, first seen Nov 16, 2026
- llopresto87/Cypresstheir own version, first seen Nov 11, 2026
- Mathews-Tom/armorytheir own version, first seen Nov 1, 2026
- pathiec92/claude-skillstheir own version, first seen Oct 25, 2026
- GabrielHenriqueCA/cortex-aitheir own version, first seen Oct 11, 2026
- govctl-org/govctltheir own version, first seen Oct 9, 2026
Other versions13 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 13
- Mathews-Tom/armory★ 340same name
- govctl-org/govctl★ 276same name
- llopresto87/Cypress★ 121same name
- applypack/applypack★ 32same name
- 45ck/software-architecture-skills★ 16same name
- Ecoa-PUC-Rio/GAIDE★ 8same name
- jcarlos78/GAIDE★ 8same name
- brpaz/agent-skills★ 1same name
- GabrielHenriqueCA/cortex-ai★ 1same name
- imtiazrayhan/agentscamp-library★ 1same name
3 more not listed
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 repository20 other files it gives its agents.
- context-engineeringSkill
- multi-agent-patternsSkill
- prompt-injection-defenseSkill
- rag-retrievalSkill
- ci-cdSkill
- playwright-e2eSkill
- structural-searchSkill
- react-server-componentsSkill
- shadcn-uiSkill
- tailwind-v4Skill
- zustand-stateSkill
- accessibilitySkill
- api-designSkill
- database-patternsSkill
- debuggingSkill
- security-patternsSkill
- typescript-patternsSkill
- proposal-writerSkill
- task-prioritizationSkill
- sitecore-xmcloudSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 6 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 8 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 26
Prevent Revisiting: Avoid endless debates about settled decisions
- Distinctive: line 43
Deprecated: No longer recommended but not yet replaced
- Distinctive: line 119
Use 4-digit zero-padded numbers: ADR-0001, ADR-0002, etc.
- Distinctive: line 123
Keep ADRs in version control alongside code:
- Very specific: line 186
ork:api-design: Use when designing APIs referenced in ADRs - Very specific: line 187
ork:database-patterns: Use when ADR involves database choices - Distinctive: line 206
Keywords: when to write adr, adr lifecycle, adr workflow, adr process, adr review, quantify impact
- Distinctive: line 208
When should I write an ADR?
“Common” is measured: kept by at least 6 in 10 of the 8 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
Architecture Decision Records
Architecture Decision Records (ADRs) are lightweight documents that capture important architectural decisions along with their context and consequences. This skill provides templates, examples, and best practices for creating and maintaining ADRs in your projects.
Overview
- Making significant technology choices (databases, frameworks, cloud providers)
- Designing system architecture or major components
- Establishing patterns or conventions for the team
- Evaluating trade-offs between multiple approaches
- Documenting decisions that will impact future development
Why ADRs Matter
ADRs serve as architectural memory for your team:
- Context Preservation: Capture why decisions were made, not just what was decided
- Onboarding: Help new team members understand architectural rationale
- Prevent Revisiting: Avoid endless debates about settled decisions
- Track Evolution: See how architecture evolved over time
- Accountability: Clear ownership and decision timeline
ADR Format (Nygard Template)
Each ADR should follow this structure:
1. Title
Format: ADR-####: [Decision Title]
Example: ADR-0001: Adopt Microservices Architecture
2. Status
Current state of the decision:
- Proposed: Under consideration
- Accepted: Decision approved and being implemented
- Superseded: Replaced by a later decision (reference ADR number)
- Deprecated: No longer recommended but not yet replaced
- Rejected: Considered but not adopted (document why)
3. Context
What to include:
- Problem statement or opportunity
- Business/technical constraints
- Stakeholder requirements
- Current state of the system
- Forces at play (conflicting concerns)
4. Decision
What to include:
- The choice being made
- Key principles or patterns to follow
- What will change as a result
- Who is responsible for implementation
Be specific and actionable:
- ✅ "We will adopt microservices architecture using Node.js with Express"
- ❌ "We will consider using microservices"
5. Consequences
What to include:
- Positive outcomes (benefits)
- Negative outcomes (costs, risks, trade-offs)
- Neutral outcomes (things that change but aren't clearly better/worse)
6. Alternatives Considered
Document at least 2 alternatives:
For each alternative, explain:
- What it was
- Why it was considered
- Why it was not chosen
7. References (Optional)
Links to relevant resources:
- Meeting notes or discussion threads
- Related ADRs
- External research or articles
- Proof of concept implementations
ADR Lifecycle
Proposed → Accepted → [Implemented] → (Eventually) Superseded/Deprecated
↓
RejectedBest Practices
1. Keep ADRs Immutable
Once accepted, don't edit ADRs. Create new ADRs that supersede old ones.
- ✅ Create ADR-0015 that supersedes ADR-0003
- ❌ Update ADR-0003 with new decisions
2. Write in Present Tense
ADRs are historical records written as if the decision is being made now.
- ✅ "We will adopt microservices"
- ❌ "We adopted microservices"
3. Focus on 'Why', Not 'How'
ADRs capture decisions, not implementation details.
- ✅ "We chose PostgreSQL for relational consistency"
- ❌ "Configure PostgreSQL with these specific settings..."
4. Review ADRs as Team
Get input from relevant stakeholders before accepting.
- Architects: Technical viability
- Developers: Implementation feasibility
- Product: Business alignment
- DevOps: Operational concerns
5. Number Sequentially
Use 4-digit zero-padded numbers: ADR-0001, ADR-0002, etc. Maintain a single sequence even with multiple projects.
6. Store in Git
Keep ADRs in version control alongside code:
- Location:
/docs/adr/or/architecture/decisions/ - Format: Markdown for easy reading
- Branch: Same branch as implementation
Quick Start Checklist
Option 1: Use Script-Enhanced Generator (Recommended)
- Run
/create-adr [number] [title]to generate ADR with auto-filled context - ADR number, date, and author are auto-populated
- Review and fill in decision details
- Set Status to "Proposed" and review with team
Option 2: Use Static Template
- Copy ADR template from
assets/adr-template.md - Assign next sequential number (check existing ADRs)
- Fill in Context: problem, constraints, requirements
- Document Decision: what, why, how, who
- List Consequences: positive, negative, neutral
- Describe at least 2 Alternatives: what, pros/cons, why not chosen
- Add References: discussions, research, related ADRs
- Set Status to "Proposed"
- Review with team
- Update Status to "Accepted" after approval
- Link ADR in implementation PR
- Update Status to "Implemented" after deployment
Available Scripts
scripts/create-adr.md- Dynamic ADR generator with auto-filled context- Auto-fills: ADR number, date, author, total ADRs count
- Usage:
/create-adr [number] [title] - Uses
$ARGUMENTSand!commandfor dynamic context
assets/adr-template.md- Static template for manual use
Rules Quick Reference
| Rule | Impact | What It Covers |
| interrogation-scalability | HIGH | Scale questions, data volume, growth projections |
| interrogation-reliability | HIGH | Data patterns, UX impact, coherence validation |
| interrogation-security | HIGH | Access control, tenant isolation, attack surface |
Common Pitfalls to Avoid
❌ Too Technical: "We'll use Kubernetes with these 50 YAML configs..." ✅ Right Level: "We'll use Kubernetes for container orchestration because..."
❌ Too Vague: "We'll use a better database" ✅ Specific: "We'll use PostgreSQL 15+ for transactional data because..."
❌ No Alternatives: Only documenting the chosen solution ✅ Comparative: Document why alternatives weren't chosen
❌ Missing Consequences: Only listing benefits ✅ Balanced: Honest about costs and trade-offs
❌ No Context: "We decided to use Redis" ✅ Contextual: "Given our 1M+ concurrent users and sub-50ms latency requirement..."
Related Skills
ork:api-design: Use when designing APIs referenced in ADRsork:database-patterns: Use when ADR involves database choices- security-checklist: Consult when ADR has security implications
Skill Version: 2.0.0 Last Updated: 2026-01-08 Maintained by: Mikul Gohil
Capability Details
adr-creation
Keywords: adr, architecture decision, decision record, document decision Solves:
- How do I document an architectural decision?
- Create an ADR
- Architecture decision template
adr-best-practices
Keywords: when to write adr, adr lifecycle, adr workflow, adr process, adr review, quantify impact Solves:
- When should I write an ADR?
- How do I manage ADR lifecycle?
- What's the ADR review process?
- How to quantify decision impact?
- ADR anti-patterns to avoid
- Link related ADRs
tradeoff-analysis
Keywords: tradeoff, pros cons, alternatives, comparison, evaluate options Solves:
- How do I analyze tradeoffs?
- Compare architectural options
- Document alternatives considered
consequences
Keywords: consequence, impact, risk, benefit, outcome Solves:
- What are the consequences of this decision?
- Document decision impact
- Risk and benefit analysis
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.

