企业官网建设流程全解析

• AI 技能
• AI 插件
• 人工智能

导读

在 AI Agent 驱动的开发流程中，"先写软件设计文档（Software Design Document，SDD）再实现"是降低返工、保证架构一致性的关键策略。本文将围绕 agentic-awesome-skills 仓库中 agents-generator 技能所生成的 sdd-workflow.md 规则模板，完整讲解 SDD 工作流的预置默认值、强制验证闭环、规格书查阅机制与全部占位符的生成逻辑，并引入底层检测矩阵与真实示例，帮助你理解如何在任意项目中落地一套"设计先行、验证兜底、归档可回溯"的 Agent 工作流。

SDD Workflow 在项目中的定位

sdd-workflow 是一份由 agents-generator 技能按目标项目自动生成的规则文件，输出到目标仓库的.agents/rules/sdd-workflow.md。它的核心思想一句话即可概括：

Software Design Document — design before implementing（软件设计文档——先设计，再实现）。

在 SKILL.md 列出的规则清单中，sdd-workflow.md与architecture.md、git-workflow.md一样属于"Always"（始终生成）的规则类别（见 decision-matrix.md 的 Rule File Selection 表格），即使项目没有任何测试框架、样式库或 ORM，也仍然会生成该文件——因为"先设计后实现"与"改前验证"是任何规模项目都应遵守的通用纪律。

Preflight Defaults：缓存的可配置项（不要重复询问）

规则模板开头定义了 5 个"预检默认值"，用于在每轮 SDD 流程开始前确定工作参数。关键约束是"cached, do not re-ask"（缓存，不要重复询问）——即这些值在项目初始化时确定一次，后续流程直接复用，避免 Agent 每轮都向用户重复提问。

从生成机制看，这些值由 agents-generator 在检测阶段依据项目特征填充（详见下文"Generation Rules"小节），生成后作为固定约定写入规则文件，供后续每一轮 SDD 流程引用。

三条铁律：Agent 工作流的安全底线

模板的 Rules 部分给出三条不可妥协的规则，它们是整套 SDD 工作流的运行前提：

1. 子代理可能犯错——必须复审其输出。模板原文提示子代理（sub-agents）可能产生重复代码块、错误类型等低级错误，因此任何子代理产出的代码都必须经过审查，不能直接信任。
2. 每个 SDD 阶段结束后，运行完整的验证循环。验证不是只在最后做，而是阶段性的强制动作（详见下一节）。
3. 归档时必须校验：所有标记为 done 的任务真实完成，delta 规格已同步回主规格。这保证了增量设计（delta spec）不会丢失，归档即代表一致性闭环。

这三条规则与 git-workflow.md 中的"NO commits without the user validating the code first（未经用户验证不得提交）"一脉相承，共同构成对 Agent 自主行为的约束护栏。

Post-Apply Verification：强制验证闭环（MANDATORY）

模板中最关键的机制是Post-Apply 强制验证：在sdd-apply（应用设计）阶段完成之后、进入sdd-verify（验证设计）阶段之前，编排器（orchestrator）必须运行完整验证循环：

{{VERIFICATION_CYCLE}}

VERIFICATION_CYCLE 是如何组装的

{{VERIFICATION_CYCLE}}不是随意编写的命令串，而是由 agents-generator 依据检测到的工具链自动拼接而成。根据 decision-matrix.md 的 Verification cycle 一节，其装配逻辑为：

{typecheck} → {lint} → {test} → {doctor}

• {typecheck}：TypeScript 项目为tsc --noEmit（bun 环境为bunx tsc --noEmit），无 TypeScript 则跳过；
• {lint}：取{pm} run lint或检测到的 lint 命令；
• {test}：取单次运行的测试脚本（test:run优先，否则test）；
• {doctor}：检测到 react-doctor 时取{pm} doctor或{pm}x react-doctor@latest，否则跳过。

其中{pm}的映射规则为：bun 直接使用bun <script>（无需run），pnpm 为pnpm，npm 为npm run，yarn 为yarn。组装依据同样记录在 template-filling-guide.md 的{{VERIFICATION_CYCLE}}条目：只包含工具真实存在的步骤，且命令格式必须与 package.json 脚本完全一致。

两个条件化补充块

模板在验证循环之后预留了两个条件插槽：

• {{MONOREPO_POST_APPLY}}：如果是 monorepo，需在验证循环之前追加"共享包重建"步骤。根据 decision-matrix.md，当修改了共享包（shared packages）时，需要先执行其 rebuild 命令，再跑循环，否则共享包的消费者会基于过期构建产物验证。
• {{DOCTOR_POST_APPLY}}：如果检测到 react-doctor，追加"关于新引入 issue 的处理规则"，把健康度检查（doctor）纳入变更门禁。

真实基准示例

example-output/README.md 给出了一个 Bun + Next.js 16 + Server Actions 项目的实测验证循环，可直接作为落地参照：

bunx tsc --noEmit → bun run lint → bun run test:run → bun doctor

该基准还强调：验证循环中每条命令都必须真实存在于 package.json 的 scripts 中——"doctor": "npx react-doctor@latest"被映射为bun doctor，而不是想当然的npm run doctor。这也是为什么模板要求验证循环的每一个环节都可执行、可验证。

Spec Verification：规格书是架构变更的"宪法"

模板的 Spec Verification 一节规定：

• 项目规格书位于{{SPECS_LOCATIONS}}所列举的位置；
• 在做出架构性变更或新增功能之前，必须查阅这些规格来源。

{{SPECS_LOCATIONS}}由生成器填充为项目实际存在的规格目录清单，典型构成包括：

• docs/specs/（项目自有规格目录）
• OpenSpec（若项目使用 OpenSpec 规格体系）
• 相关的 Engram topics（若项目使用 Engram 记忆/规格系统）

结合{{SDD_ARTIFACTS}}的取值逻辑（见下节）可以看到，SDD 工作流的设计文档落点与规格查阅范围是同一套体系：设计与规格同源，改动前查规格、设计后回写规格，避免设计与实现脱节。

Generation Rules：每个占位符的生成逻辑

模板末尾的 Generation Rules 是整份文件的"填充说明书"，规定了生成器如何根据项目特征决定每个占位符的值。逐项拆解如下：

SDD_PACE（节奏）

• 默认"Interactive"（交互式）；
• 若项目在 CI 中使用自动模式，则取"Automatic"（自动）。

SDD_ARTIFACTS（设计产物形态）

根据规格体系的存在情况三选一：

SDD_DELIVERY（交付策略）

• 默认"ask-on-risk"：仅在存在风险时询问用户；
• 若项目偏好大 PR（large PRs），取"exception-ok"。

SDD_REVIEW_BUDGET（评审预算）

• 默认400行；
• 依据项目典型 PR 大小调整（评审行数上限应与实际 PR 规模匹配）。

SDD_CHAIN_STRATEGY（链式分支策略）

• 若项目快速合入，取"stacked-to-main"（堆叠式直合主干）；
• 若项目使用长生命周期功能分支，取"feature-branch-chain"（功能分支链）。

MONOREPO_POST_APPLY 与 DOCTOR_POST_APPLY

• MONOREPO_POST_APPLY：若为 monorepo，在验证循环前加入共享包重建步骤（与上一节的条件块对应）；
• DOCTOR_POST_APPLY：若存在 react-doctor，加入关于新引入 issue 的规则。

SPECS_LOCATIONS

列出docs/specs/、OpenSpec、相关 Engram topics——即生成时实际探测到的规格来源清单。

与验证闭环配套的相邻规则

SDD 工作流的验证闭环并非孤岛，它与同批生成的相邻规则文件互相咬合：

• git-workflow.md：提交前运行{{PRE_COMMIT_CYCLE}}（完整验证循环的缩短版），任何一步失败即禁止提交；这是 SDD 阶段验证在"提交时刻"的延伸。
• testing.md：在变更{{TESTED_AREA}}（如lib/或src/）后运行{{VERIFICATION_CYCLE}}，与 SDD 的 post-apply 验证形成"测试面-设计面"双重校验。

三者共享同一套由 decision-matrix.md 定义的验证循环装配规则，保证项目内所有规则文件对"验证"的理解一致、命令一致。

落地建议：把 SDD 工作流接入你的 Agent 项目

1. 定位文件：确认目标项目根目录存在AGENTS.md，且.agents/rules/sdd-workflow.md已由 agents-generator 生成；若需要重新生成，参照 SKILL.md 的 Full mode 执行流程（读取 agents-full.md 结构与各 assets 模板后填充）。
2. 核对预检默认值：检查SDD_PACE、SDD_ARTIFACTS、SDD_DELIVERY、SDD_REVIEW_BUDGET、SDD_CHAIN_STRATEGY是否符合团队实际节奏——它们是"缓存不重问"的值，一旦定错会持续影响后续每轮流程。
3. 验证循环可执行性：对照 template-filling-guide.md 的{{VERIFICATION_CYCLE}}条目，逐条确认typecheck → lint → test → doctor中每个命令都对应 package.json 中真实存在的脚本键；monorepo 项目确认共享包 rebuild 步骤在循环之前。
4. 规格来源先行：按SPECS_LOCATIONS列出的目录（docs/specs/、OpenSpec、Engram topics）建立"改动前必查规格"的惯例，并确保归档阶段 delta specs 同步回主规格。
5. 保留人工把关：规则强调生成的指令属于"提案（proposals）"，需要人工 review 后才可采纳（见 SKILL.md 的 Limitations 一节），SDD 工作流只是把验证前置、流程固化，并未替代人的最终判断。

小结

sdd-workflow 规则模板用一份不到 50 行的文件，把"先设计后实现"从一句口号变成了可执行的工程约束：预检默认值缓存团队约定，三条铁律约束子代理行为，Post-Apply 强制验证闭环由检测矩阵自动装配、随工具链真实可跑，规格查阅机制保证设计与规格同源。配合 decision-matrix.md、template-filling-guide.md 与 example-output/README.md 三份配套资料，你可以为任意技术栈的项目生成一份同样具体、可验证、无占位符的 SDD 工作流规则——这正是 Agent 驱动开发中"设计与验证都不缺位"的落地形态。

• AI 技能
• AI 插件
• 人工智能