AgentSkillsCN

new-adr

创建新的架构决策记录（ADR）。适用于记录架构决策时使用，无论是独立决策，还是与已接受的提案相关联的决策。支持编号与交叉引用。ADR 在被接受后不可更改，仅允许在 superseded_by 字段中进行更新。

SKILL.md
--- frontmatter
name: new-adr
description: >
  Create a new Architectural Decision Record (ADR).
  Use when recording an architectural decision, either standalone
  or linked to an accepted proposal. Handles numbering and cross-referencing.
  ADRs are immutable after acceptance except for the superseded_by field.
allowed-tools: Read, Write, Bash(ls *), Bash(grep *)
user-invocable: true

New ADR — Architectural Decision Record Creation

Create a new ADR, either standalone or linked to an accepted proposal.

Command

code
/new-adr <short-title> [--from-proposal NNN] [--module <path>] [--root]

Arguments

ArgumentRequiredDescription
<short-title>YesShort, hyphenated title for the decision
--from-proposal NNNNoLink to an originating proposal (must be accepted)
--module <path>NoTarget module path
--rootNoCreate at repo root level

Workflow

With --from-proposal NNN

  1. •

    Parse arguments. Extract title, proposal number, and target.

  2. •

    Locate and verify the proposal. Find proposal NNN and verify its status is accepted. If not accepted, report: "Cannot link ADR to proposal NNN: proposal has status '<status>'. Only accepted proposals can be linked."

  3. •

    Get next sequence number. Run:

    bash
    bash scripts/next-number.sh --dir <target-decisions-dir>
  4. •

    Create the ADR file. Read templates/decision.md and create <target>/NNN-<short-title>.md.

  5. •

    Populate frontmatter:

    FieldValue
    titleDerived from short title
    numberNNN from step 3
    statusproposed
    authorGit user name or prompt
    createdToday's date
    originating_proposalThe proposal number
    superseded_bynull
  6. •

    Pre-populate from proposal. Copy relevant context from the proposal to seed the ADR's Context section.

  7. •

    Identify related architecture docs that should reference this ADR once accepted.

Without --from-proposal (standalone)

  1. •Parse arguments. Extract title and target.
  2. •Get next sequence number.
  3. •Create ADR from template with originating_proposal: null.
  4. •Confirm creation.

Supersession Handling

After creating a new ADR, prompt the user:

"Does this ADR supersede an existing ADR? (enter number or skip)"

If the user provides a number:

  1. •Locate the existing ADR.
  2. •Update its superseded_by frontmatter field to the new ADR's number. (This is the one permitted mutation on an accepted ADR.)
  3. •Set the new ADR's references to mention the superseded record.

ADR Immutability Reminder

Once an ADR is accepted, it is immutable. The only permitted change is setting superseded_by when a new ADR supersedes it. To change a decision, create a new ADR.

Templates

  • •templates/decision.md — ADR template (copy of scaffold/templates/core/decision.md)

Scripts

  • •scripts/next-number.sh — Determines the next NNN sequence number