Back to Details

architecture-decisions

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Architecture Decisions

架构决策

Value: Communication -- architecture decisions recorded before implementation ensure every contributor (human or agent) understands why the system is shaped the way it is. Decisions made in silence are decisions lost.
价值： 沟通——在实施前记录架构决策，确保每位贡献者（人类或Agent）都能理解系统为何采用当前的设计形态。默默做出的决策最终会被遗忘。

Purpose

目标

Teaches the agent to record architecture decisions before implementing them, maintain a living architecture document, and facilitate structured decision-making. Prevents the common failure mode where architecture emerges accidentally and rationale is lost.
指导Agent在实施前记录架构决策，维护动态架构文档，并推动结构化决策制定。避免架构偶然形成、决策依据丢失这一常见的失败模式。

Practices

实践方法

Record Decisions Before Implementation

实施前记录决策

Never implement a structural change without first recording the decision. An architecture decision is any choice that affects system structure, technology stack, domain boundaries, integration patterns, or cross-cutting concerns.
  1. Identify the decision: what problem motivates this choice?
  2. Document alternatives: at least two realistic options with tradeoffs
  3. Record the chosen approach and its consequences
  4. Only then proceed to implementation
Do:
  • Record decisions when they are made, while context is fresh
  • One decision per record -- keep them atomic
  • State decisions in active voice: "We will use PostgreSQL for event storage"
  • Acknowledge negative consequences honestly
Do not:
  • Document decisions after implementation as retroactive justification
  • Bundle multiple decisions into one record
  • Omit alternatives -- a decision without alternatives is not a decision
在未记录决策的情况下，绝不要进行结构性变更。架构决策指任何会影响系统结构、技术栈、领域边界、集成模式或横切关注点的选择。
  1. 明确决策：是什么问题促使做出该选择？
  2. 记录备选方案：至少两个具备权衡分析的可行选项
  3. 记录选定的方案及其影响
  4. 完成以上步骤后再开展实施
需遵循：
  • 在决策做出时立即记录，确保上下文清晰
  • 每条记录对应一个决策——保持原子性
  • 用主动语态表述决策："我们将使用PostgreSQL存储事件"
  • 坦诚记录负面后果
切勿：
  • 在实施后才记录决策，作为事后的合理性说明
  • 将多个决策合并到一条记录中
  • 遗漏备选方案——没有备选方案的选择不构成决策

Maintain the Living Architecture Document

维护动态架构文档

docs/ARCHITECTURE.md
is the single authoritative source for current system architecture. It describes WHAT the architecture IS, not WHY it became that way (the WHY lives in decision records).
Structure:
markdown
undefined
docs/ARCHITECTURE.md
是当前系统架构的唯一权威来源。它描述架构是什么，而非架构为何变成这样（后者记录在决策记录中）。
结构：
markdown
undefined

Architecture

Architecture

Overview

Overview

High-level system description
High-level system description

Key Decisions

Key Decisions

Current architectural choices (link to decision records)
Current architectural choices (link to decision records)

Components

Components

Major system components and their responsibilities
Major system components and their responsibilities

Patterns

Patterns

Patterns in use (event sourcing, CQRS, etc.)
Patterns in use (event sourcing, CQRS, etc.)

Constraints

Constraints

Current constraints and known tradeoffs

Update this document whenever a decision changes the architecture. Keep it
current -- a stale architecture document is worse than none.
Current constraints and known tradeoffs

每当决策导致架构变更时，更新此文档。确保文档内容实时更新——过时的架构文档不如没有文档。

Use ADR-as-PR Format

使用ADR作为PR格式

When the project uses GitHub, architecture decision records live as PR descriptions, not standalone files. This gives decisions a natural lifecycle:
  • Open PR = proposed decision, under review
  • Merged PR = accepted decision
  • Closed PR = rejected decision
  • New PR with "Supersedes #N" = revised decision
Each ADR PR:
  1. Branches independently from main (
    adr/<slug>
    )
  2. Updates 
    docs/ARCHITECTURE.md
    with the current decision
  3. You MUST use 
    references/adr-template.md
    for the PR description as the full decision record
  4. Gets labeled 
    adr
    for discoverability
When GitHub PRs are not available, record the architecture decision in the commit message of the commit that updates 
docs/ARCHITECTURE.md
. Use the same template structure (Context, Decision, Alternatives, Consequences). The commit message becomes the decision record, and 
git log -- docs/ARCHITECTURE.md
becomes the decision history.
当项目使用GitHub时，架构决策记录以PR描述的形式存在，而非独立文件。这让决策拥有自然的生命周期：
  • 打开PR = 待评审的拟议决策
  • 合并PR = 已接受的决策
  • 关闭PR = 已拒绝的决策
  • 带有"Supersedes #N"的新PR = 修订后的决策
每个ADR PR需满足：
  1. 从主分支独立创建分支（命名为
    adr/<slug>
    ）
  2. 更新
    docs/ARCHITECTURE.md
    以反映当前决策
  3. 必须使用
    references/adr-template.md
    作为PR描述，作为完整的决策记录
  4. 添加
    adr
    标签以便查找
当无法使用GitHub PR时，在更新
docs/ARCHITECTURE.md
的提交信息中记录架构决策。使用相同的模板结构（背景、决策、备选方案、影响）。提交信息将成为决策记录，而
git log -- docs/ARCHITECTURE.md
则成为决策历史。

Facilitate Decisions Systematically

系统化推动决策制定

When multiple architectural decisions are needed (new project, major redesign):
  1. Inventory decision points across categories: technology stack, domain boundaries, integration patterns, cross-cutting concerns
  2. Present the agenda to the human for review before facilitating
  3. For each decision: present context, present 2-4 options with tradeoffs, let the human choose, record immediately
  4. Never batch -- record each decision individually so they can be reviewed and accepted independently
当需要做出多项架构决策时（新项目、重大重构）：
  1. 梳理决策点：涵盖技术栈、领域边界、集成模式、横切关注点等类别
  2. 提前提交议程：在推动决策前先提交给人类评审
  3. 针对每个决策：说明背景、提供2-4个带有权衡分析的选项、由人类做出选择、立即记录决策
  4. 切勿批量处理：逐个记录每个决策，以便独立评审和接受

Review for Architectural Alignment

评审架构一致性

Before approving implementation work, verify it aligns with documented architecture:
  • Does it follow patterns documented in ARCHITECTURE.md?
  • Does it respect domain boundaries?
  • Does it introduce new dependencies or patterns not yet decided?
  • If it conflicts, record a new decision before proceeding
在批准实施工作前，验证其是否与已记录的架构保持一致：
  • 是否遵循
    ARCHITECTURE.md
    中记录的模式？
  • 是否尊重领域边界？
  • 是否引入了尚未确定的新依赖或新模式？
  • 如果存在冲突，需先记录新决策再继续推进

Enforcement Note

实施说明

This skill provides advisory guidance. It instructs the agent to record decisions before implementation but cannot mechanically prevent implementation without a decision record. The agent follows these practices by convention. If you observe implementation proceeding without a decision record, point it out.
本Skill提供指导性建议。它指导Agent在实施前记录决策，但无法机械阻止未记录决策就开展的实施工作。Agent需依照惯例遵循这些实践。如果您发现未记录决策就进行实施的情况，请及时指出。

Verification

验证

After completing work guided by this skill, verify:
  • Every structural change has a corresponding decision record
  • docs/ARCHITECTURE.md
    reflects the current architecture
  • Each decision record states context, alternatives, and consequences
  • No decision was recorded retroactively after implementation
  • Decision records are atomic (one decision per record)
If any criterion is not met, record the missing decision before proceeding.
在完成本Skill指导的工作后，需验证以下内容：
  • 每一项结构性变更都有对应的决策记录
  • docs/ARCHITECTURE.md
    反映当前架构
  • 每条决策记录都说明了背景、备选方案和影响
  • 没有在实施后追溯记录决策
  • 决策记录具备原子性（每条记录对应一个决策）
如果任何一项标准未满足，需先记录缺失的决策再继续推进。

Dependencies

依赖关系

This skill works standalone. For enhanced workflows, it integrates with:
  • event-modeling: Completed event models surface the decision points that need architectural choices (technology, boundaries, integration patterns)
  • domain-modeling: Domain model constraints inform bounded context boundaries and aggregate design decisions
  • code-review: Reviewers verify implementation aligns with documented architecture decisions
Missing a dependency? Install with:
npx skills add jwilger/agent-skills --skill event-modeling
本Skill可独立使用。为增强工作流，它可与以下Skill集成：
  • event-modeling： 已完成的事件模型会凸显需要进行架构选择的决策点（技术、边界、集成模式）
  • domain-modeling： 领域模型约束会影响限界上下文边界和聚合设计决策
  • code-review： 评审人员需验证实施是否与已记录的架构决策保持一致
缺少依赖？通过以下命令安装：
npx skills add jwilger/agent-skills --skill event-modeling