arc42-documentation

arc42 架构文档

目的

按照成熟的 arc42 模板（https://arc42.org/）生成完整、结构化的架构文档。该模板包含 12 个标准章节，涵盖软件架构的各个方面，从利益相关者需求到技术实现细节。

何时使用此技能

• 启动需要全面架构文档的新项目
• 为缺少结构化架构描述的现有系统编写文档
• 为技术水平不同的利益相关者创建架构概览
• 为认证（例如 iSAQB）准备架构文档
• 在多个项目中建立一致的文档标准

arc42 模板概览

arc42 模板包含 12 个章节：

1. 引言与目标 - 需求概览、质量目标、利益相关者
2. 约束 - 技术和组织方面的限制
3. 上下文与范围 - 系统边界、外部接口
4. 解决方案策略 - 基本架构决策
5. 构建块视图 - 静态分解（组件、模块）
6. 运行时视图 - 动态行为（场景、工作流）
7. 部署视图 - 基础设施和技术环境
8. 跨领域概念 - 重复出现的模式和原则
9. 架构决策 - 包含理由的重要 ADR
10. 质量需求 - 质量树和场景
11. 风险与技术债务 - 已知问题和限制
12. 术语表 - 领域和技术术语

硬性规则

必须

• 使用 todo 工具跟踪 arc42 文档工作流的进度
• 文件操作优先使用 search/*、read/* 和 edit/* 工具，而非终端命令
• 在 docs/architecture/arc42/ 目录中创建文档
• 使用 templates/arc42-template.md 中提供的模板结构
• 填写全部 12 个章节（信息尚不可用时，将章节标记为“TBD”）
• 在第 9 节（架构决策）中引用现有 ADR
• 更新 docs/architecture.md，使其引用新的 arc42 文档
• 根据具体项目背景调整内容（删除模板套话）
• 使用 Mermaid 图表进行可视化展示（上下文、构建块、部署）
• 确保面向利益相关者的章节（1、3、10）便于非技术读者理解
• 使用编辑器工具而非 shell 命令，尽量减少终端审批
• 确保 arc42 文档与现有 ADR 和功能规格保持同步
• 信息缺失或不明确时，向用户请求澄清（一次只问一个问题）
• 所记录的所有需求、约束和质量目标都必须以实际规格或用户输入为依据

禁止

• 有可用的 edit/* 工具时，使用终端命令编辑文件
• 在多步骤工作流中跳过 todo 工具
• 将 arc42 帮助文本原封不动地复制到最终文档中
• 创建不增加价值、仅重复现有 ADR 内容的文档
• 跳过章节而不将其标记为“TBD”或“不适用”
• 用 arc42 取代代码级文档
• 为简单功能创建 arc42 文档（应改用标准 ADR）
• 编造或捏造需求、约束、质量目标或技术细节
• 有条件向用户澄清时，仍在信息不完整的情况下继续

操作

1. 初始化待办事项跟踪

使用 todo 工具创建待办事项列表，跟踪 arc42 工作流的进度：

• 评估文档范围
• 创建目录结构
• 根据模板生成 arc42 文档
• 填写核心章节（1、3、4、5）
• 添加可视化图表
• 链接现有 ADR
• 验证完整性
• 更新文档索引
• 提交文档

2. 评估文档范围

每次向维护者提出一个问题：

• 这是针对整个系统，还是特定子系统／功能？
• 是否有应在第 9 节中引用的现有 ADR？
• 需要什么详细程度（高层概述还是详细技术规范）？
• 主要利益相关者是谁（开发者、架构师、管理层）？

3. 创建目录结构

使用 edit/createFile 工具（而非终端命令）创建目录和初始文件。

4. 生成 arc42 文档

• 使用 read/* 工具读取 templates/arc42-template.md
• 使用 edit/createFile 在 docs/architecture/arc42/architecture.md 创建自定义版本
• 不要使用 cp 或 cat 等终端命令，优先使用编辑器工具

5. 填写核心章节（迭代进行）

完成每个章节后，更新待办事项列表。

按建议的顺序处理各章节：

1. 使用 search/* 工具在 docs/spec.md 和功能规范中查找相关内容
2. 从第 1 节（简介和目标）开始——最容易从 spec.md 中获取内容
3. 添加第 3 节（上下文和范围）——定义系统边界
4. 记录第 4 节（解决方案策略）——关键架构决策
5. 完成第 5 节（构建块视图）——组件结构
6. 根据可用信息填写其余章节

**渐进式方法：**可以先将章节标记为“待定”，之后再逐步补充。该文档是一个持续完善的成果。

使用 edit/editFiles 进行修改，不要使用终端文本编辑器或 sed/awk 命令。

6. 添加可视化图表

添加图表时更新待办事项。

针对关键章节，使用 edit/editFiles 创建 Mermaid 图表：

• **第 3 节：**上下文图（C4 第 1 层）
• **第 5 节：**组件图（C4 第 2／3 层）
• **第 6 节：**关键场景的时序图
• **第 7 节：**部署图

提交前使用 mcp-mermaid 工具预览图表。

7. 链接现有 ADR

完成后更新待办事项。

使用 search/codebase 查找所有符合 adr-*.md 模式的 ADR 文件，然后在**第 9 节（架构决策）**中：

• 列出所有现有 ADR
• 简要概述每项决策
• 链接到完整的 ADR 文件

使用 edit/editFiles 更新该章节。

8. 验证完整性

检查并核对待办事项列表：

• 全部 12 个章节均已存在（即使标记为待定）
• 至少第 1、3、4、5 节已填写有意义的内容
• 已包含上下文和构建块图表
• 词汇表包含领域专属术语
• 文档中不再保留 arc42 帮助文本

9. 更新文档索引

使用 edit/editFiles 在 docs/architecture.md 中添加 arc42 文档的引用：

## Comprehensive Architecture Documentation

For a complete architecture overview following the arc42 standard, see:
- [arc42 Architecture Documentation](architecture/arc42/architecture.md)

10. 提交文档

将待办事项标记为完成，然后仅使用终端执行 git 操作：

git add docs/architecture/arc42/ docs/architecture.md
git commit -m "docs: add arc42 architecture documentation"

维护指南

arc42 文档应当：

• **在以下情况更新：**发生重大架构变更、出现新的质量要求、识别出重要风险
• **进行评审：**在迭代规划或架构评审会议期间
• **进行版本管理：**提交更改时使用清晰的提交消息，并关联功能／ADR
• **持续完善：**将未完成的章节标记为“待定”，也比完全跳过文档记录要好

参考资料

资源	说明
arc42.org	arc42 官方网站，提供下载和示例
arc42 Docs	各章节的详细说明和实用建议
arc42 by Example	真实世界的架构文档示例
arc42 on GitHub	模板源代码仓库
iSAQB Curriculum	使用 arc42 的认证项目

成功技巧

1. 从小处着手：先填写第 1、3、4 节，再逐步扩展
2. 使用图示：一张好的上下文图胜过千言万语
3. 添加链接，不要重复：引用现有的 ADR，不要复制内容
4. 面向读者调整：根据利益相关者调整各节的详细程度
5. 保持内容最新：架构变更时更新，而不是定期更新
6. 使用版本控制：将文档与相关代码变更一并提交