adr

分类: 数据库与数据存储 | 上传者: joestump | 下载: 0 | 版本: v1.0（最新）
使用 MADR 格式创建新的架构决策记录 (ADR)。当用户想要记录架构决策、说“创建 ADR”、“我们需要 ADR”或讨论应记录的决策时使用。
更新日志: Source: GitHub https://github.com/joestump/claude-plugin-sdd
目录结构

当前层级: tree/main/skills/adr/
📄 SKILL.md 8.5 KB
SKILL.md

---
name: adr
description: Create a new Architecture Decision Record (ADR) using MADR format. Use when the user wants to document an architectural decision, says "create an ADR", "we need an ADR for", or discusses a decision that should be recorded.
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Task, WebFetch, WebSearch, TeamCreate, TeamDelete, TaskCreate, TaskUpdate, TaskList, TaskGet, SendMessage, AskUserQuestion
argument-hint: [short description of the decision] [--review] [--module <name>]
---

# Create an Architecture Decision Record (ADR)

You are creating a new ADR using the MADR (Markdown Architectural Decision Records) format.

## Process

<!-- Governing: ADR-0016 (Workspace Mode), SPEC-0014 REQ "Artifact Path Resolution" -->

0. **Resolve artifact paths**: Follow the **Artifact Path Resolution** pattern from `references/shared-patterns.md` to determine the ADR directory. If `$ARGUMENTS` contains `--module <name>`, resolve paths relative to that module. The resolved ADR directory is referred to as `{adr-dir}` below.

1. **Determine the next ADR number**: Scan `{adr-dir}` for existing `ADR-XXXX-*.md` files and increment to the next number. Start at ADR-0001 if none exist. Create `{adr-dir}` if it does not exist. If `$ARGUMENTS` is empty (ignoring flags like `--review` and `--module`), use `AskUserQuestion` to ask the user what decision they want to document.

2. **Choose drafting mode**: Check if `$ARGUMENTS` contains `--review`.

   **Default (no `--review`)**: Single-agent mode. Research the codebase (read relevant files, understand the current architecture), draft the ADR directly, self-review against the architect's checklist in the Rules section, then write the file.

   **With `--review`**: Team review mode.
   - Tell the user: "Creating a drafting team to write and review the ADR. This takes a minute or two."
   - Create a Claude Team with `TeamCreate` to draft and review the ADR:
     - Spawn a **drafter** agent (`general-purpose`) to write the ADR based on the user's description: `$ARGUMENTS`
     - Spawn an **architect** agent (`general-purpose`) to review the drafter's output for completeness, accuracy, and adherence to MADR format
     - The architect MUST review and approve the ADR before it is finalized
     - The drafter should research the codebase (read relevant files, understand the current architecture) before writing
     - If `TeamCreate` fails, fall back to single-agent mode: draft the ADR directly, then self-review against the architect's checklist in the Rules section before writing.

3. **Write the ADR** to `{adr-dir}/ADR-XXXX-short-title.md`

4. **Clean up** the team when done (if `--review` was used).

5. **Summarize** what happened (files created, decision documented, review outcome).

6. **Suggest next steps**: After summarizing, tell the user:
   - "To formalize requirements from this decision, run: `/sdd:spec {suggested capability name}`"
   - "The spec skill can also break requirements into trackable issues (Beads, GitHub, or Gitea) for sprint planning."

7. **CLAUDE.md integration**: Check if this is the first ADR (i.e., `{adr-dir}` was just created or contains only this new file). If so:
   - Check if a `CLAUDE.md` exists at the module root (or project root for single-module projects)
   - If it exists, check if it already references the ADR directory
   - If no reference exists, ask the user: "I can add an Architecture Context section to your CLAUDE.md so future sessions know about your decisions. Shall I?"
   - If the user says yes, append an `## Architecture Context` section with `- Architecture Decision Records are in {adr-dir}`
   - If `CLAUDE.md` doesn't exist, suggest creating one

### Team Handoff Protocol (only for `--review` mode)

Follow the standard team handoff protocol from the plugin's `references/shared-patterns.md`. The drafter writes the ADR; the architect reviews against the Rules checklist below.

## MADR Template

```markdown
---
status: proposed
date: {YYYY-MM-DD}
decision-makers: {list}
# Optional graph edges (per ADR-0023 / SPEC-0018). All fields are lists of artifact IDs.
# Only include the fields that apply; omit unused fields entirely. Forward-only:
# inverse edges (superseded-by, governed-by, implemented-by, etc.) are derived by
# /sdd:graph at build time and MUST NOT be authored.
# supersedes: [ADR-XXXX]              # hard replacement; target moves to status: superseded
# extends: [ADR-XXXX]                 # builds on without replacing
# enables: [ADR-XXXX]                 # this decision unblocks another
# governs: [SPEC-XXXX]                # specs this decision governs
# related: [ADR-XXXX]                 # weak association, no semantic claim
---

# ADR-XXXX: {short title, representative of solved problem and found solution}

## Context and Problem Statement

{Describe the context and problem statement in 2-3 sentences. Articulate the problem as a question if possible.}

## Decision Drivers

* {driver 1, e.g., a force, facing concern}
* {driver 2}

## Considered Options

* {option 1}
* {option 2}
* {option 3}

## Decision Outcome

Chosen option: "{option}", because {justification}.

### Consequences

* Good, because {positive consequence}
* Bad, because {negative consequence}

### Confirmation

{How will compliance/implementation be confirmed?}

## Pros and Cons of the Options

### {Option 1}

{Description or pointer to more information.}

* Good, because {argument a}
* Good, because {argument b}
* Neutral, because {argument c}
* Bad, because {argument d}

### {Option 2}

{Description or pointer to more information.}

* Good, because {argument a}
* Bad, because {argument b}

## Architecture Diagram

```mermaid
{Mermaid diagram illustrating the architecture, decision flow, or component relationships.
Use flowchart, sequence, or C4 diagrams as appropriate.}
```

## More Information

{Additional context, links to related ADRs, references.}
```

## Rules

- ADR numbers MUST be sequential and zero-padded to 4 digits: ADR-0001, ADR-0002, etc.
- MUST include at least 2 considered options with substantive pros and cons for each
- Status starts as `proposed` -- the user decides when to mark `accepted`
- Self-review (default) or architect review (`--review`) MUST check for:
  - Completeness of all required sections (Context, Options, Outcome, Pros/Cons)
  - Realistic and balanced pros/cons (not just cheerleading the chosen option)
  - Clear decision rationale that explains "why this over alternatives"
  - Correct MADR structure and frontmatter
- Keep the title short and descriptive
- Focus on the "why" -- what problem does this solve and why this solution?
- Reference existing ADRs if this supersedes or relates to them
- Every ADR SHOULD include at least one Mermaid diagram illustrating the architecture or decision flow. Use flowchart, sequence, or C4 diagrams as appropriate.

## Graph Edge Frontmatter (per ADR-0023 / SPEC-0018)

<!-- Governing: ADR-0023 (Frontmatter DAG and /sdd:graph Skill), SPEC-0018 REQ "Frontmatter Edge Schema" -->

ADRs MAY declare relationships to other artifacts via optional frontmatter fields. All edge fields MUST be lists of artifact IDs (e.g., `[ADR-0008, ADR-0009]`). All edge fields are OPTIONAL — an ADR with no declared edges is valid.

| Field | Meaning | Example |
|-------|---------|---------|
| `supersedes` | Hard replacement — the referenced ADR moves to status `superseded` | `supersedes: [ADR-0003]` |
| `extends` | Builds on without replacing | `extends: [ADR-0008, ADR-0009]` |
| `enables` | Unblocks a downstream decision | `enables: [ADR-0016]` |
| `governs` | Names specs this decision governs | `governs: [SPEC-0007, SPEC-0010]` |
| `related` | Weak association, no semantic claim | `related: [ADR-0010]` |

**Forward-only convention.** Only forward edges are authored. Reverse edges (`superseded-by`, `governed-by`, `enabled-by`, `extended-by`) are derived by `/sdd:graph` at build time and MUST NOT appear in frontmatter — the graph builder will reject them with a warning. See `references/shared-patterns.md` § "Graph Edge Resolution" for the full forward→inverse derivation table.

**Cross-module edges (workspace mode).** When referencing artifacts in another module, use the quoted `[module]/ID` syntax: `governs: ["[api]/SPEC-0001"]`. The unquoted form `[[api]/SPEC-0001]` parses as YAML nested lists and will be rejected.

**When to add edges.** Add edges as the relationship becomes structurally meaningful — typically at the same time you would have written "Related: ADR-XXXX" in `## More Information`. Backfilling existing ADRs is supported via `/sdd:graph backfill`, which proposes edges parsed from prose for per-file review.
登录后下载/点赞/收藏 ❤ 9 | ★ 0
adr

目录结构

SKILL.md

举报内容

提示
