Back to Details

adr-writer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ADR Writer

ADR 编写器

Captures architecture decisions in a lightweight, structured format that preserves context, rationale, alternatives, and consequences. Produces numbered ADR documents with proper status lifecycle — preventing the "why did we do it this way?" problem when revisiting decisions months later.
以轻量、结构化的格式记录架构决策，保留决策背景、理由、替代方案以及影响。生成带有编号和完整状态生命周期的ADR文档——避免数月后回顾决策时出现“我们当时为什么这么做？”的问题。

Reference Files

参考文件

FileContentsLoad When
references/adr-template.md
Standard ADR template with field explanations and examplesAlways
references/status-lifecycle.md
Status transitions, supersession rules, deprecation processADR references existing decisions
references/context-capture.md
Techniques for eliciting and documenting decision contextComplex or multi-stakeholder decision
references/alternatives-analysis.md
Framework for evaluating and documenting rejected alternativesMultiple options being considered
文件路径内容说明加载时机
references/adr-template.md
带有字段说明和示例的标准ADR模板始终加载
references/status-lifecycle.md
状态转换、替代规则、废弃流程当ADR引用现有决策时
references/context-capture.md
挖掘和记录决策背景的技巧处理复杂或多方参与的决策时
references/alternatives-analysis.md
评估和记录被否决替代方案的框架存在多个待选方案时

Prerequisites

前置条件

  • A decisions directory (typically 
    docs/adr/
    or 
    docs/decisions/
    )
  • Understanding of the decision being made (may require clarifying questions)
  • 决策文档目录（通常为 
    docs/adr/
    或 
    docs/decisions/
    ）
  • 对需记录的决策有清晰认知（可能需要进一步澄清细节）

Workflow

工作流程

Phase 1: Identify the Decision

阶段1：明确决策内容

  1. What choice was made? — Extract the core architectural decision. If the user describes a problem, help them articulate the decision that resolves it.
  2. Is this decision-worthy? — ADRs are for decisions that:
    • Affect system structure (component boundaries, data flow, API design)
    • Are hard to reverse (technology choice, database schema, protocol)
    • Have non-obvious tradeoffs (multiple viable alternatives)
    • Will be questioned later (the "why" will be forgotten)
  3. What triggered this decision? — New requirement, performance issue, scaling concern, security audit finding, tech debt, team growth.
  1. 核心决策是什么？ — 提取架构决策的核心内容。如果用户描述的是问题，帮助他们明确解决该问题的具体决策。
  2. 该决策是否值得记录？ — ADR适用于以下类型的决策：
    • 影响系统结构（组件边界、数据流、API设计）
    • 难以逆转（技术选型、数据库 schema、协议选择）
    • 存在非显性权衡（多个可行替代方案）
    • 未来可能被质疑（“为什么这么做”的理由会被遗忘）
  3. 决策触发因素是什么？ — 新需求、性能问题、扩展需求、安全审计发现、技术债务、团队扩张等。

Phase 2: Capture Context

阶段2：记录决策背景

Document the forces that shaped this decision:
  1. Requirements — What functional or non-functional requirements drive this?
  2. Constraints — What limits the solution space? (budget, timeline, team expertise, existing infrastructure, regulatory requirements)
  3. Current state — What exists today? What is the pain point?
  4. Stakeholders — Who is affected by this decision? Who needs to agree?
记录影响决策的各类因素：
  1. 需求 — 哪些功能或非功能需求驱动了该决策？
  2. 约束条件 — 哪些因素限制了可选方案？（预算、时间线、团队技能、现有基础设施、合规要求）
  3. 当前状态 — 现有系统是什么样的？存在哪些痛点？
  4. 相关方 — 该决策会影响哪些角色？需要哪些角色的认可？

Phase 3: Enumerate Alternatives

阶段3：枚举替代方案

For each alternative considered:
  1. Name it clearly — "PostgreSQL" not "Option A"
  2. List concrete pros — Specific, measurable benefits
  3. List concrete cons — Specific, measurable drawbacks
  4. State the rejection reason — Why this alternative was not chosen. Be specific: "Does not support our required throughput of 10K ops/sec" not "Too slow."
针对每个考虑过的替代方案：
  1. 清晰命名 — 例如使用“PostgreSQL”而非“方案A”
  2. 列出具体优势 — 可衡量的明确收益
  3. 列出具体劣势 — 可衡量的明确弊端
  4. 说明否决理由 — 明确说明未选择该方案的原因，例如：“不支持我们所需的10K次/秒跨分区事务处理”而非“太慢了”。

Phase 4: Document the Decision

阶段4：记录最终决策

State the chosen option and why it was selected given the context and constraints. The decision should follow logically from the context + alternatives analysis.
明确说明选定的方案，以及结合背景和约束条件选择该方案的理由。决策应能从背景分析和替代方案对比中自然推导得出。

Phase 5: Project Consequences

阶段5：预期影响分析

Document what this decision makes easier and harder:
  1. Positive consequences — What improves?
  2. Negative consequences — What tradeoffs are accepted? What tech debt is incurred?
  3. Neutral consequences — Side effects that are neither good nor bad.
记录该决策带来的便利和不便：
  1. 积极影响 — 哪些方面会得到改善？
  2. 消极影响 — 接受了哪些权衡？产生了哪些技术债务？
  3. 中性影响 — 既无明显益处也无明显弊端的副作用。

Phase 6: Assign Metadata

阶段6：添加元数据

  1. Number — Sequential: ADR-001, ADR-002, etc. Check existing ADRs for the next number.
  2. Status — Initial status is usually "Proposed" or "Accepted"
  3. Date — Date the ADR was written
  4. Author — Who authored this ADR
  5. Supersedes/Superseded-by — Link to related ADRs if this replaces an earlier decision
  1. 编号 — 按顺序编号：ADR-001、ADR-002等。需查阅现有ADR确定下一个编号。
  2. 状态 — 初始状态通常为“提议中”或“已通过”
  3. 日期 — ADR编写日期
  4. 作者 — 编写该ADR的人员
  5. 替代/被替代 — 若该决策替代了之前的决策，关联对应的ADR文档

Output Format

输出格式

text
undefined
text
undefined

ADR-{NNN}: {Descriptive Title}

ADR-{NNN}: {描述性标题}

Status: {Proposed | Accepted | Deprecated | Superseded by ADR-XXX} Date: {YYYY-MM-DD} Author: {name} Supersedes: {ADR-XXX (if applicable)}
状态: {提议中 | 已通过 | 已废弃 | 被ADR-XXX替代} 日期: {YYYY-MM-DD} 作者: {姓名} 替代: {ADR-XXX（如有）}

Context

背景

{What situation requires a decision? What constraints exist? What forces are at play? Write in present tense — describe the situation as it exists at decision time.}
{什么场景需要做出该决策？存在哪些约束条件？有哪些影响因素？ 使用现在时态撰写——记录决策时的实际场景。}

Decision

决策

{State the decision clearly and concisely. "We will use X for Y because Z." One to three sentences. The reader should understand the decision without reading the rest of the document.}
{清晰、简洁地说明决策内容。例如：“我们将使用X解决Y问题，因为Z。” 1-3句话即可。读者无需阅读文档其他部分就能理解决策内容。}

Alternatives Considered

考虑过的替代方案

{Alternative 1 Name}

{替代方案1名称}

  • Pros: {specific benefits}
  • Cons: {specific drawbacks}
  • Rejected because: {concrete, specific reason tied to context}
  • 优势: {具体收益}
  • 劣势: {具体弊端}
  • 否决理由: {与背景相关的具体原因}

{Alternative 2 Name}

{替代方案2名称}

  • Pros: {specific benefits}
  • Cons: {specific drawbacks}
  • Rejected because: {concrete, specific reason tied to context}
  • 优势: {具体收益}
  • 劣势: {具体弊端}
  • 否决理由: {与背景相关的具体原因}

Consequences

影响

Positive

积极影响

  • {Concrete benefit 1}
  • {Concrete benefit 2}
  • {具体收益1}
  • {具体收益2}

Negative

消极影响

  • {Concrete tradeoff 1 — acknowledged and accepted}
  • {Technical debt incurred — with plan to address if applicable}
  • {明确接受的权衡1}
  • {产生的技术债务——如有应对计划请说明}

Neutral

中性影响

  • {Side effect that is neither positive nor negative}
  • {既无积极也无消极的副作用}

References

参考资料

  • {Link to related issue, discussion, document, or prior ADR}
undefined
  • {相关议题、讨论、文档或历史ADR的链接}
undefined

Calibration Rules

校准规则

  1. Context is king. The Context section is the most important part. A decision without context is just an assertion. Future readers need to understand WHY, not just WHAT.
  2. Specific rejection reasons. "Not suitable" is not a rejection reason. "Does not support transactions across partitions, which we need for order processing" is.
  3. Honest consequences. Every decision has downsides. If the Negative section is empty, the analysis is incomplete. Push the user to articulate tradeoffs.
  4. Present tense for context. Write the Context section in present tense — it captures the world as it was when the decision was made.
  5. One decision per ADR. If multiple decisions are interrelated, write separate ADRs and cross-reference them. Do not bundle unrelated decisions.
  6. Immutable after acceptance. Accepted ADRs are not edited. If a decision changes, write a new ADR that supersedes the old one. This preserves the historical record.
  1. 背景是核心 — 背景部分是ADR最重要的内容。缺乏背景的决策只是一个断言。未来的读者需要了解“为什么”，而非仅仅“是什么”。
  2. 具体的否决理由 — “不合适”不是有效的否决理由。“不支持订单处理所需的跨分区事务”才是。
  3. 坦诚的影响分析 — 每个决策都有弊端。如果消极影响部分为空，说明分析不完整。需要引导用户明确权衡点。
  4. 背景使用现在时态 — 背景部分使用现在时态撰写——记录决策做出时的真实场景。
  5. 一个ADR对应一个决策 — 若多个决策相互关联，编写独立的ADR并交叉引用。不要将无关决策合并到一个ADR中。
  6. 通过后不可修改 — 已通过的ADR不得编辑。若决策发生变更，编写新的ADR替代旧文档。这样可以保留完整的历史记录。

Error Handling

错误处理

ProblemResolution
User cannot articulate alternativesHelp them brainstorm by asking: "What else could you have done? What did you consider and reject?"
Decision is trivial (no real alternatives)Suggest it doesn't need an ADR. ADRs are for non-obvious decisions with tradeoffs.
Decision already made, no context rememberedReconstruct context from code, PRs, commit history. Note reconstructed context as "best available."
Existing ADR numbering scheme unknownCheck 
docs/adr/
or 
docs/decisions/
. If no directory exists, suggest creating one and starting at 001.
Decision scope is too broadSplit into multiple focused ADRs. One for the database choice, one for the caching strategy, etc.
问题场景解决方法
用户无法明确替代方案通过提问引导 brainstorm：“还有哪些其他可行方案？你们考虑过但否决了哪些选项？”
决策无关紧要（无实际替代方案）建议无需编写ADR。ADR适用于存在权衡的非显性决策。
决策已做出，但背景记忆模糊从代码、PR、提交历史中重构背景。注明重构的背景为“最佳可用信息”。
未知现有ADR编号规则检查 
docs/adr/
或 
docs/decisions/
目录。若不存在该目录，建议创建并从001开始编号。
决策范围过于宽泛拆分为多个聚焦的ADR。例如一个ADR记录数据库选型，另一个记录缓存策略等。

When NOT to Write an ADR

无需编写ADR的场景

Push back if:
  • The decision is easily reversible (library version, code formatting rules) — use a comment or config instead
  • The decision is a standard practice with no alternatives (use HTTPS, validate input) — not decision-worthy
  • The user wants to document implementation details — ADRs are for WHY decisions, not HOW implementations
  • The decision has already been superseded — write the new ADR, not the old one
遇到以下情况时建议不编写ADR：
  • 决策可轻松逆转（库版本选择、代码格式规则）——使用注释或配置文件记录即可
  • 决策是标准实践（使用HTTPS、输入验证）——无记录必要
  • 用户想记录实现细节——ADR用于记录“为什么”，而非“如何实现”
  • 决策已被替代——编写新的ADR替代旧文档即可，无需更新旧文档