Back to Details

adr-drafting

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ADR Drafting

ADR 起草

Creates new Architecture Decision Record (ADR) documents for major architectural choices so teams can keep a clear history of why important technical decisions were made.
为重大架构选择创建新的架构决策记录（ADR）文档，以便团队能够清晰留存重要技术决策的制定原因。

Overview

概述

This skill helps create a new ADR from discovery to final markdown file. It confirms the decision details, inspects the repository for any existing ADR conventions, and drafts a new ADR with the standard sections 
Title
, 
Status
, 
Context
, 
Decision
, and 
Consequences
.
When the repository does not already have an ADR convention, default to storing ADRs in 
docs/architecture/adr
and use a zero-padded filename such as 
0001-use-postgresql-for-primary-database.md
.
See 
references/template.md
for the default ADR template and 
references/examples.md
for example ADRs and naming patterns.
本技能可辅助完成从信息收集到最终生成markdown文件的全流程ADR创建工作。它会确认决策详情，检查代码仓库中现有的ADR规范，并按照标准章节 
Title
、
Status
、
Context
、
Decision
、
Consequences
起草新的ADR。
如果仓库中尚未制定ADR规范，默认将ADR存储在 
docs/architecture/adr
路径下，并使用补零的文件名格式，例如 
0001-use-postgresql-for-primary-database.md
。
默认ADR模板可查看 
references/template.md
，ADR示例和命名模式可查看 
references/examples.md
。

When to Use

适用场景

Use this skill when a user or agent has decided on a meaningful architectural change and needs to document the rationale, chosen direction, and trade-offs in a new Architecture Decision Record. It fits requests such as creating an ADR, documenting an architecture decision, writing a decision record, or preserving the project history behind an important technical choice.
当用户或Agent已经确定要进行一项重要的架构变更，需要在新的架构决策记录中记录决策依据、选定方案以及权衡因素时使用本技能。适用于以下类型的请求：创建ADR、记录架构决策、编写决策记录、留存重要技术选择背后的项目历史。

Instructions

使用说明

Phase 1: Confirm the ADR inputs

阶段1：确认ADR输入信息

Ask the user for the minimum information needed to draft a new ADR:
  1. Decision title
  2. Decision status (
    Proposed
    by default if not yet finalized)
  3. Context: the problem, constraints, or forces driving the decision
  4. Decision: the chosen approach
  5. Consequences: what becomes easier, harder, riskier, or more expensive
  6. Confirm that this request is for a new ADR, not for editing an existing ADR
  7. Confirm the desired repository language if documentation language is unclear
  8. Confirm whether any existing ADR naming convention must be preserved
If the user actually wants to update an existing ADR, change statuses in older ADRs, or manage supersession links, explain that this skill only drafts new ADR documents and ask whether they want to proceed with a new record instead.
向用户询问起草新ADR所需的最少信息：
  1. 决策标题
  2. 决策状态（如果尚未最终确定，默认为 
    Proposed
    ）
  3. 上下文：驱动该决策的问题、约束或影响因素
  4. 决策：选定的实现方案
  5. 影响：哪些工作会变得更简单、更困难、风险更高或是成本更高
  6. 确认本次请求是要创建新ADR，而非编辑现有ADR
  7. 如果文档语言不明确，确认期望的仓库文档语言
  8. 确认是否需要遵守任何现有的ADR命名规范
如果用户实际想要更新现有ADR、修改旧ADR的状态，或是管理替代关系链接，请说明本技能仅负责起草新ADR文档，并询问用户是否改为创建新的记录。

Phase 2: Discover ADR conventions in the repository

阶段2：探查仓库中的ADR规范

Inspect the repository before drafting:
  1. Search for likely ADR locations such as: 
    • docs/architecture/adr
    • docs/adr
    • adr
    • architecture/adr
  2. If ADR files already exist, read one to three examples to infer:
    • numbering format
    • filename pattern
    • title format
    • language and tone
  3. If no ADR directory exists, recommend 
    docs/architecture/adr
  4. Determine the next ADR number from existing files when possible
  5. If no prior ADR exists, start with 
    0001
Preferred default naming when no convention exists:
  • Directory: 
    docs/architecture/adr
  • Filename: 
    NNNN-short-kebab-title.md
  • Title: 
    # ADR-NNNN: <Decision Title>
起草前先检查代码仓库：
  1. 搜索可能的ADR存放路径，例如： 
    • docs/architecture/adr
    • docs/adr
    • adr
    • architecture/adr
  2. 如果已经存在ADR文件，读取1-3个示例以推断：
    • 编号格式
    • 文件名模式
    • 标题格式
    • 语言和措辞风格
  3. 如果不存在ADR目录，推荐使用 
    docs/architecture/adr
  4. 尽可能根据现有文件确定下一个ADR编号
  5. 如果此前没有ADR，从 
    0001
    开始编号
没有现有规范时的首选默认命名规则：
  • 目录：
    docs/architecture/adr
  • 文件名：
    NNNN-short-kebab-title.md
  • 标题：
    # ADR-NNNN: <Decision Title>

Phase 3: Draft the ADR

阶段3：起草ADR

Create a draft using the standard structure:
markdown
undefined
使用标准结构创建草稿：
markdown
undefined

ADR-NNNN: Decision Title

ADR-NNNN: Decision Title

Status

Status

Proposed
Proposed

Context

Context

What problem, constraints, or trade-offs led to this decision?
What problem, constraints, or trade-offs led to this decision?

Decision

Decision

What architectural choice was made?
What architectural choice was made?

Consequences

Consequences

What becomes easier, harder, riskier, or more expensive because of this decision?

Drafting rules:

- Keep the title specific and decision-oriented
- Capture enough context to explain *why* the decision was needed
- Record the chosen direction clearly and directly
- Include both positive and negative consequences when known
- Do not invent rationale, constraints, or outcomes that the user did not provide
- If critical information is missing, insert concise placeholders or ask follow-up questions before finalizing
What becomes easier, harder, riskier, or more expensive because of this decision?

起草规则：

- 标题要具体，以决策为导向
- 留存足够的上下文以说明*为什么*需要做出该决策
- 清晰直接地记录选定的方案
- 已知的正面和负面影响都要包含
- 不要虚构用户未提供的决策依据、约束或结果
- 如果缺少关键信息，插入简洁的占位符，或是在最终定稿前询问后续问题补充信息

Phase 4: Review the draft with the user

阶段4：与用户一起审核草稿

Before writing files, present:
  • proposed file path
  • proposed title
  • ADR status
  • a concise preview of the drafted sections
Ask for approval before creating the file. If the user wants adjustments, revise the draft first.
写入文件前，先展示以下内容：
  • 建议的文件路径
  • 建议的标题
  • ADR状态
  • 已起草章节的简明预览
创建文件前先征求用户同意，如果用户需要调整，先修改草稿。

Phase 5: Create the ADR file

阶段5：创建ADR文件

After approval:
  1. Create the ADR directory if it does not exist
  2. Write the ADR markdown file using the repository's established pattern when available
  3. Preserve the user's wording for decision rationale as much as possible while keeping the document concise
  4. Report the final file path and summarize what was created
  5. Stop after creating the new ADR file so the skill remains focused on a single new decision record
获得批准后：
  1. 如果ADR目录不存在则创建该目录
  2. 尽可能遵循仓库已有的模式写入ADR markdown文件
  3. 在保持文档简洁的同时，尽可能保留用户对决策依据的原始表述
  4. 告知最终的文件路径，总结已创建的内容
  5. 创建完新ADR文件后即终止流程，确保本技能专注于单条新决策记录的创建

Examples

示例

Example 1: New database decision

示例1：新数据库决策

User request: "Create an ADR for moving from SQLite to PostgreSQL"
Expected flow:
  1. Confirm the title, status, reasons for the change, and expected consequences
  2. Check whether the repository already has ADR files
  3. Draft a new ADR in the existing convention or default to 
    docs/architecture/adr/0001-move-to-postgresql.md
  4. Ask for approval before writing the file
用户请求： "Create an ADR for moving from SQLite to PostgreSQL"
预期流程：
  1. 确认标题、状态、变更原因和预期影响
  2. 检查仓库是否已有ADR文件
  3. 按照现有规范起草新ADR，没有规范则默认生成 
    docs/architecture/adr/0001-move-to-postgresql.md
  4. 写入文件前征求用户同意

Example 2: New service boundary

示例2：新服务边界

User request: "Document the decision to split billing into a dedicated service"
Expected flow:
  1. Ask for the architectural context and why the current design is insufficient
  2. Confirm the chosen boundary and the operational consequences
  3. Draft a new ADR with the standard sections
  4. Create the file only after user approval
See 
references/examples.md
for longer ADR examples.
用户请求： "Document the decision to split billing into a dedicated service"
预期流程：
  1. 询问架构上下文以及当前设计不足的原因
  2. 确认选定的边界和运营影响
  3. 按照标准章节起草新ADR
  4. 仅在获得用户批准后创建文件
更长的ADR示例可查看 
references/examples.md
。

Best Practices

最佳实践

  • Keep each ADR focused on one architectural decision
  • Match existing repository naming, numbering, and writing style when ADRs already exist
  • Prefer concise explanations over long narratives
  • Capture trade-offs honestly, including downsides and new risks
  • Default the status to 
    Proposed
    unless the user confirms another state
  • Use the repository's preferred documentation language when it is clear
  • 每条ADR仅聚焦于一项架构决策
  • 如果仓库中已有ADR，要匹配现有命名、编号和写作风格
  • 优先使用简洁的解释而非长篇叙述
  • 如实记录权衡因素，包括缺点和新增风险
  • 除非用户确认其他状态，否则默认状态为 
    Proposed
  • 明确的情况下使用仓库偏好的文档语言

Constraints and Warnings

约束和注意事项

  • This skill is for new ADR creation only
  • Do not update existing ADR files, status histories, or supersession chains
  • Do not fabricate missing rationale or consequences
  • Do not force 
    docs/architecture/adr
    if the repository already uses another ADR location
  • Ask clarifying questions whenever the decision, context, or consequences are too vague to document responsibly
  • 本技能是仅用于创建新ADR
  • 不要更新现有ADR文件、状态历史或替代关系链
  • 不要虚构缺失的决策依据或影响
  • 如果仓库已经使用其他ADR存放路径，不要强制使用 
    docs/architecture/adr
  • 当决策、上下文或影响过于模糊无法可靠记录时，询问澄清问题