---
name: arch-design
description: 澄清并记录领域模型、模块边界、职责分配、依赖方向、关键接口、数据流和迁移方案。当新功能的技术方案不显然，或用户要求架构优化、领域建模、改善领域模型、重新划分职责或边界、调整分层与依赖、规划架构演进时使用。
---

# 架构设计

`arch-design` 是技术方案澄清技能。它既服务新功能，也服务现有架构和领域模型的主动优化。目标是在实现前把“系统如何表达需求”说清楚，形成便于人评审的设计依据，而不是替模型补一套架构教材。

三类产物各有边界：

| 阶段 | 澄清内容 |
|---|---|
| `spec-design` | 为什么做、用户可观察的行为和验收契约 |
| `arch-design` | 领域概念、职责、模块边界、依赖方向、关键接口、数据流和技术质量目标 |
| 计划与 `incremental-impl` | 实施步骤、切片、顺序、分发和提交 |

## 什么时候使用

- 新功能跨模块、重划边界，或者技术方案仍需与人确认。
- 用户要求优化现有架构、重新分层、调整依赖或规划系统演进。
- 用户要求领域建模、改善领域模型，或概念、职责、不变量和生命周期尚未归位。
- 一个结构问题会同时影响多个模块、公共接口、关键数据流或长期演进成本。

以下情况退出：

- 产品语义、范围或用户可观察行为仍不清楚：回到 `spec-design`。
- 有明确问题验证路径的缺陷：先走 `systematic-debugging`。
- 只是模块内部的命名、嵌套、重复、死代码或局部搬移：交给 `code-simplify` 做代码简化。
- 调研后确认没有实质性的架构、领域模型或跨边界决策：说明理由，直接进入后续实现。

## 核心约束

1. **先澄清，再实现。** 不用代码草稿替代技术方案确认。
2. **区分产品决定与技术决定。** 架构澄清若暴露出未确定的产品语义或外部行为，回到需求规格补充；纯技术表达方式留在本技能中确认。
3. **从真实代码出发。** 阅读受影响代码、现有接口和数据流，不根据摘要想象当前结构。
4. **选择满足当前驱动的最简设计。** 抽象、接缝和新层级都要有当下成立的理由，不用假想需求证明复杂度。
5. **只比较真实选项。** 只有存在会显著改变成本、风险或行为保护方式的真实取舍时才给出多个候选；方向明确时直接给出推荐方案和理由。
6. **先总后分。** 先让评审者看懂当前系统和目标系统的全貌，再按需求主题逐项说明原始需求、设计、为什么和验证方式。

## 流程

### 1. 建立设计上下文

- 新功能先读 `spec.md`、`validation-contract.md`、适用的上级规范与已确认决定；现有系统直接读目标代码和相关测试。若用户没有说清目标范围，先确认要处理的模块、边界或具体结构问题，不猜测扫描区域。
- 写清当前结构、具体问题、设计目标和不做什么。领域模型优化要同时写清概念混乱、职责错位或不变量泄漏发生在哪里。
- 收集项目级架构规则：用 `git rev-parse --show-toplevel` 确认仓库根，读取 `<仓库根>/docs/rules/arch/` 下与本次设计相关的规则；再从每个受影响代码或规范路径向仓库根查找更近的 `docs/rules/arch/`。两层都读取，冲突时子包级规则优先，以离目标代码最近者为准；非 git 仓库时从目标路径向当前目录回退查找。没有相关规则时记录“无项目专属架构规则”。
- 调研后若没有实质性设计问题，执行退出条件，不制造架构流程。

### 2. 按条件唤醒设计工具

只读取本次问题需要的参考资料：

| 设计条件 | 参考资料 | 它提醒模型考虑什么 |
|---|---|---|
| 划分组件、包或功能模块 | `references/component-design.md` | 内聚、耦合、依赖方向和物理模块边界 |
| 设计公共接口、模块接缝或接口演进 | `references/interface-design.md` | 信息隐藏、契约形状、兼容性和错误语义 |
| 优化领域概念、职责、不变量或生命周期 | `references/domain-modeling.md` | 实体、值对象、聚合、领域服务、事件和状态模型 |
| 替换接口、实现、模块或遗留子系统 | `references/migration-strategies.md` | 显式切换、并行变更、抽象分支、绞杀榕和保护网 |

参考资料是工具箱，不是必做清单。读完只选能解决当前问题的兵器；不要为了展示知识把每种模式都塞进设计。

### 3. 澄清设计

至少明确：

- 当前问题、目标和非目标。
- 约束与不变量，包括现有行为、公共接口、平台限制和项目架构规则。
- 模型按作用范围放置：跨多个分项复用、或负责维持跨分项规则的模型放在总览；只服务单个分项的模型放在对应分项。共享模型保留模型总表，分项直接展开模型详情，不重复一张只有一两行的总表；一个模型只定义一次，其他位置引用。每个模型都要明确概念与职责、变更状态和代码或存储映射，并区分无独立代码实体的抽象概念与类、接口、文件、数据库对象等具体载体；需要时再逐项说明同一性判断、状态与存续范围，以及有效状态规则的成立边界。模型详情中的结构变更表只列新增、修改或删除，以及必须重点确认的字段、关系或约束，不复制完整字段清单。不涉及模型变化时明确跳过。
- 目标模块边界、依赖方向、关键接口和数据流。
- 按共享同一设计机制的需求主题组织分项；每项列出权威来源和条款，说明具体设计、代码落点、就地理由以及验证证据。为什么不单独成节：模型理由紧邻模型，接口理由紧邻接口，流程与边界理由紧邻图示说明。不要按接口、数据流、领域模型等技术类别把同一需求拆散。
- 涉及持久化结构时，解释每个非自明字段的业务含义，以及行粒度、主键、快照边界、版本位置、冗余列和索引等真实相关的结构性选择为什么成立；不为自明字段制造理由。
- 影响架构选择的技术质量目标及其设计响应；只选择当前问题真实需要的属性，不按通用清单机械填写。
- 现有系统的行为保护方式，以及迁移或回滚约束。
- 影响选择的少数真实驱动，例如简单性、影响范围、可测试性、可逆性、迁移成本或有明确预算的性能要求。

如果存在真实取舍，给出能成立的候选和具体后果，请用户决定会显著改变成本或风险的方向。若不存在真实取舍，直接推荐最简设计，不制造候选和选择步骤。

### 4. 写出可人工评审的设计

只要存在实质性的架构、领域模型或跨边界决策，默认按照 `references/arch-design-template.md` 写入 `docs/specs/<topic>/arch_design.md`。文档不仅保存设计，也让澄清结果在实现前经过人评审。

仅在以下情况跳过文档：

- 调研结果触发了前述退出条件；或
- 用户明确要求在对话内确认，不保留设计文件。

如果环境没有可写项目根或无法写入目标路径，报告阻塞并在对话中给出设计草稿，不把草稿当作已经确认的实施输入。

写作时以评审效率为准：先展示需要人确认的决定和主要影响，再按“现状概览 → 目标设计概览 → 分项设计 → 迁移 → 风险 → 技术质量目标 → 部署上线”展开；先明确怎么实现并盘点风险，再判断要重点关注哪些技术指标以及如何上线。只保留与本次设计有关的章节和图。当前和目标整体图默认使用业务含义帮助评审者建立全局心智模型，代码标识只作准确锚点；技术质量目标及其设计响应属于人工重点评审内容，不能只藏在约束、风险或实现说明中。

设计产物的代码实体命名同时适用于文字描述和图：已有模块、类、接口、方法或文件沿用仓库中的原始标识符；本次设计新增的实体沿用设计上下文中定义的标识符；同一实体在正文、标题、表格、接口草图、目录结构和图中保持一致，不为配合文档语言翻译名称；解释性文字可以跟随文档语言。

模型设计不要把业务语义、设计变更和代码或存储载体压进一个含混的“概念”列。跨多个分项的共享模型在总览定义并保留模型总表，只服务单个分项的本项模型在分项直接展开详情；模型详情说明职责、同一性、状态、规则和需要重点评审的结构变更。已有实体给出仓库相对路径，本次新增实体给出预计路径，没有独立代码载体时明确写为抽象概念。尚未决定是否落为代码实体的项目必须标为待确认，并进入人工评审重点。

涉及接口时写入承接它的所属分项，不另设全局接口章节；一个接口只在主要承接它的分项定义一次，其他分项引用。HTTP API 的请求、成功响应和错误响应 DTO 都必须用带逐行注释的 `jsonc` 完整展开，每个对象层级注明对应 DTO 及其新增、复用或修改状态，修改字段在字段行直接标出。非服务端工程也要为新增或改变的重要进程内接口简要写明函数或方法签名、输入、输出和失败语义，不枚举普通辅助函数。字段表不能替代 JSON，机器契约仍以项目的 OpenAPI 或其他接口定义产物为准。

跨职责数据流与必要图示放在分项的同一章节，不维护一份文字流程和另一份图。每张图后就地说明关键关系、为什么这样流转或划分边界，以及状态或事务安排为什么成立。

`references/arch-design-template.md` 是产物结构、字段语义、占位形态和排除项的唯一详细契约；本技能与各工具箱只保留流程、选择方法和导航，不重复维护模板细节。

### 5. 收口并交给人工评审

初稿完成后、交给用户前，执行三项闭环检查：

1. **需求闭环**：从 `spec.md`、`validation-contract.md`、上级规范、项目规则和已确认决定逐条反查；每条权威要求都要指向具体设计机制和正文位置，没有落点就补设计或标为待确认。
2. **理由闭环**：检查理由是否就地写在它解释的机制旁；模型重点检查职责边界、非自明字段与结构性选择，接口重点检查归属边界、形状、错误和兼容语义，流程图示重点检查流转、状态与事务安排，不能只列结果或集中补一节理由。
3. **影响闭环**：涉及删除或替换资产时，按 `references/migration-strategies.md` 从退场对象做反向引用闭包，逐路径列出删除、修改或保留项，不能用“对应模块”“相关测试”等概括措辞。

设计包含高影响、且作者难以仅靠当前上下文可靠自检的断言时，例如不可逆数据迁移、退场资产可能被活代码依赖或跨规范硬约束容易遗漏，在运行时支持的情况下增加一次全新上下文、只读的独立评审：只提供设计产物和权威依据清单，要求评审者逐断言回到当前代码核实。简单、低风险或已有机械验证充分覆盖的设计不强制增加评审；独立评审补充而不替代上述三项自检。

向用户讨论待确认项时，每轮只聚焦一个会改变设计的问题，使用业务语言说明决定、理由和后果；收到答案后同步更新正文与 `Human Decisions`，再进入下一项。

写完后返回文件路径，概括需要关注的决定和风险，等待用户明确评审确认。用户明确选择不落盘时，改为在对话中完整呈现同样的评审重点并记录确认结果。收到修改意见就更新设计；**实现前必须取得用户确认**，不能把沉默当作批准。

### 6. 交接

- 用户确认后，把设计文档或对话内已确认的设计交给计划阶段或 `incremental-impl`。
- 本技能不写实施步骤、切片顺序或代理分发方案。
- 现有系统重构在第一个结构性提交前要有行为保护网；保护网缺失时交给 `test-driven-development` 补足。
- `arch_design.md` 继续遵循仓库的临时规范生命周期：拉取请求就绪前晋升为稳定架构文档、归档到工作记录或删除，晋升与归档用 `documentation-management` 执行，不直接移动文件。昂贵且长期有效的决策可另交该技能固化为架构决策记录。

## 交接前检查

- [ ] 产品语义和技术决定没有混在一起。
- [ ] 设计建立在实际代码、约束和项目架构规则上。
- [ ] 当前与目标全貌已经说明，分项设计逐条写清原始需求、带就地理由的设计和验证方式。
- [ ] 每条权威要求都能指向具体设计机制；没有被标题、枚举值或一句概括代替。
- [ ] 领域概念、模块边界、依赖方向、关键接口和数据流按相关性说明清楚。
- [ ] 非自明字段与结构性选择有业务理由；接口放在所属分项，HTTP DTO 按层标出变更状态，重要进程内接口写清输入输出；流程与图示没有重复维护。
- [ ] 资产退场清单已经逐路径收敛，活代码依赖没有漏在删除范围之外。
- [ ] 影响架构选择的技术质量目标及其设计响应已单独呈现，并作为人工重点评审内容。
- [ ] 没有为凑流程制造候选或抽象。
- [ ] 设计文档或对话内已确认的设计突出了人工评审重点，并已取得用户明确确认。
- [ ] 没有夹带实施步骤和切片计划。