跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
其他技能

adr

Document architectural decisions in standardized ADR format. This skill should be used when making significant technical decisions, choosing between approaches, establishing patterns, or when other skills (create-plan, implement-plan, brainstorm) identify decisions that need documentation. Triggers on "document decision", "create ADR", "architectural decision", or automatically when invoked by other skills during planning and implementation.

mhylle · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add mhylle/claude-skills-collection --skill adr

技能说明


name: adr description: Document architectural decisions in standardized ADR format. This skill should be used when making significant technical decisions, choosing between approaches, establishing patterns, or when other skills (create-plan, implement-plan, brainstorm) identify decisions that need documentation. Triggers on "document decision", "create ADR", "architectural decision", or automatically when invoked by other skills during planning and implementation. argument-hint: "[decision-title?]"

Architectural Decision Records (ADR)

Contents

Reference files (open one when a step points to it):

  • references/adr-template.md: ADR-NNNN: [Title]
  • references/index-template.md: Architectural Decision Records

Document significant architectural and technical decisions in a standardized, searchable format optimized for LLM context efficiency.

Design Principles

Context Conservation

ADRs are designed for efficient LLM consumption:

  1. Small, focused files - One decision per ADR, minimal content
  2. Quick Reference block - First 5 lines summarize the entire ADR
  3. Central INDEX.md - Single file listing all ADRs with one-line summaries

LLM Reading Strategy

When consulting ADRs, follow this tiered approach:

TIER 1: Read INDEX.md (one file, all summaries)
        ↓ Identify potentially relevant ADRs
TIER 2: Read Quick Reference block only (first 10 lines of candidate ADRs)
        ↓ Confirm relevance
TIER 3: Read full ADR content (only when details are needed)

Implementation:

# Tier 1: Scan index
Read("docs/decisions/INDEX.md")

# Tier 2: Quick reference only (use limit parameter)
Read("docs/decisions/ADR-0001-title.md", limit=10)

# Tier 3: Full content (only if needed)
Read("docs/decisions/ADR-0001-title.md")

When to Use This Skill

Directly invoked when:

  • Making a significant technical decision
  • Choosing between architectural approaches
  • Establishing patterns or conventions
  • Documenting why a particular technology was selected

Automatically invoked by other skills when:

  • create-plan: Design decision is made in Phase 4
  • implement-plan: Mismatch discovered or architectural choice made during implementation
  • brainstorm: Key decisions identified during analysis

ADR Location and Naming

Directory: docs/decisions/

Naming Convention: ADR-NNNN-short-title.md

  • NNNN: Zero-padded sequential number (0001, 0002, etc.)
  • short-title: Lowercase, hyphenated description (max 50 chars)

Examples:

  • ADR-0001-use-jwt-for-authentication.md
  • ADR-0002-postgresql-over-mongodb.md
  • ADR-0003-event-sourcing-for-audit.md

Getting the Next ADR Number

Before creating an ADR, determine the next sequence number:

# Find highest existing ADR number
ls docs/decisions/ADR-*.md 2>/dev/null | sort -t- -k2 -n | tail -1 | grep -oP 'ADR-\K\d+' || echo "0000"

If no ADRs exist, start with 0001.

ADR Status Values

StatusMeaning
ProposedUnder consideration, not yet decided
AcceptedDecision made, ready for implementation
DeprecatedWas accepted, now superseded
SupersededReplaced by another ADR (link to replacement)

Creating an ADR

Required Information

Gather these inputs (ask user if not provided):

FieldDescriptionRequired
TitleShort, descriptive titleYes
ContextWhy is this decision needed?Yes
OptionsWhat alternatives were considered?Yes
DecisionWhat was decided?Yes
RationaleWhy this option?Yes
ConsequencesWhat are the implications?Yes
Related ADRsLinks to related decisionsIf applicable

ADR Template

Use this format (also in references/adr-template.md):

# ADR-NNNN: [Title]

> **Quick Reference** | Status: [Accepted] | Date: [YYYY-MM-DD]
> **Decision**: [One sentence: what was decided]
> **Context**: [One sentence: why this decision was needed]
> **Alternatives**: [Rejected options, comma-separated]
> **Impact**: [Key areas affected, comma-separated]

---

## Context

[2-3 sentences max. The problem or opportunity being addressed.]

## Decision

**We will use [chosen option].**

[1-2 sentences explaining the decision.]

## Alternatives Considered

| Option | Pros | Cons | Why Not |
|--------|------|------|---------|
| [Option A] | [Key pro] | [Key con] | [Brief reason] |
| [Option B] | [Key pro] | [Key con] | [Brief reason] |

## Consequences

- **Positive**: [Key benefit]
- **Negative**: [Key trade-off]
- **Requires**: [What must be done as a result]

## Related

- [ADR-XXXX](./ADR-XXXX-title.md): [Relationship]

Quick Reference Block (Mandatory)

The first 5 lines after the title form the Quick Reference block. This enables LLMs to assess relevance without reading the full document.

Format (must fit in ~5 lines):

> **Quick Reference** | Status: [Status] | Date: [Date]
> **Decision**: [One sentence summary of what was decided]
> **Context**: [One sentence on why this decision was needed]
> **Alternatives**: [Comma-separated list of rejected options]
> **Imp
阅读完整来源 ↗