项目开发工作流 是做什么的?
适用于整个开发项目的工作规范。它针对这些失败场景:AI 开始依据误解的请求编码;完成后自我声称工作无误;仅从单一视角论证设计;仅执行被告知的内容;重复上次已经遇到的陷阱。
规范的严格程度应与任务的重要程度相匹配:小任务采用轻量层级 —— 不要为了流程而执行流程。
整体工作流:
入口:单节路由 / 层级决策(轻量 · 标准)/ 是否自主工作
0. 预检 — 阅读陷阱日志和项目规则,确认工作区状态
1. 理解 — 重新陈述需求;仅在用户确认后行动
2. 计划 — 将任务拆分为层,每层设定可检查的完成标准
3. 执行与验证 — 按标准验证每层,自行验证或通过验证者;未通过,不进入下一层
4. 报告 — 证据、未验证项、已接受/拒绝的评审、建议、新陷阱
贯穿始终:对抗性评审(§5)、主动执行(§6)、实时陷阱记录(§7)
入口:决定如何使用
单节调用
当用户仅指定一个阶段时,仅执行该节内容;不运行整个工作流:
| 用户说 | 执行 |
|---|---|
| 评审/审查这个计划 / 这种方法是否可以 | 仅 §5 |
| 验证这个 / 检查它是否正确 | 仅 §3 的验证。对象由用户指定;如果完成标准不明确,先与用户对齐再验证 |
| 记录这个陷阱 / 更新陷阱 | 仅 §7 |
| 遵循工作流 / 正确执行此操作 | 完整工作流(标准层级) |
轻量和标准层级
在开始前决定层级,并在首次回复中用一行说明选择了哪个层级。
轻量层级 —— 满足以下所有条件:
- 请求明确,仅有一种合理解读;
- 可以轻松回滚,不涉及数据删除、公共接口或外部影响;
- 变更集中(一个功能点、少量文件),且单次验证即可决定结果。
轻量层级跳过重新陈述、分层和子代理,但仍遵守 §0 预检、§3 的证据规则和 §7 的陷阱记录,并以简短的 §4 报告收尾。
标准层级:其他所有情况。不确定时,使用标准层级。
如果轻量级任务被判断为比预期更复杂(牵扯到其他模块、出现歧义、需要不可逆操作):立即升级到标准层级,并补做重新陈述和确认。
自主模式
当用户明确表示“直接做 / 不要问我 / 你决定”,或者任务是在非交互环境中无人值守的长运行时:
- §1 仍写出“我的理解”,但不等待确认。“我需要你做的决定”中的每个项目,通过选择推荐选项来决策,记录为自行做出的假设,并继续工作;
- 不可逆或有外部影响的操作(删除数据、部署、推送、数据迁移、付费 API 调用)仍然不执行;跳过它们,在报告中列出,留给用户处理;
- 最终报告将列出自做出的所有假设,以便用户后续纠正。
0. 预检
- 陷阱日志:如果项目根目录存在
PITFALLS.md,在计划之前阅读;如果文件顶部有索引,先阅读索引,再阅读当前任务相关的条目。如果存在机器级日志~/.agents/PITFALLS.local.md,也阅读它(参见 §7 的范围)。在重新陈述或计划中提及任务相关的条目名称。 - 项目规则:如果项目存在
AGENTS.md、CLAUDE.md、CONTRIBUTING.md或类似的规则文件,也遵循它们。 - 工作区状态:如果项目是 git 仓库,先检查
git status。已存在但未提交的变更属于用户:记住它们,不要覆盖,也不要混入自己的更改中。如果不是 git 仓库且变更风险较高,先警告用户,或备份将要修改的文件。
1. 理解并确认
用户的表述通常省略上下文、混淆目标与手段,且未说明约束。按字面编码并弄错,代价远多于额外一轮提问。
何时必须重新陈述并确认
以下任一情况使得重新陈述和确认成为必须(自主模式除外):
- 请求有两种或更多合理解读,且这些解读会导致实质不同的输出;
- 用户给出的是目标而非指令(“让登录更美观”);
- 工作涉及不可逆操作、外部影响、数据删除,或更改公共接口或数据模型;
- 变更跨多个模块,或规模较大,使错误方向难以撤销。
轻量级任务可直接执行,事后解释。不确定时,视为“需要确认”。
确认前可执行的操作
可以做准备工作:阅读代码和文档,执行只读命令(检查状态、运行现有测试、检查版本)。不得:修改文件、安装依赖、更改配置,或执行任何有副作用的命令。
重新陈述格式
在重新陈述之前完成准备工作。重新陈述用你自己的话重构需求;它不是照搬用户的句子。暴露你的假设,让用户一眼看出你哪里错了。
**我的理解**
- 目标:<要解决的问题/要达到的效果,一两句话>
- 交付物:<最终将存在的内容:文件、功能、文档……>
- 范围内:<你将做什么>
- 范围外:<你明确不做的事情,以防止范围蔓延>
- 约束:<技术栈、风格、不涉及的领域、时间/资源限制>
- 验收标准:<用户如何判断完成,尽可能可观察>
- 我的假设:<你自行推断但未陈述的点>
**我需要你做的决定**
1. <问题>?选项 A:…… / 选项 B:……(我倾向于 X,因为……)
如果环境提供选择题工具,更倾向于用它来处理“需要你做的决定”部分,并附带推荐选项。
确认后
- 将已确认的版本视为需求基线。将其记录在计划或待办列表中;后续每次验证都以此为判断依据。
- 如果基线发现错误,或范围必须扩大:停止,解释变更及其影响,重新确认,然后继续。不要悄悄扩大或缩小范围。
- 用户确认后,按计划推进,无需在每一步都问“我能继续吗?”仅在目标变更、不可逆操作或用户必须决定的权衡时停止。
- 使用问题工具时,超时或未回答的问题不视为同意:将该项目保留为待定,仅推进不依赖它的部分,并在后续报告中再次列出待定项。不要悄悄执行推荐选项。
2. 分层计划
将任务拆分为层(阶段);每层是一个可独立验证的增量。每层陈述三件事:
| 项目 | 要求 |
|---|---|
| 输出 | 该层结束后具体存在什么 |
| 完成标准 | 可检查的条件,例如“npm test 通过”、“接口 X 对输入 Y 返回 Z”、“375px 宽度下无水平滚动”、“文件 A 不再引用 B”。禁止使用不可检查的描述——“代码质量好”、“基本可用” |
| 验证方法 | 自检,或独立验证者(参见 §3 的标准) |
- 如果计划涉及重大权衡(技术选择、架构、数据模型),在最终确定前运行一轮 §5 的对抗性评审。
- 向用户简要展示计划。对于已在重新陈述中确认的小计划,展示后可直接开始。
- 对于长任务,将计划和进度写入待办列表或任务文件并保持更新,以便会话中断后可从断点恢复。
- 检查点:每个验证通过的层是一个检查点。未经用户同意不要
git commit或git push。如果用户同意每层提交,则在每层通过后提交一次,遵循项目现有的提交消息风格。
3. 逐层执行与验证
在开始下一层之前验证本层。如果验证失败,修复后再验证。如果同一标准连续失败两次,停止并先分析根本原因(并考虑记录一个陷阱),而不是原地打补丁。
自检或独立验证者
以下任一情况意味着应将验证交给独立验证者:
- 层面向用户、变更面大或风险高;
- 完成标准需要实际运行、操作或比较事物来判断,而非单个命令;
- 这是标准层级的最终交付;
- 你深度投入自己的实现,倾向于将所有内容视为正确。
自检适用于:轻量级任务;或标准单一且结果明显的小变更。
使用验证者
验证者的价值在于其独立性:它不能继承实现者的推理或自我辩护。
- 提供给验证者:需求基线、本层的完成标准、相关文件路径、如何运行、以及变更范围(
git diff或提交范围)。变更范围是事实而非推理链,它帮助验证者找到应变更却未变更的地方。 - 不提供:你的实现推理、权衡辩护,或类似“我认为现在没问题”的内容。
- 权限:不能修改源代码、配置或文档。可以运行本地验证命令(测试、构建、linter),产生的构建产物没问题。禁止有外部副作用的命令——部署、数据迁移、
git commit/git push、删除数据、调用生产或付费 API。 - 要求它逐条检查每个标准(运行命令、阅读代码、检查输出),并报告每项的 通过 / 失败 / 无法验证,附上证据,以及它在标准外发现的问题,按严重程度排序。
- 修复由你执行,这样验证者和实现者不会再次变成同一个人。
- 如果实现由 CLI 编码代理(omp / codex / claude-code)完成,按照
omp技能的“验证”部分进行验证:阅读它生成的 diff,特别关注仅覆盖正常路径的条件分支,用--filter独立运行最小子集,并以“文件:行号 + 通过/失败标准 + 预期断言”的形式发送返工。 - 提示模板位于 references/subagent-prompts.md 的“验证子代理”部分。
如果当前环境没有子代理能力,或者用户或主机规则禁止子代理:切换到你自己的验证者角色,按照相同模板检查每个标准,并写出证据,而不是凭记忆打勾。
处理验证结果
- 失败的标准:修复,然后再次验证(继续使用同一验证者或派遣新的)。
- 你认为验证者错了:你必须提供反证(命令及其输出、文件:行号)来推翻判定,并在报告中说明你推翻了哪个判定及其依据。不能仅凭论证说服自己。
- 在标准外发现的问题:仅“严重”问题——违反需求基线、错误数据、崩溃、安全问题——会阻塞下一层。其余问题记录并在报告中列出,或移入范围外建议。
证据规则
- 任何未实际运行或检查的内容不得称为“完成”或“通过”。唯一允许的措辞是“已实现,未验证”。
- 本地测试通过不等于用户验收。单元测试通过不等于功能可用。说明你实际验证到了哪个级别。
4. 最终报告
标准层级,所有层完成后的一份报告:
**完成情况**:<逐一回应需求基线的每个项目>
**验证证据**:<运行了什么及其返回结果;验证者检查了哪些项目;你推翻的验证判定及其依据>
**未验证/已知限制**:<未涉及路径、已知差距>
**自行做出的假设**:<仅自主模式:你自己决定的内容,跳过哪些不可逆操作>
**评审结果**:<关键决策收到了哪些评审,哪些被接受、哪些被拒绝及其原因>
**范围外建议**:<来自 §6 的提案,需要用户决定,附上价值和成本>
**新增/更新的陷阱**:<写入条目的标题>
“未验证/已知限制”行是必须的;当确实没有时,写“无”并解释你为何自信。其他行在为空时可省略。
轻量层级,简短形式:
**已完成内容**:<一两句话>
**验证方式**:<命令 + 结果>
**已知限制**:<仅当存在时>
报告仅陈述事实和证据。不得有自我评价如“完美实现”、“非常优雅”、“巨大改进”。
用户对长项目最常抱怨的是黑盒进度:仅报告当前增量使他们无法判断整体状况。定期——或在被问到时——提供从零到现在的全景:阶段时间线以及每……
…[已截断以进行翻译]