# Ddunnock Claude Plugins Adr Authoring > Architecture Decision Record Authoring - Skill: `tomevault-io/ddunnock-claude-plugins-adr-authoring` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/ddunnock-claude-plugins-adr-authoring` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/ddunnock-claude-plugins-adr-authoring/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/ddunnock-claude-plugins-adr-authoring --- # Architecture Decision Record Authoring Write clear, useful ADRs that capture the context, options, and rationale behind technical decisions. Good ADRs prevent re-litigation of decisions and help new team members understand the codebase. ## Quick Reference ### MADR Template Levels | Level | When to Use | Required Fields | |-------|-------------|-----------------| | **Lightweight** | Quick decisions, low impact | Status, Context, Decision, Consequences | | **Standard** | Most architectural decisions | + Date, Decision-makers, Drivers, Options | | **Full** | Critical/reversible decisions | + Confirmation, Traceability | ### ADR Lifecycle ``` proposed → accepted → [deprecated → superseded] ↘ rejected ``` ## Lightweight ADR Template For quick decisions with limited impact: ```markdown ### ADR-XXX: [Short Title] **Status**: proposed | accepted | rejected | deprecated | superseded **Context and Problem Statement** [2-3 sentences describing the situation and what needs to be decided] **Decision Outcome** Chosen option: "[Option name]" [1-2 sentences explaining why] **Consequences** - Good: [positive outcomes] - Bad: [negative outcomes or trade-offs] ``` ## Standard ADR Template For most architectural decisions: ```markdown ### ADR-XXX: [Short Title] **Status**: proposed | accepted | rejected | deprecated | superseded **Date**: YYYY-MM-DD **Decision-makers**: [names or roles] **Context and Problem Statement** [2-3 sentences describing the situation requiring a decision. What is the issue? Why does it need to be addressed now?] **Decision Drivers** - [Driver 1: e.g., "Need to support 10x current load"] - [Driver 2: e.g., "Team has no experience with technology X"] - [Driver 3: e.g., "Budget constraint of $X/month"] **Considered Options** 1. [Option 1 name] 2. [Option 2 name] 3. [Option 3 name] **Decision Outcome** Chosen option: "[Option N]" because [1-2 sentence rationale linking to drivers]. **Consequences** - Good: [positive outcome 1] - Good: [positive outcome 2] - Bad: [trade-off or negative outcome] - Neutral: [side effect that's neither good nor bad] ``` ## Full ADR Template For critical decisions requiring traceability: ```markdown ### ADR-XXX: [Short Title] **Status**: proposed | accepted | rejected | deprecated | superseded **Date**: YYYY-MM-DD **Decision-makers**: [names or roles] **Context and Problem Statement** [Detailed context with background information. Include relevant constraints and dependencies.] **Decision Drivers** - [Driver 1 with quantifiable metric if possible] - [Driver 2] - [Driver 3] **Considered Options** 1. **[Option 1 name]**: [Brief description] 2. **[Option 2 name]**: [Brief description] 3. **[Option 3 name]**: [Brief description] **Pros and Cons of Options** #### Option 1: [Name] - Good: [Pro 1] - Good: [Pro 2] - Bad: [Con 1] #### Option 2: [Name] - Good: [Pro 1] - Bad: [Con 1] - Bad: [Con 2] #### Option 3: [Name] - Good: [Pro 1] - Neutral: [Neither good nor bad] - Bad: [Con 1] **Decision Outcome** Chosen option: "[Option N]" because [rationale]. **Consequences** - Good: [outcome 1] - Bad: [outcome 2] **Confirmation** [How will we verify this decision was correct?] - [Metric or checkpoint 1] - [Metric or checkpoint 2] **Traceability** - Requirements: REQ-XXX, REQ-YYY - Tasks: TASK-XXX, TASK-YYY - Supersedes: ADR-ZZZ (if applicable) ``` ## Writing Effective ADRs ### Context Section **Do:** - State the problem clearly in 2-3 sentences - Include relevant constraints (time, budget, team skills) - Mention what triggered this decision **Don't:** - Write a novel (save details for options analysis) - Assume reader knows the background - Include the solution in the context ### Decision Drivers Quantify when possible: | Vague | Specific | |-------|----------| | "Need better performance" | "Must handle 1000 req/sec" | | "Team preference" | "3 of 4 developers have React experience" | | "Cost concerns" | "Budget limit: $500/month" | ### Considered Options Include at least 2 options. Always include: - The chosen option - The obvious alternative - "Do nothing" if applicable ### Consequences Be honest about trade-offs: ```markdown **Consequences** - Good: Reduces API latency by 40% - Good: Team already knows this technology - Bad: Adds operational complexity (new service to maintain) - Bad: Vendor lock-in to AWS - Neutral: Requires migration of existing data (one-time effort) ``` ## ADR Numbering Use sequential numbering within the project: ```markdown ADR-001: Database Selection ADR-002: Authentication Strategy ADR-003: API Versioning Approach ``` For domain-specific ADRs in larger projects: ```markdown ADR-AUTH-001: OAuth Provider Selection ADR-DATA-001: Cache Strategy ADR-INFRA-001: Container Orchestration ``` ## When to Write an ADR | Situation | ADR Level | |-----------|-----------| | Choosing a database | Standard or Full | | Selecting a framework | Standard | | API design patterns | Standard | | Deployment strategy | Standard or Full | | Library selection | Lightweight | | Code organization | Lightweight | | Naming conventions | Lightweight (or skip) | ## Integration with SpecKit ADRs created during `/speckit.plan` should: 1. **Use consistent numbering** - ADR-001, ADR-002, etc. 2. **Reference requirements** - Link to REQ-XXX from spec 3. **Be validated** - `/speckit.analyze` checks ADR completeness 4. **Trace to tasks** - Tasks reference implementing ADRs ## Additional Resources For detailed patterns and examples, see: - **`references/madr-full-template.md`** - Complete MADR template with all fields - **`references/adr-examples.md`** - Real-world ADR examples ## Checklist Before Finalizing - [ ] Status is set (proposed for new ADRs) - [ ] Context explains WHY a decision is needed - [ ] At least 2 options were considered - [ ] Decision clearly states the chosen option - [ ] Consequences include both good AND bad - [ ] Date and decision-makers are recorded (Standard+) --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/ddunnock) — claim your Tome and manage your conversions.