Community编程与开发github.com

项目开发工作流

用于AI编程代理的开发规范。在编码前重新陈述请求并获得确认;将工作分层并设置可检查的完成标准,在进入下一层之前验证每一层(必要时使用独立验证者);在关键决策上采用对抗性评审或明确的自我反驳;在确认范围内推进,超出范围则提出建议;将每个已解决的陷阱记录到PITFALLS.md。适用于开始或继续非平凡的开发工作——多步骤功能、跨多个步骤的缺陷、重构、架构或方案选择——即使未明确引用此技能。也适用于“遵循工作流”、“正确执行此操作”、“验证此内容”、“评审该计划”、“记录此陷阱”、“更新陷阱”等独立请求,仅运行匹配的部分。不适用于纯问答和一行改动。

项目开发工作流 是什么?

项目开发工作流(Project Dev Workflow)是一项为AI编码代理设计的开发规范,旨在解决常见开发失败场景,如AI误解请求后直接编码、自检通过但实际有误、从单一视角论证设计、仅执行指令、重复已犯陷阱等。其核心流程包括入口路由(单节调用/轻量或标准层/自主模式)、预检(阅读陷阱日志和项目规则、确认工作区状态)、理解与确认(重新陈述需求、等待用户确认)、分层计划(将任务拆分为可独立验证的增量层并设定检查标准)、逐层执行与验证(每个层验证通过后才能进入下一层,高风险层交给独立验证者)、最终报告(提供证据、未验证项、已接受/拒绝的评审、建议、新陷阱),以及贯穿始终的对抗性评审、主动执行和实时陷阱记录。该规范支持Claude Code、Cursor、Codex等平台,通过明确的分层和验证机制,减少开发失误、提高协作透明度。

兼容平台✓Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/svd748xyz/project-dev-workflow/tree/HEAD

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

项目开发工作流 是做什么的?

适用于整个开发项目的工作规范。它针对这些失败场景: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 的提案,需要用户决定,附上价值和成本>
**新增/更新的陷阱**:<写入条目的标题>

“未验证/已知限制”行是必须的;当确实没有时,写“无”并解释你为何自信。其他行在为空时可省略。

轻量层级,简短形式:

**已完成内容**:<一两句话>
**验证方式**:<命令 + 结果>
**已知限制**:<仅当存在时>

报告仅陈述事实和证据。不得有自我评价如“完美实现”、“非常优雅”、“巨大改进”。

用户对长项目最常抱怨的是黑盒进度:仅报告当前增量使他们无法判断整体状况。定期——或在被问到时——提供从零到现在的全景:阶段时间线以及每……

…[已截断以进行翻译]

相关技能