AllWorkin / Articles / 2026.07.02

如何打造云软件工厂第2篇:复杂Issue自动写Spec(PRODUCT.md + TECH.md)

复杂 Issue 别硬写代码。Warp 云工厂第 2 篇:Spec Agent 自动生成 PRODUCT.md + TECH.md,人改 spec 后再 Implement。附 6 步落地清单,Claude Code / Codex / Warp 通用。

2026.07.02约 6 分钟#Agent#Skills#Prompt#Cursor

ChatGPT Image 2026年7月8日 17_00_20

上一篇我们搭了 Triage → Implement:Issue 进来,Agent 分流,简单的直接出 PR。

那复杂需求呢?范围大、方案有分歧、改完可能上千行代码——硬丢给实现 Agent,多半产垃圾 diff。

这篇讲的是怎么把 Spec Agent 接进同一条流水线。PRODUCT.md / TECH.md 怎么写、怎么落到你的 repo,全在这里。


一、为什么 Triage → Implement 不够

第一篇的逻辑很清晰:Triage Agent 看 Issue 质量,必要时问澄清问题。范围够小就打 ready-to-implement,Implementation Agent 出 draft PR。

这对简单直接的 bug、小功能够用。

碰上下面两种 Issue,直接写代码多半翻车:

作者的做法:在四标签分流里,把 ready-to-spec 这一步做细,接上 Spec Agent。


二、ready-to-spec:什么时候该写 Spec

四标签逻辑(与第一篇一致,这里只展开 spec 分支):

打 ready-to-spec 要同时满足两件事:

1、匹配路线图和愿景

Demo 项目在 cloud-factory-demo 仓库里加了两个文件,给 Triage / Spec Agent 当「北星」:

  • roadmap.md — 产品要往哪走

  • vision.md — 长期愿景是什么

Issue 如果对不上路线图,就算复杂也先别自动写 spec——避免 Agent 帮倒忙。

2、值得写 Spec(歧义或复杂度)

  • 歧义:多种产品/技术方案差异大,人得选

  • 复杂度:实现量预计几百行以上

Triage Skill 升级后,判定逻辑多了一层:Issue 既符合 roadmap/vision,又有歧义或复杂度 → 打 ready-to-spec。标签一打,GitHub Action 触发,云端跑 Spec Agent。

基建跟第一篇一样:Docker 镜像、云 Runner(示例用 Oz)、GitHub Actions。平台可换,Skill 逻辑不变。


三、Spec Agent 产出什么

Spec Action 跑完后,repo 里会多两个文件,按 Issue 编号放在 specs/ 目录下:

Demo 里 image editor 的功能 spec 可以直接去 cloud-factory-demo 仓库看样例。

我的建议(与原文一致):Spec 随实现 PR 一起提交,也可以先单独 PR 合并 spec、再开实现。存进 repo 的好处:以后能翻「Agent 当时想怎么做」,Review 和验证都有对照物。

系列下一篇会加 Verification Agent,用 /validate-changes-match-specs 核对实现是否偏离 spec——这篇先知道有这步就行。


四、Spec 不会一次写对:人在回路怎么接

Agent 出的 PRODUCT.md / TECH.md 通常是可改初稿,不是终稿。

作者推荐 workflow:

  1. 把 spec 拉到本地工作区

  2. 用交互式 Skill 对齐预期——他点名 Matt Pocock 的 /grill-me(拷问式对谈,本号 Skills 榜里也有,高安装量)

  3. Spec 满意后,把 Issue 标成 ready-to-implement(人或 Agent 在 GitHub 改标签均可)

  4. Implementation Agent 启动,且 Implementation Skill 已升级:先读 spec 再写代码

整条链路变成:

Issue → Triage → [简单] 直接 Implement
              → [复杂+合路线图] Spec → 人改 spec → Implement 跟 spec 写
              → [不清] needs-info / wait

复杂 Issue 先 spec、再实现,比「Prompt 里多写两句」靠谱得多。


五、对我们的落地步骤

如果你已经跟过第一篇 Demo(/oz-cloud-factory-demo),第二篇增量不大:

  1. 升级 Triage Skill:加入 roadmap/vision 读取 + 歧义/复杂度判定

  2. 新增 Spec Skill + Spec 专用 GitHub Action(监听 ready-to-spec)

  3. 在 repo 根目录放 roadmap.md / vision.md(哪怕先写半页)

  4. 约定 specs/{issue号}/ 目录结构

  5. 升级 Implementation Skill:实现前必须读对应 PRODUCT.md + TECH.md

  6. Spec 初稿用 /grill-me 或你习惯的 Review Skill 过一遍

没有 Oz 时:用 GitHub Action + 容器 Runner 一样能跑,Codex 也有 webhook 可接。思路一样——标签驱动 Agent 角色切换。


六、我的判断

云工厂第二篇的核心就一句:把「写 spec」也工厂化,且 spec 是可入库、可 Review 的产物,不是聊天里的临时约定。

三个结论:

  1. ready-to-spec 别打太宽——必须绑 roadmap/vision,否则 Agent 会给无关 Issue 写一堆废 spec

  2. PRODUCT / TECH 分开很值——产品行为和技术形态混在一个 Prompt 里,后面验证和对账都痛苦

  3. Spec → grill-me → Implement 这条人在回路,比全自动更现实;全自动留到 Verification 那篇。Skill 怎么自我迭代,之前写过《Loop Engineering》,思路可以直接搬

先把 spec 目录和 Implementation Skill 的「读 spec」接上,就已经比大多数「Issue 直接丢给 Cursor Agent」的团队领先一步。

下一篇作者要加 Review 和 Verification Agent。


参考链接

AI工具实战派

觉得有用?每周的新笔记先发公众号。

每周的实战笔记先发在这里。扫码关注,新文章第一时间推给你。

关注 / 加入社群 →