工作流设计质量经验¶

最关键的交付物¶

Workflow Builder 的核心是工具、Checker、GuideDoc、config/inc 和用户文档。manifest、schema 和实现计划只有在约束这些核心交付、减少跨阶段歧义或支持确定性检查时才有价值。新增 spec 前应回答它解决了哪个真实错误，以及谁读取和更新它。

workflow_implementation_plan.md 是前后阶段对话载体。首阶段应把用户需求扩展为更具体的工具数据流、Checker 判定、文档、依赖、测试和失败恢复。后续阶段的“问题与处理”记录模板不兼容、Checker 误报、引用时序和设计调整，是优化母工作流最有价值的证据之一。

计划不能只重复用户原文，也不能堆叠不会执行的宏大设计。每项计划要映射到 workflow build spec、实际文件和验收。

常见形式主义包括：为每个小动作增加一个 spec；反复进行认知核验；要求每阶段全文读取所有文档；创建大量空壳工具；通过重复文字满足长度；每生成一个文档就运行一次全量检查。

更好的做法是保留少量中心事实来源、提供索引和最小示例、批量生成后综合检查，并把时间用于业务算法、Checker 证据和开发文档的真实源码分析。

工具计划至少说明输入、输出、核心算法、异常、路径边界、调用阶段、注册和测试。Checker 计划至少说明检查对象、字段、通过/失败条件、证据、正反 fixture、构造参数和误报风险。计划详细度应高于用户需求，而不是要求用户预先写完实现。

生成配置前后都要审查：变量是否定义；reference/output 是否为具体文件；文件在对应阶段是否已存在；路径规范化；工具与 Checker 注册参数一致；write/un_write 边界不矛盾；阶段是否能从上一阶段产物得到输入；任务描述是否可能让 Agent无限重试。

用户文档需要稳定结构、完整命令和真实输入输出，开发者文档还必须引用实际业务源码。简单的“本工具负责处理数据”不能指导维护者修改算法。详细度通过字段、代码、控制流、失败和扩展点体现，而不是单纯字符数。

业务运行结束后完整阅读实现计划的所有“问题与处理”，把问题分为业务特有、GuideDoc 缺失、生成器缺陷、Checker 缺陷和外部不稳定。只有跨业务可复现的内容进入公共 FAQ 或通用规则。修改后用新的不同业务验证，避免只对历史案例过拟合。

新增结构前回答：是否拥有独立消费者；是否消除两个组件的真实歧义；是否能被确定性验证；更新责任是否明确；是否比扩展现有中心 spec 更简单。不能回答时，不新增。spec 数量不是工程质量指标。

详细计划聚焦数据流、业务算法、错误、测试和扩展点。无意义详细是为每一步重复“读取、确认、再次确认”，或提前规定大量永远不用的状态。每项计划要映射到交付文件和 Checker，否则只是形式。

开发者文档每个组件引用真实文件和符号，摘录最小关键片段，解释输入、控制流、返回、异常、路径边界和修改影响。粘贴完整源码不算分析；只列路径也不够。业务工作流生成的 docs/04 和 docs/05 同样适用。

修复母工作流后至少选择一个不同类型的新业务验证，观察首阶段失败、生成耗时、文档质量、工具/Checker 注册和最终 make check。只在造成问题的历史工作区验证容易过拟合已有文件、历史和审批状态。

流程结束后总结有效问题、误报、失败次数、耗时热点、人工干预、文档缺项和可复用经验。每条建议说明收益和可能新增复杂度。用户选择暂不实施的建议保留决策理由，不应在下一轮自动重新引入。