arc42

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

arc42 — write or update architecture chapters

arc42 — 编写或更新架构文档章节

arc42 is a lightweight architecture documentation template with 12 chapters. Each chapter has a defined purpose; filling them in order produces a coherent architecture document a newcomer can read end-to-end.

arc42是一款轻量级架构文档模板，包含12个章节。每个章节都有明确的定位；按顺序填写这些章节，就能生成一份逻辑连贯的架构文档，新手可以从头读到尾轻松理解。

Before You Start

开始之前

The arc42 template (https://docs.arc42.org or a local copy under
```
docs/arc42/
```
).
```
docs/arc42/
```
or equivalent — the project's existing arc42 tree. Find with
```
find . -type d -name 'arc42*'
```
.
Root
```
CLAUDE.md
```
Architecture section — often duplicates chapter 5 content; sync as you edit.

If the project has no arc42 tree yet, confirm with the user that arc42 is the right framework before creating one. Alternatives: C4 model, minimal

ARCHITECTURE.md

, or a single page in the docs site.

arc42模板（可访问https://docs.arc42.org，或本地副本存放在`docs/arc42/`目录下）。
```
docs/arc42/
```
或同类目录——项目现有的arc42文档目录。可通过命令
```
find . -type d -name 'arc42*'
```
查找。
根目录下的
```
CLAUDE.md
```
中的架构部分——通常与第5章内容重复，编辑时需同步更新。

如果项目尚未创建arc42文档目录，请先与用户确认arc42是否为合适的框架，再进行创建。替代方案包括：C4模型、极简版

ARCHITECTURE.md

，或文档站点中的单页文档。

The 12 chapters and what goes where

12个章节及其内容定位

#	Chapter	What belongs here	Quality criterion
1	Introduction and Goals	Top 3 business goals, top 3 quality attributes, key stakeholders	Any newcomer understands WHY this system exists in 5 minutes
2	Constraints	Technical, organizational, and regulatory constraints imposed from outside	Reader knows which rules are non-negotiable
3	Context and Scope	System boundary: users, external systems, their interactions	Clear line between "our system" and "not our system"
4	Solution Strategy	The 5–10 load-bearing architectural decisions, with 1-line rationale each	Reader grasps the shape without reading chapters 5–10
5	Building Block View	Static structure: components and their relationships, at multiple zoom levels	A dev knows which component owns a given concern
6	Runtime View	Sequence diagrams for 3–5 important scenarios	Reader understands dynamic behavior for critical flows
7	Deployment View	Where the software runs, in what topology	On-call engineer knows what's where
8	Cross-cutting Concepts	Patterns applied across the system (auth, logging, error handling, i18n)	One place to learn "how we do X"
9	Architecture Decisions	ADRs — each an immutable record	Decisions are traceable with their context
10	Quality Requirements	Measurable quality attributes with scenarios	Quality goals are testable
11	Risks and Technical Debt	Known risks, debt items, mitigations	Team and sponsors see what's parked and why
12	Glossary	Terms with precise definitions	Ambiguous language has a single meaning

序号	章节	内容范畴	质量标准
1	引言与目标	前3项业务目标、前3项质量属性、关键利益相关者	任何新手都能在5分钟内理解该系统存在的原因
2	约束条件	来自外部的技术、组织和监管约束	读者清楚哪些规则是不可协商的
3	上下文与范围	系统边界：用户、外部系统及其交互关系	清晰划分“我们的系统”与“非我们的系统”的界限
4	解决方案策略	5-10项核心架构决策，每项配1行理由说明	读者无需阅读第5-10章就能把握架构整体轮廓
5	构建块视图	静态结构：组件及其关系，支持多层级缩放	开发人员能明确哪个组件负责特定功能
6	运行时视图	3-5个重要场景的序列图	读者理解关键流程的动态行为
7	部署视图	软件的运行位置及拓扑结构	值班工程师清楚各个组件的部署位置
8	跨领域概念	系统中通用的设计模式（认证、日志、错误处理、国际化i18n）	一站式了解“我们如何实现X”
9	架构决策	ADRs——每项决策都是不可变更的记录	决策可追溯其背景信息
10	质量需求	可衡量的质量属性及对应场景	质量目标可被测试验证
11	风险与技术债务	已知风险、债务项及缓解措施	团队和项目资助方清楚待处理事项及其原因
12	术语表	带有精确定义的术语	模糊术语有唯一明确的含义

Step 1: find the project's arc42 tree

步骤1：查找项目的arc42文档目录

bash

find . -type d -name 'arc42*' -not -path '*/node_modules/*'

bash

find . -type d -name 'arc42*' -not -path '*/node_modules/*'

Common: docs/arc42/ OR documentation/arc42/

常见位置：docs/arc42/ 或 documentation/arc42/


Inside the tree, you usually find one file per chapter: `01-introduction.md` … `12-glossary.md`. Some projects use full chapter names in filenames.


在该目录内，通常每个对应一个文件：`01-introduction.md` … `12-glossary.md`。部分项目会在文件名中使用完整的章节名称。

Step 2: pick the chapter

步骤2：选择目标章节

Ask: what is the user asking for, or what did this PR change?

Business-goal shift → chapter 1.
New external dependency or boundary change → chapter 3.
A load-bearing decision → chapter 4 (summary) + chapter 9 (full ADR via
```
document-decision
```
).
New major component or refactored structure → chapter 5.
New critical user flow → chapter 6.
Infra change → chapter 7.
New pattern applied codebase-wide → chapter 8.
A decision recorded → chapter 9.
Quality goal changed or measured → chapter 10.
New risk discovered → chapter 11.

思考：用户的需求是什么？或者本次PR修改了什么？

业务目标变更 → 第1章。
新增外部依赖或边界变更 → 第3章。
核心架构决策 → 第4章（摘要） + 第9章（通过
```
document-decision
```
撰写完整ADR）。
新增主要组件或重构结构 → 第5章。
新增关键用户流程 → 第6章。
基础设施变更 → 第7章。
全代码库应用新设计模式 → 第8章。
记录决策 → 第9章。
质量目标变更或已量化 → 第10章。
发现新风险 → 第11章。

Step 3: write or edit

步骤3：编写或编辑

Writing discipline per chapter

各章节的撰写规范

Chapter 1 — avoid aspirational prose. "We want to be the best" is not a goal; "p99 latency under 500ms for tier-1 queries" is.

Chapter 4 — 5–10 decisions, one line of rationale each. If you're writing paragraphs here, move them into ADRs (chapter 9) and summarize.

Chapter 5 — use diagrams (Mermaid, PlantUML, SVG). Text alone loses the structure. Label every component and arrow.

Chapter 6 — sequence diagrams. Three to five scenarios is enough; more dilutes. Pick scenarios that exercise chapter 5's interactions.

Chapter 7 — include a real deployment diagram with the actual hosts/containers/services, not an idealized one.

Chapter 8 — one subsection per concern: auth, logging, config, error handling, i18n, caching. Name files if a concern has a canonical implementation (

src/lib/errors/index.ts

Chapter 9 — one file per ADR, linked from the chapter index. Use

document-decision

for the ADR body.

Chapter 10 — quality scenarios in the form "when X happens, system responds with Y within Z." Non-testable quality goals are wishes.

Chapter 11 — risks have likelihood + impact + mitigation. "Might become slow" is not a risk — "if monthly active users exceed 100k, database writes will bottleneck; mitigation: shard user table" is.

Chapter 12 — one line per term, ordered alphabetically.

第1章 — 避免空泛的口号式表述。“我们想成为最佳”不是目标；“一级查询的p99延迟低于500ms”才是明确的目标。

第4章 — 5-10项决策，每项配1行理由说明。如果在此处撰写大段文字，请将内容移至ADR（第9章）并进行摘要总结。

第5章 — 使用图表（Mermaid、PlantUML、SVG）。仅用文字无法清晰呈现结构。为每个组件和箭头添加标签。

第6章 — 使用序列图。3-5个场景足够；过多会分散重点。选择能体现第5章组件交互的场景。

第7章 — 包含真实的部署图，展示实际的主机/容器/服务，而非理想化的示意图。

第8章 — 每个关注点对应一个小节：认证、日志、配置、错误处理、国际化i18n、缓存。如果某个关注点有标准实现文件，请注明文件名（如

src/lib/errors/index.ts

）。

第9章 — 每个ADR对应一个文件，并在章节索引中添加链接。使用

document-decision

撰写ADR主体内容。

第10章 — 质量场景需采用“当X发生时，系统在Z时间内做出Y响应”的格式。无法测试的质量目标只是愿望。

第11章 — 风险需包含可能性+影响+缓解措施。“可能会变慢”不是风险——“如果月活跃用户超过10万，数据库写入将出现瓶颈；缓解措施：对用户表进行分片”才是明确的风险描述。

第12章 — 每个术语对应一行内容，按字母顺序排列。

General editing discipline

通用编辑规范

Link between chapters. Chapter 5 references chapter 4's decisions. Chapter 6 references chapter 5's components. Chapter 11 references the chapters whose risks it tracks.
Keep each chapter self-contained at the top. A reader jumping directly to chapter 7 should still orient themselves.
No orphan chapters. If a chapter has < 30 lines and wouldn't grow, it's not worth its own file — fold it into an adjacent chapter.

章节间建立链接。第5章引用第4章的决策。第6章引用第5章的组件。第11章引用其跟踪风险对应的章节。
各章节开头保持自洽。直接跳至第7章的读者仍能快速定位自身位置。
避免孤立章节。如果某章节内容不足30行且无扩展空间，则无需单独成文件——可合并至相邻章节。

Step 4: keep CLAUDE.md in sync

步骤4：同步CLAUDE.md内容

The root

CLAUDE.md

"Architecture" section is a condensed summary of arc42 chapters 3–5. When you edit those chapters substantially, re-scan

CLAUDE.md

for drift:

bash

undefined

根目录下

CLAUDE.md

的“Architecture”部分是arc42第3-5章的浓缩摘要。当你大幅修改这些章节时，请重新检查

CLAUDE.md

是否存在内容偏差：

bash

undefined

Verify

验证

bash

undefined

bash

undefined

The edited chapter has the right section structure

编辑后的章节具有正确的结构

(most chapters have sub-headings like ### Building blocks, ### Interfaces)

（大多数章节包含### 构建块、### 接口等子标题）

grep -c '^##? ' docs/arc42/<chapter>.md

Expected: several — chapter content has subsections.

预期结果：多个匹配项——章节内容包含子小节。

Links between chapters resolve

章节间的链接可正常跳转

grep -oE '[([^]]+)](([^)]+.md[^)]*))' docs/arc42/<chapter>.md | while read link; do

Relative path check

target=$(echo "$link" | sed -E 's/.(([^)]+))./\1/' | cut -d'#' -f1) [ -n "$target" ] && [ ! -f "docs/arc42/$target" ] && echo "BROKEN: $link" done

grep -oE '[([^]]+)](([^)]+.md[^)]*))' docs/arc42/<chapter>.md | while read link; do

检查相对路径

target=$(echo "$link" | sed -E 's/.(([^)]+))./\1/' | cut -d'#' -f1) [ -n "$target" ] && [ ! -f "docs/arc42/$target" ] && echo "BROKEN: $link" done

Docs site builds (project-specific command)

文档站点可正常构建（项目特定命令）

undefined

undefined

Common Mistakes

常见错误

Mistake	Correction
Filling every chapter because the template has 12	Chapters are optional if empty. Better to have 8 load-bearing chapters than 12 skeleton-filled ones.
Treating chapter 4 and chapter 9 as the same	Chapter 4 is a summary (5–10 one-liners). Chapter 9 is ADRs (full immutable records). Both exist.
Chapter 5 with no diagram	The static structure is a diagram first, prose second. Add one (Mermaid or PlantUML).
Quality goals as adjectives	"Fast" is not a quality goal. Write it as a scenario: "when user clicks X, UI responds within 100ms at p95".

错误	修正方案
因模板有12章就填满所有章节	若章节为空则可省略。与其有12个空架子章节，不如有8个有实际内容的核心章节。
将第4章和第9章视为同一内容	第4章是摘要（5-10条单行内容）。第9章是ADRs（完整的不可变更记录）。两者功能不同，需分别维护。
第5章未包含图表	静态结构应以图表为主，文字为辅。添加图表（Mermaid或PlantUML格式）。
质量目标仅用形容词描述	“快速”不是质量目标。应写成场景：“当用户点击X时，UI在p95情况下100ms内响应”。