From harness-flow
Transforms approved requirement specs into reviewable design docs for architecture, modules, APIs, data models, backend NFRs using ADR, C4, DDD, Event Storming. Use post-spec approval, pre-task planning or design revisions.
npx claudepluginhub hujianbest/harness-flow --plugin harness-flowThis skill uses the workspace's default tool permissions.
把已批准规格转化为可评审的设计文档,说明"如何"实现,让后续任务规划与实现不再靠猜测推进。
evals/README.mdevals/evals.jsonevals/fixtures/minimal-approved-spec.jsonreferences/adr-template.mdreferences/architecture-patterns.mdreferences/ddd-strategic-modeling.mdreferences/ddd-tactical-modeling.mdreferences/design-doc-template.mdreferences/event-storming.mdreferences/failure-modes.mdreferences/nfr-checklist.mdreferences/threat-model-stride.mdtest-prompts.jsonCollaboratively brainstorms architecture, approaches, and trade-offs from specs, proposes options, gets section-by-section approval, then writes design.md. Use for 'design this' or 'brainstorm approaches'.
Generates architecture/design documents from approved SRS docs when no prior design exists, proposing 2-3 approaches with trade-offs and securing section-by-section approval.
Designs software architecture from specs using 5 agents for module splits, dependencies, data flows, and interfaces. Outputs Markdown docs with diagrams and ADR. Use for spec-to-design or pattern selection.
Share bugs, ideas, or general feedback.
把已批准规格转化为可评审的设计文档,说明"如何"实现,让后续任务规划与实现不再靠猜测推进。
职责边界:本 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。
本 skill 融合以下已验证方法:
references/adr-template.md。references/ddd-strategic-modeling.md。references/ddd-tactical-modeling.md。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 重构词汇足以表达后期模式选择。references/event-storming.md。hf-specify 层的 QAS(ISO 25010 + Source/Stimulus/Environment/Response/Response Measure),把每条 QAS 映射到具体模块 / 机制 / observability / 验证。详见 references/nfr-checklist.md。references/threat-model-stride.md。使用:
hf-design-review 返回 需修改 或 阻塞,需要按 findings 修订不使用:
hf-specify / hf-spec-reviewhf-taskshf-design-reviewhf-workflow-router直接调用信号:"开始做设计"、"把实现方案写出来"、"设计被打回了"、"先别拆任务,把架构想清楚"。
读取:已批准规格(默认 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。
hf-design-review 给出"通过"前,不发起 approval stepusing-hf-workflow 或 hf-workflow-router 入口判断,不直接开始设计references/nfr-checklist.md)references/ddd-tactical-modeling.md)references/threat-model-stride.md)读取 项目级路径约定(若项目已声明)、feature progress.md(默认 features/<active>/progress.md)当前阶段、已批准规格(默认 features/<active>/spec.md)相关部分。
提取:核心范围、成功标准与验收标准、约束、非功能需求、集成点、关键需求编号、显式 assumptions、会影响架构选择的开放问题。
规格中若有阻塞架构判断的未决问题:
hf-workflow-router阅读现有架构 / 项目布局、当前框架与运行时约束、已知部署 / 集成 / 兼容限制、可复用模块与边界。
识别架构模式(按 references/architecture-patterns.md 的维度判断)。
不提前进入实现规划。
若用户输入仍是 brainstorming 式实现想法(多种做法混写、优缺点零散、夹带局部技术偏好):
候选方案 / 决策驱动因素 / 硬性约束 / 假设 / 明显越界的实现细节进入 C4 视图之前,先回答"哪些边界需要存在":
references/ddd-strategic-modeling.md 起草 Bounded Context 清单(1–4 个为宜)按 references/event-storming.md 选择合适深度:
lightweight:一段自然语言描述主要事件 / 命令 / 异常流standard:Event Timeline(Mermaid sequence 或文字时序),含异常路径full:Event Timeline + Process Modeling(命令 / 策略 / Read Model / 外部系统 / Hotspot 标记)Hotspot(争议 / 不清楚)应转化为 ADR 候选决策或 STRIDE list 的关注项。事件聚类是候选 Bounded Context 的边界输入。
在战略建模锁定 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)。
对每个候选方案说明:如何工作、适合原因、主要优缺点、对约束和 NFR 的影响、关键风险。
默认应形成一个紧凑的 compare view,而不是只写 prose。至少让 reviewer 能冷读出:
默认 compare view 至少要能回答以下维度;可用表格、矩阵或等价紧凑结构表达:
方案名 / 核心思路最适合的场景或约束主要收益主要代价 / 风险对关键 NFR / 约束的匹配度对后续 task planning 的影响若复用现有架构、历史方案或团队偏好作为候选项之一,仍要把它放进 compare view,而不是只写“沿用旧方案”。
推荐方案时使用 ADR 格式记录关键决策(按 references/adr-template.md)。
若是因 hf-design-review 打回而重入:先读评审 findings → 修复阻塞问题 → 不重做未受影响的部分。
选定方案后、编写设计文档前,校验以下维度:
若 项目声明了项目级设计原则、architecture principles、soul docs 或等价价值锚点,先按声明路径读取,并把它作为候选方案筛选准则;不要假设固定目录、固定文件名或 Garage 特定路径。
references/nfr-checklist.mdreferences/failure-modes.md 分析关键路径,确认单点故障、错误处理四层次按 references/design-doc-template.md 的默认结构(或 项目级覆盖的模板)。
明确区分规格层(做什么)、设计层(如何实现)、任务层(分步实施,属于 hf-tasks)。
对非 trivial 设计,提供 2-3 类最少必要视图(逻辑架构、组件/接口关系、关键交互、数据视图),优先 Mermaid。
默认要显式落下以下文档级语义:
hf-test-driven-dev 的最薄验证路径hf-tasks交 hf-design-review 前确认:
hf-test-driven-dev REFACTOR 步 emergent 浮现)references/nfr-checklist.md),包含 observability 与验证方法hf-tasksfeatures/<active>/design.md(或 项目级覆盖路径)docs/adr/NNNN-<slug>.md,状态写 proposed,design.md 通过 ADR ID 引用而非内联全文progress.md 已按 canonical schema 更新 Current Stage 和 Next Action准备好后,启动独立 reviewer subagent 执行 hf-design-review,不在父会话内联评审。
按需加载详细参考内容。任一 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 三篇| 易混淆 skill | 区别 |
|---|---|
hf-ui-design | 本 skill 管架构 / 模块 / API / 数据模型 / 后端 NFR;hf-ui-design 管 IA / 交互 / 视觉 / 组件 / 前端 a11y。两者是同层 peer,规格含 UI surface 时并行起草、联合进入 设计真人确认。 |
hf-tasks | 设计阶段回答"如何实现";任务阶段回答"分几步做"。设计未批准前不拆任务。 |
hf-design-review | 本 skill 负责起草设计;design-review 负责独立评审。不能自审自交。 |
hf-specify | specify 回答"做什么";design 回答"如何做"。规格未稳定时不进入设计。 |
hf-workflow-router | router 负责阶段判断和路由(含 UI surface 激活条件);本 skill 假设阶段已确定为"设计"。 |
完成时产出:
features/<active>/design.md)docs/adr/NNNN-<slug>.md,状态 proposed),design.md 通过 ID 引用docs/diagrams/)README.md 中 Artifacts 表的 Design 行与 Linked Long-Term Assets 中的 ADRs 行已更新progress.md 更新:Current Stage → hf-design;Next Action Or Recommended Skill → hf-design-review推荐输出:
设计文档草稿已起草完成,下一步应派发独立 reviewer subagent 执行 `hf-design-review`。
推荐下一步 skill: `hf-design-review`
如果设计稿仍未达评审门槛,不伪造 handoff;明确还缺什么,继续修订。
features/<active>/design.md(非规格文件、非任务文件)docs/adr/NNNN-<slug>.md(status: proposed)hf-tasksprogress.md 已按 canonical schema 更新 Current Stage 和 Next ActionREADME.md 中 Design / ADRs 引用已更新hf-design-review