ben2pc 架构设计
arch-design 是技术方案澄清技能。它既服务新功能，也服务现有架构和领域模型的主动优化。目标是在实现前把“系统如何表达需求”说清楚，形成便于人评审的设计依据，而不是替模型补一套架构教材。
三类产物各有边界：
| 阶段 | 澄清内容 |
|---|---|
spec-design |
为什么做、用户可观察的行为和验收契约 |
arch-design |
领域概念、职责、模块边界、依赖方向、关键接口、数据流和技术质量目标 |
计划与 incremental-impl |
实施步骤、切片、顺序、分发和提交 |
什么时候使用
- 新功能存在需要确认的职责边界、数据所有权、接口兼容或迁移形态决定。
- 用户要求优化现有架构、重新分层、调整依赖或规划系统演进。
- 用户要求领域建模、改善领域模型，或概念、职责、不变量和生命周期尚未归位。
- 结构选择会实质改变关键数据流、行为保护方式或长期演进成本。
以下情况退出：
- 产品语义、范围或用户可观察行为仍不清楚：回到
spec-design。 - 有明确问题验证路径的缺陷：先走
systematic-debugging。 - 只是模块内部的命名、嵌套、重复、死代码或局部搬移：交给
code-simplify做代码简化。 - 调研后确认沿用现有架构即可、没有实质性的架构或领域决定：说明理由，直接进入后续实现；跨多个文件或模块本身不触发完整设计。
核心约束
- 先澄清，再实现。 实质架构决定在实现前取得用户确认；复用对话中仍有效的已确认设计，只对新增或改变的实质决定重新确认，不用代码草稿替代确认。
- 区分产品决定与技术决定。 架构澄清若暴露出未确定的产品语义或外部行为，回到需求规格补充；纯技术表达方式留在本技能中确认。
- 从真实代码出发。 阅读受影响代码、现有接口和数据流，不根据摘要想象当前结构。
- 选择满足当前驱动的最简设计。 抽象、接缝和新层级都要有当下成立的理由，不用假想需求证明复杂度。
- 只比较真实选项。 只有存在会显著改变成本、风险或行为保护方式的真实取舍时才给出多个候选；方向明确时直接给出推荐方案和理由。
- 先总后分。 先让评审者看懂当前系统和目标系统的全貌，再按需求主题逐项说明原始需求、设计、为什么和验证方式。
流程
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. 收口并交给人工评审
初稿交付前统一核对以下三项；收到修改后，根据变化影响复核失效的设计与证据，不重复检查无关部分：
- 需求闭环：从
spec.md、validation-contract.md、上级规范、项目规则和已确认决定逐条反查；每条权威要求都要指向具体设计机制和正文位置，没有落点就补设计或标为待确认。 - 理由闭环：检查理由是否就地写在它解释的机制旁；模型重点检查职责边界、非自明字段与结构性选择，接口重点检查归属边界、形状、错误和兼容语义，流程图示重点检查流转、状态与事务安排，不能只列结果或集中补一节理由。
- 影响闭环：涉及删除或替换资产时，按
references/migration-strategies.md从退场对象做反向引用闭包，逐路径列出删除、修改或保留项，不能用“对应模块”“相关测试”等概括措辞。
设计包含高影响、且作者难以仅靠当前上下文可靠自检的断言时，例如不可逆数据迁移、退场资产可能被活代码依赖或跨规范硬约束容易遗漏，在运行时支持的情况下增加一次全新上下文、只读的独立评审：只提供设计产物和权威依据清单，要求评审者逐断言回到当前代码核实。简单、低风险或已有机械验证充分覆盖的设计不强制增加评审；独立评审补充而不替代上述三项自检。
向用户讨论待确认项时，将前置条件已明确、彼此独立的决定同轮提出，最多三个且服从提问工具上限；依赖本轮答案的决定留到后续。用业务语言给出推荐、理由和主要后果，收到答案后同步更新正文与 人工确认结果。
返回文件路径或对话内设计，概括决定和风险，区分已有确认与新增待确认项。仅对尚未确认的实质决定等待用户评审；收到修改意见就更新设计及确认状态。实现前必须取得用户确认，不能把沉默当作批准。
6. 交接
- 用户确认后，把设计文档或对话内已确认的设计交给计划阶段或
incremental-impl。 - 本技能不写实施步骤、切片顺序或代理分发方案。
- 现有系统重构在第一个结构性提交前，按
test-driven-development建立有效的行为保护证据。 arch_design.md继续遵循仓库的临时规范生命周期：拉取请求就绪前晋升为稳定架构文档、归档到工作记录或删除，晋升与归档用documentation-management执行，不直接移动文件。昂贵且长期有效的决策可另交该技能固化为架构决策记录。