01 · 从聊天指令到可验收的工程任务

定位：方法研究与项目复盘。 仓库包含 Claude Code、Codex、研发流程和 Agent 协作教程，并不包含这些产品的引擎源码。本文总结的是工程组织方法，不把教程案例写成已部署系统，也不承诺某个命令在所有版本中可用。

“帮我完成这个功能”是一句合理的需求，却不是完整的工程任务。它没有告诉执行者哪些现状不能改变、什么结果才算正确、遇到冲突时应该保留什么，也没有给接手的人留下验证入口。

claude-demo 的研究从工具使用扩展到研发全流程，之后又进入素材、视频和三维实验。把这些内容连在一起看，会发现一个比提示词技巧更稳定的规律：Agent 能否交付，取决于任务能否被清晰地描述、观察和验收。

一、把 Agent 看成反馈循环，而不是一次性答案生成器

入门资料用“思考—工具—观察”解释工作过程。工程上可以将它理解为：执行者根据当前证据选择动作，再用环境反馈修正判断。

如果没有可观察的反馈，这个循环只是在不断生成更像答案的文本；如果没有边界，它可能为了完成目标修改不该修改的文件；如果没有停止条件，它可能在局部改善上不断消耗时间。

因此，一个可执行任务至少需要四部分：

部分	要回答的问题	仓库案例中的表现
目标	交付给谁、解决什么问题？	动作表情、移动端文章、角色模型、平台素材包
上下文	以哪些文件和现状为准？	原图、数据目录、构建脚本、设计记录
边界	哪些动作禁止或必须确认？	不覆盖来源素材、不读取凭证、不擅自上传
验收	如何区分成功与“看上去完成”？	测试、清单、预览、视觉评审、平台回执

这些内容不必都写成长文档，但不能全部留在执行者的猜测里。

二、用交付契约替代不断追加的聊天要求

下面是从仓库案例提炼的任务约定模板，不是某款 Agent 的实际配置语法：

task: 核查一组动态素材是否可以进入投稿准备
inputs:
  - 原始分镜与角色参考
  - 当前构建脚本、配置与测试
allowed_actions:
  - 读取来源与输出元数据
  - 在独立目录生成检查材料
forbidden_actions:
  - 覆盖来源图
  - 自动调用收费生成服务
  - 自动提交到平台
acceptance:
  - 文件、尺寸、时长和命名检查有结果
  - 视觉问题能定位到素材与帧
  - 未确认事项明确列出，不伪装为通过

契约的价值不在格式，而在于它可以被不同执行者复用。换一个模型、换一个人、跨一次会话，目标和权限不会随聊天上下文一起丢失。

仓库的设计与计划资料已经形成类似分工：设计说明“为什么、要什么”，计划说明“怎样拆解、改哪些位置、怎样检查”。截至本次盘点有 34 份设计与 36 份计划。它们是重要的过程资产，但计划中的复选框和示例命令本身并不能证明执行完成。

三、将“完成”拆成不同证据层级

最容易出现的误判，是把所有结果都压缩成一句“测试通过”。实际上，不同交付物需要不同证据。

代码功能需要输入输出断言及适当的集成检查；浏览器界面还需要实际渲染和交互；图像动画需要格式校验之外的视觉审查；平台投稿需要区分本地包、上传成功、进入审核和审核通过。

研发全生命周期资料强调前端渲染、后端业务测试及敏感变更确认。这些建议在后来的素材项目中有更具体的映射：文件存在只是第一层，动画是否表达正确动作是另一层，平台是否接受又是下一层。

一个实用的交接格式是：

结果：完成了什么
依据：哪个源码、配置、测试或报告支持这一判断
验证：本轮实际运行了什么，结果是什么
边界：没有验证什么，哪些依赖仍缺失

把边界写出来不会降低交付质量；它恰恰防止下一位执行者把未知条件当成既成事实。

图 01：不同交付类型对应不同证据；投稿还需要区分本地包、上传、进入审核与审核通过。图中不声明任何平台状态已经达成。

四、经典案例可以学方法，不能借走“成绩”

cc-classic-cases 收录了管道处理、多代理审计、跨系统自动化、迁移、联调、调研到实现、文档生成和跨会话任务。这些材料可以作为任务设计的模板。

但其中的审计结果处于“输出示例”部分，示例中的业务源码路径在当前仓库并不存在。不能据此宣称“本项目发现并修复了这些漏洞”，也不能把示意投票比例转换为真实检出率。

同样，亮眼项目清单、工具能力评分和效率倍率，只有在具备明确实验任务、基线、重复次数和原始数据时，才有资格作为测量结论。原始提效研究也明确承认缺少独立效率基准。

技术分享最应该保留的是方法的推理链，而不是脱离证据的漂亮数字。

五、长任务真正需要保存的是状态

跨会话工作不应只保存“我们聊过什么”，更应保存以下信息：

• 当前问题和已经确认的事实。
• 已修改或生成的文件及其用途。
• 已运行的验证、失败信息和尚未核验的假设。
• 下一步最小动作，以及不应重复执行的外部操作。

仓库中同一主题存在多个版本、评审目录和设计修订，这说明研究任务会经历路线改变。如果只保存最终产物而没有决策状态，后来的执行者容易把旧方案当成当前约束，或者反复生成已被否定的版本。

状态文件也不应变成新的隐私风险：凭证、平台会话、个人资料和完整外部返回内容，不属于普通交接材料。

六、怎样在团队中落地

建议先选一个边界清楚的小任务，例如修复一个图像裁切规则或补充一项输出校验，而不是直接要求 Agent 负责整个发布流程。

开始前确认输入、可写范围和验收项；执行中要求发现与证据一起提交；结束时检查产物与验证是否匹配。连续观察几轮后，再把重复稳定的步骤抽成脚本或技能。

不要先以“让更多 Agent 干活”为目标。只有当任务边界、上下文和质量门槛已经清楚时，并行才可能带来净收益；否则只是同时增加多个无法验收的输出。

结语

好的 Agent 工作流，本质上也是好的工程工作流：边界清楚、状态可交接、证据可追踪、结果可验收。模型可以参与更多步骤，但对需求与发布结果的责任不会因为自动化而消失。