| name | hf-design |
| description | 适用于需求规格已批准但设计尚未批准、或设计评审返回需修改/阻塞需修订的场景。不适用于规格仍是草稿/待批准（→ hf-specify）、设计已批准需拆任务（→ hf-tasks）、仅需执行设计评审（→ hf-design-review）、阶段不清或证据冲突（→ hf-workflow-router）。 |
HF 设计
把已批准规格转化为可评审的设计文档，说明"如何"实现，让后续任务规划与实现不再靠猜测推进。
职责边界：本 skill 只负责 架构 / 模块 / API 契约 / 数据模型 / 后端 NFR。若规格声明 UI surface，hf-ui-design 会被 hf-workflow-router 激活为 design stage 的 conditional peer，与本 skill 并行处理 IA / wireframe / 交互 / 视觉 / 前端 a11y / i18n / 响应式。两条 skill 独立起草、独立 review、联合进入 设计真人确认。详见 hf-workflow-router/references/ui-surface-activation.md。
Methodology
本 skill 融合以下已验证方法：
- ADR (Architecture Decision Records, Nygard format): 所有影响后续任务的关键决策用 ADR 格式记录，包含上下文、决策、后果与可逆性评估。详见
references/adr-template.md。
- C4 Model (Context-Container-Component-Code): 架构视图按 Context → Container → Component 层次递进，提供最少必要视图（逻辑架构、组件关系、关键交互），优先 Mermaid。
- Risk-Driven Architecture (Fairbanks): 架构投入按风险驱动——先识别哪些设计决策风险最高，对高风险决策投入更多分析和备选方案比较，而非均匀铺开。
- YAGNI + Complexity Matching: 决策必须由当前已确认需求驱动；架构复杂度匹配团队规模和系统规模（solo + 本地运行不引入微服务/消息队列）。
- ARC42 (partial): 设计文档结构覆盖 ARC42 核心维度：约束、决策、视图、风险/技术债务、 Glossary（通过 spec-template 衔接）。
- DDD Strategic Modeling（Phase 0 新增）: 进入 C4 视图前，先锁定 Bounded Context、Ubiquitous Language、Context Map，让边界先于结构。详见
references/ddd-strategic-modeling.md。
- DDD Tactical Modeling（Phase 0 新增）: 在战略建模之后、C4 Component 之前，回答每个 Bounded Context 内部的 Entity / Value Object / Aggregate / Repository / Domain Service / Application Service / Domain Event。让"写代码前要考虑好模式"落到领域语义驱动的选择上，而不是 GoF 直觉驱动。详见
references/ddd-tactical-modeling.md。
- Emergent vs Upfront Patterns（HF 立场，硬性约束）: 本 skill 只前置领域语义驱动的战术模式（Entity / VO / Aggregate / Repository / Domain Service / Application Service / Domain Event）；GoF 代码模式（Strategy / Factory / Adapter / Observer / Decorator / Builder / Singleton 等）刻意不在本 skill 前置决策——它们属于实现层 emergent 浮现，由
hf-test-driven-dev 在 REFACTOR 步按 Fowler 重构词汇（Replace Conditional with Polymorphism / Extract Factory Method / ...）浮现处理。强行前置等于 over-abstraction，违反 YAGNI 与 Clean Architecture dependency rule。理由：上游需求 / 真实接入点未稳定时锁定具体扩展点会让"灵活性"绑定到错误的轴上；TDD REFACTOR 阶段的 Two Hats 纪律保证了重构窗口存在；Fowler 重构词汇足以表达后期模式选择。
- Event Storming as spec→design bridge（Phase 0 新增）: 用事件视角把业务流程摊开，Big Picture / Process Modeling 两档按 profile 使用。详见
references/event-storming.md。
- Quality Attribute Scenarios（Phase 0 承接）: 承接
hf-specify 层的 QAS（ISO 25010 + Source/Stimulus/Environment/Response/Response Measure），把每条 QAS 映射到具体模块 / 机制 / observability / 验证。详见 references/nfr-checklist.md。
- STRIDE 轻量威胁建模（Phase 0 新增）: 在激活条件满足时产出最小 STRIDE list，落到具体缓解与 ADR。详见
references/threat-model-stride.md。
When to Use
使用：
- 需求规格已批准，但设计尚未批准
hf-design-review 返回 需修改 或 阻塞，需要按 findings 修订- 当前问题已进入 HOW 层，需要明确架构、模块边界、接口、数据流、技术决策和测试策略
不使用：
- 规格仍是草稿/待评审/待批准 →
hf-specify / hf-spec-review
- 设计已批准，需要任务计划 →
hf-tasks
- 只要求执行设计评审 →
hf-design-review
- 阶段不清或证据冲突 →
hf-workflow-router
直接调用信号："开始做设计"、"把实现方案写出来"、"设计被打回了"、"先别拆任务，把架构想清楚"。
Chain Contract
读取：已批准规格（默认 features/<active>/spec.md）、feature progress.md（默认 features/<active>/progress.md）、项目级路径约定（若项目已声明）、其中声明的项目级设计原则锚点（默认 docs/principles/，承载项目自身的 architecture/product principles 等）、当前架构概述（按 Minimal docs Tiers：档 1 读 docs/architecture.md，档 2 读 docs/arc42/；二者择一存在），外加最少必要技术上下文。当 hf-ui-design 被激活时，也读取其最新草稿以标记 peer 依赖条目。
read-on-presence：上述 docs/ 资产若不存在，视为该资产未启用（项目当前在档 0），不阻塞当前节点；按"项目当前未启用此类资产"作为判断结论，仍可继续设计。
产出：可评审设计草稿（默认 features/<active>/design.md）+ 设计层追溯与关键决策；若有 hf-ui-design 并行，还需在文档中写明 peer 依赖交接块（本设计依赖对方锁定的条目、本设计已锁定、冲突或待协商）。
关键决策必须以 ADR 形式落到仓库级 ADR pool（默认 docs/adr/NNNN-<slug>.md，4 位顺序号、仓库级唯一、永不复用），而不是内联在 design.md 内。design.md 通过 ADR ID 引用，例如 "see ADR-0042"。新建 ADR 时状态字段写 proposed；hf-design-review 通过且 设计真人确认 完成后翻为 accepted。源码化图（Structurizr DSL / PlantUML）允许直接落到 docs/diagrams/，与 design review 一并审核 diff。
Handoff：hf-design-review。
联合 design approval：当 hf-ui-design 被激活时，hf-design-review 与 hf-ui-review 均通过后，父会话才发起 设计真人确认。本 skill 的 review 通过不等于可以单独进入 approval。
Hard Gates
- 设计未评审获批前，不得拆解任务或编写实现代码
hf-design-review 给出"通过"前，不发起 approval step- 未经
using-hf-workflow 或 hf-workflow-router 入口判断，不直接开始设计
Design Constraints
MUST DO
- 用 ADR 记录所有影响后续任务规划的关键决策
- 逐项处理非功能需求，按 QAS 映射到模块 / 机制 / observability / 验证（见
references/nfr-checklist.md）
- 至少比较两个可行方案，权衡 trade-offs；候选对比需显式评估对 Success Metrics 的影响
- 分析关键路径的失败模式并给出缓解策略
- 识别架构模式并说明选择理由和天然限制
- 提供最少必要的架构视图（优先 Mermaid）
- 规格存在多概念 / 多角色 / 跨系统交互时，先做 Domain Strategic Modeling（Bounded Context / Ubiquitous Language / Context Map）
- 战术建模触发条件满足时（Bounded Context ≥ 2 / 单 Context 内多实体 + 一致性约束 / 并发或事务边界 / 领域事件 / 跨聚合不变量），产出 DDD Tactical Model（见
references/ddd-tactical-modeling.md）
- 触发条件满足时产出轻量 STRIDE threat list（见
references/threat-model-stride.md）
MUST NOT DO
- 为假设的未来需求过度设计（YAGNI）
- 不评估备选方案就选定技术或模式
- 忽略运维复杂度和部署成本
- 在没理解需求前就开始画架构图
- 跳过安全性和隐私考量（Security NFR 存在或跨信任边界存在时，必须产出 STRIDE list）
- 让模块 / 组件切分与 Bounded Context 不一致却不作解释
- 把 GoF 代码模式（Strategy / Factory / Adapter / Observer / Decorator / Builder / Singleton 等）前置决策到 design 阶段——这类模式属于实现层 emergent 浮现，强行前置等于 over-abstraction，违反 YAGNI 与 Clean Arch dependency rule。战术模式（Entity / VO / Aggregate / Repository / ...）不在此禁令内——它们是领域语义选择，必须前置
- 战术建模触发条件满足却静默跳过（无"本 Context 不做战术建模"说明）
Workflow
1. 阅读已批准规格并提取设计驱动因素
读取 项目级路径约定（若项目已声明）、feature progress.md（默认 features/<active>/progress.md）当前阶段、已批准规格（默认 features/<active>/spec.md）相关部分。
提取：核心范围、成功标准与验收标准、约束、非功能需求、集成点、关键需求编号、显式 assumptions、会影响架构选择的开放问题。
规格中若有阻塞架构判断的未决问题：
- 会改变范围/验收标准/约束/接口的 → 回到
hf-workflow-router
- 属于实现上下文级澄清、不改变需求边界的 → 可在当前轮次补充确认
2. 了解最少必要技术上下文
阅读现有架构 / 项目布局、当前框架与运行时约束、已知部署 / 集成 / 兼容限制、可复用模块与边界。
识别架构模式（按 references/architecture-patterns.md 的维度判断）。
不提前进入实现规划。
若用户输入仍是 brainstorming 式实现想法（多种做法混写、优缺点零散、夹带局部技术偏好）：
- 先归一化为
候选方案 / 决策驱动因素 / 硬性约束 / 假设 / 明显越界的实现细节
- 不把"大家随口提过的方案名"直接当作已比较完成的候选方案
- 先抽出真正影响方案选择的比较维度，再进入候选方案比较
2.5 Domain Strategic Modeling（Phase 0 新增）
进入 C4 视图之前，先回答"哪些边界需要存在"：
- 按
references/ddd-strategic-modeling.md 起草 Bounded Context 清单（1–4 个为宜）
- 为每个 Context 写 Purpose / Core Concepts / Language / Ownership
- 把 spec section 14 术语扩展为 Ubiquitous Language 的 design 侧入口；显式列出跨 Context 冲突
- 画 Context Map（用 Mermaid 或紧凑列表）表达 Shared Kernel / Customer-Supplier / ACL / Conformist / Open-Host / Published Language / Separate Ways / Partnership 的真实关系
- 若项目规模不匹配（单模块脚本、单一稳定 Context），可显式标注"本轮不做战略建模"并说明理由
2.6 Event Storming Snapshot（Phase 0 新增，按 profile 分档）
按 references/event-storming.md 选择合适深度：
lightweight：一段自然语言描述主要事件 / 命令 / 异常流standard：Event Timeline（Mermaid sequence 或文字时序），含异常路径full：Event Timeline + Process Modeling（命令 / 策略 / Read Model / 外部系统 / Hotspot 标记）
Hotspot（争议 / 不清楚）应转化为 ADR 候选决策或 STRIDE list 的关注项。事件聚类是候选 Bounded Context 的边界输入。
2.7 DDD Tactical Modeling（Phase 0 新增）
在战略建模锁定 Bounded Context 之后、进入候选方案比较之前，回答每个 Context 内部的领域模型长什么样。
触发条件（任一满足即必须产出；否则显式写明跳过理由）：
- Bounded Context 数量 ≥ 2
- 单个 Bounded Context 内存在多实体 + 跨实体一致性约束
- 存在并发修改或事务边界需要回答
- 存在领域事件（业务状态变化需要跨聚合 / Context 感知）
- 规格中存在跨聚合的业务不变量
产出：按 references/ddd-tactical-modeling.md 的最小结构，对每个触发 Context 填写 Aggregates / Value Objects / Repositories / Domain Services / Application Services / Domain Events，落到设计文档 § 4.5。
关键决策（聚合边界切分、Domain Event vs 同步调用、乐观 vs 悲观锁）落到 ADR，不内联。
边界：本步骤只处理领域语义驱动的模式（Entity / VO / Aggregate / Repository / Domain Service / Application Service / Domain Event）。GoF 代码模式（Strategy / Factory / Adapter / Observer / Decorator / Builder / Singleton 等）不在本步骤前置决策——它们属于实现层 emergent 浮现，由 hf-test-driven-dev 在 REFACTOR 步按 Fowler 重构词汇处理（详见本 skill Methodology 中 Emergent vs Upfront Patterns）。
3. 提出 2-3 个候选方案并形成结构化决策
对每个候选方案说明：如何工作、适合原因、主要优缺点、对约束和 NFR 的影响、关键风险。
默认应形成一个紧凑的 compare view，而不是只写 prose。至少让 reviewer 能冷读出：
- 候选方案之间最关键的 trade-offs
- 选定方案为什么比另外方案更匹配当前轮边界
- 哪些决策已经稳定，哪些仍待后续澄清
默认 compare view 至少要能回答以下维度；可用表格、矩阵或等价紧凑结构表达：
方案名 / 核心思路最适合的场景或约束主要收益主要代价 / 风险对关键 NFR / 约束的匹配度对后续 task planning 的影响
若复用现有架构、历史方案或团队偏好作为候选项之一，仍要把它放进 compare view，而不是只写“沿用旧方案”。
推荐方案时使用 ADR 格式记录关键决策（按 references/adr-template.md）。
若是因 hf-design-review 打回而重入：先读评审 findings → 修复阻塞问题 → 不重做未受影响的部分。
4. 校验设计原则
选定方案后、编写设计文档前，校验以下维度：
若 项目声明了项目级设计原则、architecture principles、soul docs 或等价价值锚点，先按声明路径读取，并把它作为候选方案筛选准则；不要假设固定目录、固定文件名或 Garage 特定路径。
- YAGNI 校验：决策是否由当前已确认需求驱动？"未来可能需要"标记为过度工程候选
- 复杂度适配：Solo + 本地运行 → 不引入微服务/消息队列/分布式数据库；文档型 → 不引入重型框架；组件 < 10 → 不需要服务发现
- 模块边界：依赖单向（内层不依赖外层）、最小知识（接口只暴露最小必要信息）、开闭原则
- Bounded Context 一致性（Phase 0 新增）：C4 Container / Component 切分与 Bounded Context 一致；若不一致，必须在 ADR 中显式解释
- Tactical Model 触发判断（Phase 0 新增）：满足触发条件时，每个 Bounded Context 产出战术模型（Aggregates / VOs / Repositories / Domain Services / Application Services / Domain Events）；不触发时显式写明跳过理由
- Emergent vs Upfront 模式边界（Phase 0 新增）：DDD 战术模式（领域语义驱动）前置决策；GoF 代码模式（实现细节）刻意保持 emergent，不在 design 章节前置列举（详见本 skill Methodology 中 Emergent vs Upfront Patterns）
- NFR QAS 承接（Phase 0 新增）：每条 spec 中的 QAS 都有对应设计承接（模块 / 机制 / observability / 验证），见
references/nfr-checklist.md
- Security / Threat 触发判断（Phase 0 新增）：若 Security NFR 存在或跨信任边界存在，必须产出 STRIDE list
- 失败模式：按
references/failure-modes.md 分析关键路径，确认单点故障、错误处理四层次
- 可测试性：关键行为可隔离验证；存在 Walking Skeleton 最薄端到端路径
5. 编写设计文档
按 references/design-doc-template.md 的默认结构（或 项目级覆盖的模板）。
明确区分规格层（做什么）、设计层（如何实现）、任务层（分步实施，属于 hf-tasks）。
对非 trivial 设计，提供 2-3 类最少必要视图（逻辑架构、组件/接口关系、关键交互、数据视图），优先 Mermaid。
默认要显式落下以下文档级语义：
- 候选方案对比与选定理由
- 测试与验证策略，尤其是后续
hf-test-driven-dev 的最薄验证路径
- task planning readiness：哪些边界、接口、风险已经足够支撑
hf-tasks
- 开放问题的阻塞 / 非阻塞分类
6. 评审前自检与 handoff
交 hf-design-review 前确认：
准备好后，启动独立 reviewer subagent 执行 hf-design-review，不在父会话内联评审。
Reference Guide
按需加载详细参考内容。任一 reference 未命中其"加载时机"时，不需要提前读取。
| 主题 | Reference | 加载时机 | 最小 profile |
|---|
| 项目级设计原则锚点 | 项目级约定（查找 design principles / architecture principles / soul docs 的声明路径） | 项目存在这类价值锚点时，先按声明路径加载并用于筛选候选方案 | 全档必读（存在时） |
| ADR 模板 | references/adr-template.md | 记录关键决策时 | 全档必读 |
| NFR 检查清单（含 QAS 承接 / observability） | references/nfr-checklist.md | 处理非功能需求时 | 全档必读（存在 NFR 时） |
| 失败模式分析 | references/failure-modes.md | 分析关键路径韧性时 | standard / full；lightweight 仅关键路径存在时 |
| 架构模式选择 | references/architecture-patterns.md | 识别架构模式时 | standard / full；lightweight 仅明显需要选型时 |
| 设计文档模板（含 Phase 0 新章节） | references/design-doc-template.md | 编写设计文档时；每次会话至少读一次 | 全档必读 |
| DDD 战略建模 | references/ddd-strategic-modeling.md | 进入 C4 前锁边界 / 统一语言 / Context Map；Bounded Context 预计 ≥ 2 时 | full；standard 当跨系统交互或多角色时加载 |
| DDD 战术建模 | references/ddd-tactical-modeling.md | 战略建模之后、候选方案比较之前；触发条件（Bounded Context ≥ 2 / 单 Context 多实体 + 一致性约束 / 并发或事务边界 / 领域事件 / 跨聚合不变量）满足时加载 | standard / full；lightweight 允许显式跳过 |
| Emergent vs Upfront 模式立场 | 本 skill Methodology 段 Emergent vs Upfront Patterns（已内联） | 判断某个模式该前置还是 emergent 时直接读本 skill 内立场 | 全档必读 |
| Event Storming | references/event-storming.md | spec → design 桥接，按 profile 分档 | standard / full；lightweight 允许纯自然语言跳过加载 |
| 轻量 STRIDE 威胁建模 | references/threat-model-stride.md | Security NFR 或跨信任边界激活时 | 全档必读（触发时） |
加载策略：
lightweight：默认读 design-doc-template.md + nfr-checklist.md，并参考本 skill Methodology 段 Emergent vs Upfront Patterns 内联立场；ADR 记录时加 adr-template.md；STRIDE 触发时加 threat-model-stride.md；其余按命中条件standard：在 lightweight 基础上加 failure-modes.md 与 architecture-patterns.md；跨系统或多角色时加 ddd-strategic-modeling.md 与 event-storming.md；战术触发时加 ddd-tactical-modeling.mdfull：按实际需要加载；Bounded Context 预计 ≥ 2 或存在多 Context 集成时，预读 DDD 战略 + 战术 + Event Storming 三篇
Red Flags
- 设计文档写成实现伪代码
- 复制需求规格而无设计决策
- 只给一个方案不讨论权衡
- 候选方案只有名称或口号，没有可冷读的 compare view
- 候选对比未显式评估对 Success Metrics 的影响
- 设计文档里直接拆任务
- 只写模块名不写边界、交互和契约
- NFR 只在概述中出现，没落实到具体模块
- NFR 承接表缺 observability 手段或验证方法
- Bounded Context 与 C4 模块切分不一致却无解释
- Ubiquitous Language 只是抄了一遍 spec 术语表，没有澄清冲突
- 战术建模触发条件满足却静默省略，或用"本 Context 简单所以跳过"这种模糊理由
- Aggregate 用 "XxxAggregate" 技术后缀；Repository 服务多个 Aggregate Root；Application Service 里写 if 业务规则（这些都指向战术建模未认真做）
- 设计文档列出 Strategy / Factory / Adapter / Observer / Decorator 等 GoF 候选模式作为前置决策（这是 over-abstraction；GoF 应 emergent 浮现）
- "为了通用 / 为了扩展 / 为了未来可能多一种实现"而在 design 阶段引入抽象层，但当前只有 1 种实现
- Security NFR 存在或跨信任边界存在，却跳过 STRIDE list
- STRIDE list 只填了两三个字母，其余留空
- Event Storming 被画成 sequence diagram 的别名（只记交互，不记业务事件）
- 决策理由含"未来可能需要"而无当前需求支撑
- 没分析关键路径失败模式
- handoff 缺失却声称"设计可以直接往下走"
Output Contract
完成时产出：
- 可评审设计草稿（默认
features/<active>/design.md）
- 关键 ADR（默认
docs/adr/NNNN-<slug>.md，状态 proposed），design.md 通过 ID 引用
- 源码化图（如有变更，默认
docs/diagrams/）
- 设计驱动因素、关键决策、边界与最少必要视图
- feature
README.md 中 Artifacts 表的 Design 行与 Linked Long-Term Assets 中的 ADRs 行已更新
- feature
progress.md 更新：Current Stage → hf-design；Next Action Or Recommended Skill → hf-design-review
推荐输出：
设计文档草稿已起草完成，下一步应派发独立 reviewer subagent 执行 `hf-design-review`。
推荐下一步 skill: `hf-design-review`
如果设计稿仍未达评审门槛，不伪造 handoff；明确还缺什么，继续修订。
Common Rationalizations
| 借口 | 反驳 / Hard rule |
|---|
| "DDD 战略 / 战术对小 feature 太重，跳过。" | Hard Gates: bounded context + ubiquitous language 是 design 必需输出；缺位时 hf-design-review 判 fail。 |
| "我直接套 GoF 模式，不需要在 § 4.5 列战术模式。" | Hard Gates: 实现层 SUT Form pattern:<name> 只允许承接 design § 4.5 已批准的 DDD 战术模式（hf-test-driven-dev 的对位约束），GoF 是 emergent 而非 upfront。 |
| "ADR 留到实现时再补。" | Workflow stop rule: 重大架构决策必须在 design 阶段以 ADR 形式落盘；事后补 ADR 违反 evidence-based routing。 |
| "STRIDE 风险建模等安全审计阶段做。" | Hard Gates: lightweight STRIDE 是 design 阶段必需输出；v0.2.0 缺 hf-security-hardening 时 design 是唯一安全捕获点。 |
Verification
