Skip to main content
architecture-decision-record ADR templates in the Nygard format with context, decision, consequences, and alternatives. Use when writing ADRs, recording an architectural decision, or evaluating options.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/yonatangross/orchestkit --skill architecture-decision-recordThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository Chain patterns for multi-phase pipelines: MCP detection, handoff files, checkpoint-resume, worktree agents, CronCreate monitoring. Use when building or debugging a pipeline skill.
OrchestKit doctor for health diagnostics across manifest integrity, hook configuration, skill validation, agent frontmatter, MCP server connectivity, CC version compatibility, and permission rules. Reports issues with severity levels and auto-remediation suggestions. Validates component counts, detects orphaned entries, and checks CC version matrix compliance. Use when diagnosing plugin health, troubleshooting configuration issues, or running pre-release checks.
Inspects the OrchestKit telemetry pipeline for the current project — lists all known telemetry files with write counts, sizes, schema status, growth trend, and orphan detection. Use when verifying the observability pipeline is healthy, debugging a missing writer, or auditing which files have schema locks vs. which are drift-vulnerable. Read-only — never modifies telemetry files.
Related occupations SOC
Based on SOC occupation classification
name architecture-decision-record license MIT compatibility Claude Code 2.1.220+. description ADR templates in the Nygard format with context, decision, consequences, and alternatives. Use when writing ADRs, recording an architectural decision, or evaluating options. version 2.0.0 author OrchestKit tags ["architecture","documentation","decision-making","backend"] context fork agent backend-system-architect user-invocable false complexity medium persuasion-type guidance metadata {"category":"document-asset-creation"} allowed-tools ["Read","Glob","Grep","WebFetch","WebSearch"]
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 decidedOnboarding : Help new team members understand architectural rationalePrevent Revisiting : Avoid endless debates about settled decisionsTrack Evolution : See how architecture evolved over timeAccountability : 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 considerationAccepted : Decision approved and being implementedSuperseded : Replaced by a later decision (reference ADR number)Deprecated : No longer recommended but not yet replacedRejected : 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
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
↓
Rejected
Best 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 readingBranch : Same branch as implementation
Quick Start Checklist
Option 1: Use Script-Enhanced Generator (Recommended)
Option 2: Use Static Template
assets/adr-template.md
Available Scripts
Rules Quick Reference
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-designork:database-patternssecurity-checklist : Consult when ADR has security implications
Skill Version : 2.0.0
Last Updated : 2026-01-08
Maintained by : OrchestKit
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
