# Arch Design

> 涉及领域职责、模块边界、数据所有权、接口兼容或迁移等实质技术取舍，或用户要求架构设计与优化时使用。

- Skill: `ben2pc/arch-design` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add ben2pc/arch-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ben2pc/arch-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: ben2pc (https://skillmd.com/u/ben2pc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ben2pc/arch-design

---


# 架构设计

`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`。文档不仅保存设计，也让澄清结果在实现前经过人评审。

仅在以下情况跳过文档：

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

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

先展示需要人确认的决定和主要影响，再说明现状、目标及按需求主题组织的设计。理由就地放在对应模型、接口或图示旁，实际相关的质量风险与保障、可观测设计列为人工重点评审内容。

`references/arch-design-template.md` 是章节、模型表、接口展示、代码命名和图示的唯一详细契约；写作时读取，正文只保留当前设计相关的内容。用户选择对话内确认时，仍须提供足以评审的契约和理由，可省略文件排版。

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

初稿交付前统一核对以下三项；收到修改后，根据变化影响复核失效的设计与证据，不重复检查无关部分：

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

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

向用户讨论待确认项时，将前置条件已明确、彼此独立的决定同轮提出，最多三个且服从提问工具上限；依赖本轮答案的决定留到后续。用业务语言给出推荐、理由和主要后果，收到答案后同步更新正文与 `人工确认结果`。

返回文件路径或对话内设计，概括决定和风险，区分已有确认与新增待确认项。仅对尚未确认的实质决定等待用户评审；收到修改意见就更新设计及确认状态。**实现前必须取得用户确认**，不能把沉默当作批准。

### 6. 交接

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