arch-design

架构设计

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

三类产物各有边界：

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

什么时候使用

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

以下情况退出：

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

核心约束

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

流程

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

仅在以下情况跳过文档：

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

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

写作时以评审效率为准：先展示需要人确认的决定和主要影响，再给支撑细节；只保留与本次设计有关的章节和图。技术质量目标及其设计响应属于人工重点评审内容，不能只藏在约束、风险或实现说明中。

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

5. 交接

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

交接前检查

• 产品语义和技术决定没有混在一起。
• 设计建立在实际代码、约束和项目架构规则上。
• 领域概念、模块边界、依赖方向、关键接口和数据流按相关性说明清楚。
• 影响架构选择的技术质量目标及其设计响应已单独呈现，并作为人工重点评审内容。
• 没有为凑流程制造候选或抽象。
• 设计文档或对话内已确认的设计突出了人工评审重点，并已取得用户明确确认。
• 没有夹带实施步骤和切片计划。