Translation Comparison - develop-adr

An Architecture Decision Record documents a significant technical decision along with its context and consequences. ADRs capture the "why" behind architectural choices so future team members understand the reasoning . especially important when they question why something was done a particular way. This skill follows Michael Nygard's lightweight ADR format.

架构决策记录（ADR）用于记录重要技术决策及其背景与后果。ADR捕捉架构选择背后的“原因”，以便未来团队成员理解决策依据——尤其当他们质疑某项工作为何采用特定方式完成时，这一点至关重要。本技能遵循Michael Nygard提出的轻量级ADR格式。

When to Use

使用场景

Making significant technical decisions that affect system architecture
Choosing between technology options (frameworks, databases, services)
Establishing patterns that future development should follow
Documenting the rationale for constraints or non-obvious approaches
Preserving institutional knowledge about past decisions

做出影响系统架构的重要技术决策时
在多种技术选项（框架、数据库、服务）间进行选择时
制定未来开发应遵循的模式时
记录约束条件或非直观方案的理由时
留存关于过往决策的机构知识时

Instructions

操作步骤

When asked to create an ADR, follow these steps:

Assign a Number and Title ADRs are numbered sequentially (ADR-001, ADR-002, etc.) for easy reference. The title should be a short noun phrase describing the decision, like "Use PostgreSQL for order data" or "Adopt React for frontend."
Set the Status New ADRs start as "Proposed." After team review, they become "Accepted," "Deprecated," or "Superseded by ADR-XXX." Status changes should be tracked.
Describe the Context Explain the circumstances that led to this decision. What problem are you solving? What forces are at play (technical constraints, team expertise, timeline, cost)? This section should help a reader who wasn't there understand why this decision was needed.
State the Decision Clearly articulate what you decided. Use active voice: "We will use..." rather than "It was decided..." Be specific about what is and isn't included in the decision.
Document the Consequences List the outcomes of this decision . positive, negative, and neutral. Good ADRs are honest about trade-offs. What becomes easier? What becomes harder? What new constraints or options does this create?

当被要求创建ADR时，请遵循以下步骤：

分配编号与标题 ADR按顺序编号（如ADR-001、ADR-002等），便于查阅。标题应为简短的名词短语，描述决策内容，例如“使用PostgreSQL存储订单数据”或“采用React开发前端”。
设置状态 新创建的ADR初始状态为“提议中（Proposed）”。经团队评审后，状态可变为“已接受（Accepted）”、“已弃用（Deprecated）”或“被ADR-XXX取代（Superseded by ADR-XXX）”。状态变更需进行跟踪。
描述背景 说明导致该决策的环境情况。要解决什么问题？存在哪些影响因素（技术约束、团队专业能力、时间线、成本）？此部分应帮助未参与决策的读者理解为何需要做出该决策。
陈述决策 清晰阐明所做的决策。使用主动语态：“我们将使用……”而非“已决定……”。明确说明决策包含和不包含的内容。
记录后果 列出该决策带来的所有结果——积极、消极和中性的。优质的ADR会坦诚地记录权衡关系。哪些事情会变得更简单？哪些会更困难？该决策会带来哪些新的约束或选择？

Output Format

输出格式

Use the template in

references/TEMPLATE.md

to structure the output.

使用

references/TEMPLATE.md

中的模板构建输出内容。

Quality Checklist

质量检查清单

Before finalizing, verify:

Title is a short, descriptive noun phrase
Status is clearly indicated (Proposed/Accepted/Deprecated/Superseded)
Context explains why this decision was needed
Decision is stated clearly in active voice
Consequences include both positive and negative outcomes
ADR can stand alone without requiring other documents

最终定稿前，请验证以下内容：

标题是简短且具描述性的名词短语
状态已明确标注（提议中/已接受/已弃用/已取代）
背景部分解释了为何需要该决策
决策内容以主动语态清晰陈述
后果部分包含积极和消极结果
ADR可独立存在，无需依赖其他文档

See

references/EXAMPLE.md

for a completed example.

完整示例请查看

references/EXAMPLE.md

。

develop-adr

Original

Translation

Architecture Decision Record (ADR)

架构决策记录（ADR）