一键导入
hf-design
适用于需求规格已批准但设计尚未批准、或设计评审返回需修改/阻塞需修订的场景。不适用于规格仍是草稿/待批准(→ hf-specify)、设计已批准需拆任务(→ hf-tasks)、仅需执行设计评审(→ hf-design-review)、阶段不清或证据冲突(→ hf-workflow-router)。
用 Codex 或 Claude 帮你安装 复制这段 Prompt,粘贴到 Codex、Claude 或其他助手里,让它检查 Skill 页面并帮你完成安装。
菜单
适用于需求规格已批准但设计尚未批准、或设计评审返回需修改/阻塞需修订的场景。不适用于规格仍是草稿/待批准(→ hf-specify)、设计已批准需拆任务(→ hf-tasks)、仅需执行设计评审(→ hf-design-review)、阶段不清或证据冲突(→ hf-workflow-router)。
用 Codex 或 Claude 帮你安装 复制这段 Prompt,粘贴到 Codex、Claude 或其他助手里,让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Use when starting an existing-code bug audit on a repository or large directory tree. First detects project language + architecture (e.g. C/C++ embedded SOA, Python web service, frontend SPA), proposes a tailored review checklist (scenario-specific bug categories) for user confirmation, then slices the codebase into modules within a per-module token budget. Produces plan.json with profile + review_checklist + modules that downstream audit-reviewer consumes module-by-module. Not for PR diff review (use hf-code-review) or for actually finding bugs (use audit-reviewer).
Use as the FINAL stage of the code-audit pipeline. Reads confirmed.json (output of audit-verifier) and renders a self-contained single-file HTML report (always) and optionally an Excel workbook. The HTML contains summary stats by severity/category/module, filterable finding cards with code snippets and audit trails (reviewer + verifier). Not for emitting findings (use audit-reviewer) or verifying findings (use audit-verifier).
Use when scanning an existing-code module for bugs and emitting finding drafts. Reads source files within one module from the plan.json produced by audit-planner, walks files line-by-line, emits findings/<module>.json with file path, line numbers, category, severity, confidence, code snippet evidence, and reasoning. The set of allowed finding categories is sourced from plan.json's review_checklist (scenario preset such as c-cpp-embedded-soa / python-web-service / frontend-spa / generic) rather than a fixed taxonomy — keep findings scoped to the user-confirmed checklist. This is the PRIMARY (first-stage) reviewer in the two-agent confirmation pipeline; downstream audit-verifier independently confirms each finding. Not for PR diff review (use hf-code-review) or for verifying findings (use audit-verifier).
Use as the SECOND-STAGE independent confirmer in the two-agent code-audit pipeline. Reads finding drafts produced by audit-reviewer and independently re-examines each one against the actual source code, writes verifications/<module>.json with status (confirmed/rejected/upgrade/downgrade/needs_more_evidence), reason, and evidence_check. Operates with FRESH context — does not see reviewer's internal reasoning beyond what is recorded in the finding's description+evidence fields, to enable independent judgement. Not for emitting new findings (use audit-reviewer) or rendering the report (use audit-reporter).
Use when hf-test-driven-dev finishes GREEN on a frontend-touching active task whose spec declares a UI surface, and fresh browser runtime evidence (screenshot / console log / network trace) is required for downstream gates. Not for issuing verdicts (gates do that), not for replacing hf-test-review's test-quality review, not for backend-only tasks.
适用于 test review 通过后评审代码质量、用户要求 code review 的场景。不适用于评审测试(→ hf-test-review)、写/修代码(→ hf-test-driven-dev)、阶段不清(→ hf-workflow-router)。
| name | hf-design |
| description | 适用于需求规格已批准但设计尚未批准、或设计评审返回需修改/阻塞需修订的场景。不适用于规格仍是草稿/待批准(→ hf-specify)、设计已批准需拆任务(→ hf-tasks)、仅需执行设计评审(→ hf-design-review)、阶段不清或证据冲突(→ hf-workflow-router)。 |
把已批准规格转化为可评审的设计文档,说明"如何"实现,让后续任务规划与实现不再靠猜测推进。
职责边界:本 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 三篇完成时产出:
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;明确还缺什么,继续修订。
| 借口 | 反驳 / 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 是唯一安全捕获点。 |
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