adr

atusy 的头像作者 atusy

管理架构决策记录和与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.md for the MADR structure (status, context, drivers, options, consequences)
  • Operations: See operations.md for directory discovery, naming conventions, commit integration, deprecation (_ prefix), and ADR-aligned development workflow
  • Queries: See queries.md for 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?"

  1. Discover ADR directory (see operations.md)
  2. Search for relevant ADRs by keyword/topic
  3. Summarize the decision and its rationale
  4. 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

  1. Check for existing ADRs on the topic (may need to supersede)
  2. Gather information through clarifying questions
  3. Draft ADR using template.md
  4. Save and commit (amend later if needed)

ADR-Aligned Development Mode

Trigger: Implementing features, making architectural changes, deviating from existing patterns

  1. Before implementation: Check for relevant ADRs
  2. During implementation: Reference ADR in commits
  3. On completion: Update ADR status (proposed → accepted)
  4. 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)