adr-writer

分类: 内容与多媒体 | 上传者: govctl-org | 下载: 0 | 版本: v1.0（最新）
编写有效的架构决策记录。在以下情况下使用：(1) 创建新的 ADR，(2) 记录设计决策，(3) 用户提及 ADR、决策、权衡或替代方案
更新日志: Source: GitHub https://github.com/govctl-org/govctl
目录结构

当前层级: tree/main/.claude/skills/adr-writer/
📄 SKILL.md 6.8 KB
SKILL.md

---
name: adr-writer
description: "Write effective Architecture Decision Records. Use when: (1) Creating a new ADR, (2) Recording a design decision, (3) User mentions ADR, decision, trade-off, or alternatives"
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, TodoWrite
argument-hint: [optional ADR topic]
---

# ADR Writer

Write ADRs that clearly capture context, decisions, and consequences.

## Invocation Mode

This helper skill may be used standalone or by `/discuss`, `/gov`, `/spec`, or `/migrate`.
It is responsible for ADR content structure and quality, not ADR lifecycle verbs. Use `/spec` or `/gov` for `govctl adr accept`, `reject`, or `supersede`.

## Quick Reference

```bash
govctl adr new "<title>"
govctl adr set <ADR-ID> context --stdin <<'EOF'
context text
EOF
govctl adr set <ADR-ID> decision --stdin <<'EOF'
decision text
EOF
govctl adr set <ADR-ID> consequences --stdin <<'EOF'
consequences text
EOF
govctl adr add <ADR-ID> alternatives "Option: Description"
govctl adr add <ADR-ID> refs RFC-NNNN
```

## ADR Structure

Every ADR has three required fields and two optional fields:

### 1. Context (required)

Explain the situation that requires a decision. Structure:

> **Do NOT include `## Context` heading** — the renderer adds it automatically.

```markdown
[1-2 sentence summary of the situation]

### Problem Statement

What specific issue are we addressing?

### Constraints

What existing RFCs, ADRs, or technical limitations restrict our options?

### Options Considered

Brief overview (details go in the alternatives field).
```

**Key principle:** A reader 6 months from now must understand _why_ this decision was needed without asking anyone.

### 2. Decision (required)

State what was decided and why. Structure:

> **Do NOT include `## Decision` heading** — the renderer adds it automatically.

```markdown
We will **[action]** because:

1. **Reason one:** Explanation
2. **Reason two:** Explanation

### Implementation Notes

Specific guidance for implementing this decision.
```

**Key principle:** Lead with the decision, then justify. Don't bury the answer.

### 3. Consequences (required)

Honest accounting of trade-offs. Structure:

> **Do NOT include `## Consequences` heading** — the renderer adds it automatically.

```markdown
### Positive

- Benefit one
- Benefit two

### Negative

- Trade-off one (mitigation: ...)
- Trade-off two (mitigation: ...)

### Neutral

- Side effect that is neither positive nor negative
```

**Key principle:** Every decision has downsides. If your Negative section is empty, you haven't thought hard enough.

### 4. Alternatives (recommended)

Document options considered. Future readers need to know what was _not_ chosen and why.

**Extended structure per ADR-0027:**

    [[content.alternatives]]
    text = "Option A: Description"
    status = "rejected"
    pros = ["Advantage 1", "Advantage 2"]
    cons = ["Disadvantage 1"]
    rejection_reason = "Why this was not chosen"

**Field semantics:**

- `text` (required): Description of the alternative
- `status`: `considered` (default) | `accepted` | `rejected`
- `pros`: List of advantages
- `cons`: List of disadvantages
- `rejection_reason`: If rejected, explains why

**CLI commands:**

```bash
# Simple alternative
govctl adr add <ADR-ID> alternatives "Option A: Use PostgreSQL"

# With pros, cons, and rejection reason
govctl adr add <ADR-ID> alternatives "Option B: Use Redis" \
  --pro "Fast caching" --pro "Simple API" \
  --con "Additional infrastructure" \
  --reject-reason "Overkill for our scale"

# Edit nested fields after creation
govctl adr tick <ADR-ID> alternatives --at 0 -s rejected
govctl adr add <ADR-ID> alt[0].pros "New advantage"
govctl adr remove <ADR-ID> alt[0].cons "Outdated disadvantage"
```

**When to add pros/cons:**

- For significant decisions with multiple options
- When trade-offs are non-obvious
- To help future readers understand the evaluation process

### 5. References (recommended)

```bash
govctl adr add <ADR-ID> refs RFC-0001
govctl adr add <ADR-ID> refs ADR-0005
```

Link to artifacts that constrained or informed the decision. Use plain IDs (not `[[...]]` syntax) in the refs field.

## Validation and Handoff

- Run `govctl check` after substantive ADR edits
- Use `adr-reviewer` before acceptance or handoff
- Use `/spec` for ADR acceptance without implementation
- Use `/gov` when the ADR accompanies implementation-bearing work

## Writing Rules

### Quality Checklist

- **Context is complete.** Problem statement, constraints, and options are all present.
- **Decision is decisive.** Starts with "We will..." — not "We might..." or "We could...".
- **Consequences are honest.** Negative section is non-empty with mitigations.
- **Alternatives are documented.** For new decisions, include at least one rejected option with reason. For historical backfills, document rejected options when known; otherwise state that they were not recoverable.
- **References link to related artifacts.** Use `[[artifact-id]]` in content fields.

### Content Field Formatting

Use markdown within content fields. Wrap code/technical terms in backticks:

```
# Good
decision = "Use `HashMap<String, Vec<ClauseSpec>>` for clause storage"

# Bad — angle brackets break mdbook rendering
decision = "Use HashMap<String, Vec<ClauseSpec>> for clause storage"
```

## Rendering Rules

The renderer auto-generates structural elements from TOML metadata. **Do NOT include these in content fields:**

- `## Context`, `## Decision`, `## Consequences` headings — auto-generated for each section
- `## Alternatives Considered` heading — auto-generated if alternatives exist
- `### Option Name (status)` headings — auto-generated from `alternatives[].text` + `status`
- `- **Pros:**`, `- **Cons:**`, `- **Rejected because:**` — auto-generated from structured fields
- ADR title (`# ADR-NNNN: Title`) — auto-generated from metadata

Content fields should contain only the body prose and `[[...]]` references.

## Common Mistakes

| Mistake                               | Fix                                                      |
| ------------------------------------- | -------------------------------------------------------- |
| `## Context` in content field         | Don't — the renderer adds section headings automatically |
| Empty Negative section                | Every decision has trade-offs — document them            |
| No alternatives for a new ADR         | Add at least one rejected option                         |
| Historical ADR lacks rejected options | State that alternatives were not recoverable             |
| Vague context: "We need to decide"    | Specific: "RFC-0002 requires X but doesn't specify how"  |
| Decision buried in prose              | Lead with "We will **action**"                           |
| Missing refs                          | Link to RFCs/ADRs that constrain the decision            |
登录后下载/点赞/收藏 ❤ 102 | ★ 0
adr-writer

目录结构

SKILL.md

举报内容

提示
