adr
管理架构决策记录和与ADR一致的开发。当用户说"我们应该使用"、"让我们选择"、询问"我们为什么选择X?"、实现可能有ADR的功能、更新ADR状态或需要检查与现有决策的一致性时使用。
📖 中文导读:管理架构决策记录和与ADR一致的开发。当用户说"我们应该使用"、"让我们选择"、询问"我们为什么选择X?"、实现可能有ADR的功能、更新ADR状态或需要检查与现有决策的一致性时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: adr description: Manage Architecture Decision Records and ADR-aligned development. Use when user says "we should use", "let's go with", asks "why did we choose X?", implements a feature that may have an ADR, updates ADR status, or needs to check alignment with existing decisions.
INSTRUCTIONS
Manage Architecture Decision Records (ADRs) throughout their lifecycle: read existing decisions, write new ones, and ensure development aligns with documented decisions.
- Template: See
template.mdfor the MADR structure (status, context, drivers, options, consequences) - Operations: See
operations.mdfor directory discovery, naming conventions, commit integration, deprecation (_prefix), and ADR-aligned development workflow - Queries: See
queries.mdfor finding ADRs by topic, status, or relationship
Modes
Read Mode
Trigger: "why did we choose X?", "what's our approach to Y?", "is there an ADR for Z?"
- Discover ADR directory (see
operations.md) - Search for relevant ADRs by keyword/topic
- Summarize the decision and its rationale
- Note if the ADR is active, deprecated, or superseded
Write Mode
Trigger: "we should use", "let's go with", "I've decided to", trade-off discussions
- Check for existing ADRs on the topic (may need to supersede)
- Gather information through clarifying questions
- Draft ADR using
template.md - Save and commit (amend later if needed)
ADR-Aligned Development Mode
Trigger: Implementing features, making architectural changes, deviating from existing patterns
- Before implementation: Check for relevant ADRs
- During implementation: Reference ADR in commits
- On completion: Update ADR status (proposed → accepted)
- On deviation: Create superseding ADR, deprecate old one with
_prefix
Quality Checklist
Before finalizing an ADR:
- Title clearly states the decision (not the problem)
- Context explains WHY this decision is needed now
- At least 2 options were genuinely considered
- Decision drivers link to actual project constraints
- Consequences include both positive AND negative impacts
- Confirmation section describes how to validate the decision
Anti-Patterns
- Decision without options: Always document alternatives considered
- Vague consequences: Be specific about trade-offs
- Missing "why": The ADR should answer "why this, why now"
- Orphan ADRs: Link to related ADRs when relevant
- Stale ADRs: Update status when implemented or superseded
- Undocumented deviation: If you deviate from an ADR, create a new one
Reference
Based on MADR - Markdown Architectural Decision Records (Version 4.0, 2024)