recon-driven-dev（侦察驱动开发 · 自包含五阶段流水线工作流）

一条即时开发轨:开头做一份只针对本次改动的"摸底",喂给后面的需求、设计、(评审)、写计划、实施。自包含、零外部 Skill 依赖——各阶段能力都内联在本 Skill 内,丢到任何环境都能独立跑。

各阶段细则下沉 references/,本文件只持跨阶段的脊柱:流程图、阶段衔接与所有 ⏸ 暂停、起步约定、全局护栏,以及每阶段「一句话职责 + 指向 reference 的指针」。指针只点名该 reference 里非默认的具体动作,细则不在脊柱复述。

核心流程

五阶段,每阶段结束暂停等用户确认。产物都落本次改动目录 docs/recon-driven-dev/<YYYY-MM-DD>-<change-name>/,收尾时连目录一起归档。③ 评审可选,由 ② 出口的决策点拍板。

① 定向分析   一句话粗需求 → 钻落点 + 消费面 → directed-report.md
             ⏸ 主会话实测门(① 自守、防空转的真牙)
② 需求+设计  据①(参考非上限,可自行补探),内联对话澄清需求与设计 → requirements.md + design.md
             ⏸
       └─ ⏸ 评审决策点:据 ①② 信号给「建议评审 / 可跳过」+ 理由,用户拍板 ─┐
③ 评审(可选) 派评审 sub-agent → 三维度 + 定向报告验收 → review.md
             ⏸
④ 写计划     拆 tasks.md(曳光弹切片 + 右尺寸 + 验收/依赖序)
             ⏸ 审计划   →   ⏸ 执行方式(内联 / 子 agent)
⑤ 实施       两分支 gates(clean-baseline / ISOLATE / TDD / per-task 评审)+ 收尾前整支评审
             ⏸ FINISH 收口菜单   →   ⏸ 归档

流向:① → ② → (③?) → ④ → ⑤,线性不回流(唯一例外:事实订正,见末尾全局护栏)。

为什么先摸代码再谈需求:不先摸清楚就拍方案,十有八九漏掉"原来别处也在用这张表"这类坑,等写代码才发现要返工。

派发与降级(① / ③ / ⑤ 整支评审 共用)

凡需上下文隔离的 sub-agent 能力(① 侦查、③ 评审、⑤ 收尾前整支评审、⑤ 子 agent 实现),走同一范式:

• 有隔离能力(本会话有 Task / 通用 agent):派——Read 对应的自带 prompt 体(recon-agent.md / review-agent.md / code-reviewer.md),以其正文作 Task 的 prompt、把本次的路径与上下文(含子 agent 要读的模板绝对路径)追加在末尾,用通用 Task 当搬运工。派发时须确保子 agent 冷启动、不继承主会话史——宿主派发默认继承上文时(如 Codex spawn_agent 默认 fork_turns=all),须在派发处显式关闭历史继承(Codex 对应 fork_turns=none;仅映射示例、不绑死)。不赖任何特定内置 agent(如 Explore)——它们的 prompt/模型不归本 Skill 控、质量会飘。
• 无隔离能力:降级主会话自跑同一套契约/判据——没有新视角与隔离收益,须把契约当外部尺逐条核、把检索噪声尽量挡在叙事外。

工具名 = 能力示例:本 Skill 正文出现的 Read/Grep/Glob/Write/Task 等是 Claude Code 工具名,仅作能力示例;其它引擎映射到等价能力即可(读文件 / 检索 / 按名圈选 / 写文件 / 派隔离子 agent)。

契约/判据与跑在哪一级无关,派发只是执行方式。各 prompt 体是本 Skill 自带的、不调任何外部 skill。

起步:建本次产物目录

AI 直接为本次改动定个 kebab-case 短名(无需问用户),冠以当天日期,创建 docs/recon-driven-dev/<YYYY-MM-DD>-<change-name>/;该目录已存在(活跃或归档)就换名 / 加后缀,别覆盖前一次的产物。

每阶段暂停模板

阶段 X 完成,产出 <file>。请审阅。
✅ 满意 → 进入下一阶段   ✏️ 需调整 → 告诉我哪里改

① 定向分析 → directed-report.md

职责:动需求/方案前,把这次需求主题落进的那片现有代码摸清楚——有啥、牵动谁、埋了什么雷——全带锚点,喂给 ②。只摆现状事实、不出方案。它是给 ② 的现状参考、不是权威上限。

细则(派发路由 / agent 降级 / 主会话实测门 / ① 阶段封存边界)见 references/directed-analysis.md。

⏸ 这道质量门是「主会话实测门」、不是泛质量门——收到报告后,主会话亲自扫本会话可用的只读手段(含 MCP),对支撑坑的 [未核验] 软推断当场取真实值比对,而非只复核"交付四条齐全"就放行。具体动作住 reference;别让半成品报告进 ②。

② 需求 + 设计 → requirements.md + design.md

职责:据 ① 的现状定"要什么"和"改哪些 / 怎么改",内联对话谈完一次产出两份。① 是参考起点、不是上限,需求够到 ① 没覆盖的代码就自行补探,新发现记进 design.md(前向),不回写已封存的 directed-report。

细则(对话契约 / 三硬规则 / 两份产物 / design.md 必覆盖清单 / 评审决策点判据 / ② 自评)见 references/requirements-design.md。

HARD GATE:呈现需求 + 设计并经用户(非模型自判)批准前,不写任何实现 / 脚手架 / 代码——完整规则住 reference,脊柱只亮牌。

别猜先问硬闸:设计对话遇实质不确定 / 分叉,先问用户、有合理默认也须 ADR 记录,绝不静默拍板——判据(含反合理化红旗)住 reference。

② 端信号产出义务:② 的产物/自评须让下面这些信号对评审决策点可读取——① 暴露的协同护栏 / 反直觉陷阱 / [未核验],与 ② 的测试缝隙数 / ADR 决策数 / 爆炸半径。否则决策点"据 ①② 信号给建议"无据可依。

⏸ 两份产出后暂停让用户过目;别在这道停点之外再叠一道。

⏸ 评审决策点(③ 是否进行)

② 出口后,skill 据上面「② 端信号产出义务」列的 ①② 信号,给「建议评审 / 可安全跳过」+ 理由,用户拍板。判据(完整信号清单 + 代价提示)单一权威在 references/requirements-design.md;脊柱只点一个钩子——跳过 ③ 即丢掉「定向报告验收」这道安全网;它查什么、为何 ② 自评补不上、哪些 ① 信号因此触发建议,都见 reference 的评审决策点判据。

③ 评审(可选) → review.md

职责:判方案好坏。③ 不在主上下文内联自评——派一个上下文隔离的评审 sub-agent,新视角去自评偏见,评审的中间推理不回灌主对话。

派发:把 ①② 的三份产物(directed-report.md + requirements.md + design.md)+ 一句改动概述交给评审 sub-agent,按上文「派发与降级」走(Read review-agent.md 作 prompt)。它产 review.md + 三档结论(通过 / 有条件通过 / 不通过)+ 修订清单,回主 agent 一段简短结论。判据全住 references/review-agent.md,脊柱不复述;后两档不自动分流,在下面这道 ⏸ 由用户据修订清单定是否回写 ② 改设计;用户处置后主会话回填 review.md——逐条标处置状态(已修订 / 接受风险+依据 / 仍阻断)+ 一句本轮 ③ 最终放行状态,放行前核其与经处置的 design.md(及回写的 requirements.md)评审相关主张一致(别让 review.md 停在原结论、下游却已按新决策前进;收口是主会话活、非评审 agent 职责)。

⏸。

④ 写计划 → tasks.md

职责:把 design 拆成小而独立、各自可演示/可验的任务,排好依赖序。

细则(基线计划六条 / 分层计划 / 执行方式决策)见 references/planning.md。

• ⏸ 审计划——写码前最便宜的拦截点,审过再往下。
• ⏸ 执行方式:计划末尾选内联 vs 每任务一个新子 agent。这个选择决定计划是否升级到自包含形态(精确 Interfaces + 任务级完整路径),也决定 ⑤ 走哪条执行分支。

⑤ 实施 → 代码 + 归档

职责:按 ④ 的计划在隔离工作区内落地、收口、归档。

细则(两条执行分支 gates / 非显性陷阱块 / 实施前冲突预检 / 收尾前整支评审 / 文件交接 / 进度账本)见 references/implementation.md。脊柱点名几个非默认硬闸:

• 两分支共有硬闸:clean-baseline、ISOLATE(优先原生 worktree 工具、从当前 HEAD 切、<type>/<change-name> 分支名)、在 ② 预先约定的测试缝隙上写失败测试(TDD)、per-task 两阶段评审(spec 符合 + 代码质量)。
• 实施前:先做「计划 ↔ 全局约束 ↔ 评审 rubric」的冲突预检——一次批量问用户、扫净则静默继续。
• 收尾前:派隔离子 agent 跑 code-reviewer.md 做整支代码评审(Standards + Spec 两轴),无隔离能力降级主会话自跑——派/降级只看隔离能力,与 ④ 选的执行分支正交。
• ⏸ FINISH 收口菜单(本地合并 / push+PR / 保留原样 / 保留分支·回收 worktree / 丢弃) → ⏸ 归档(本次目录移进 _archived/)。

全局护栏

> 这些是运行时跨阶段硬约束(写给正在跑五阶段流水线的 AI)。改本 Skill 自己时的治理规则(防膨胀 / 单一权威源 / provenance 归处)是维护宪法、不随运行载入。

• ✅ 报告必须落「发现」(落点现状 / 实答 / 锚点)——这是料、不是套路。薄的是流程(别教怎么 grep / 追链),不是结论;空有问句没答案才是真薄。
• ✅ 各阶段在出口守住自己产物的质量、不把把关堆到下游——③ 不打回 ① 补摸底,② 的盲区 ② 自己探。(① → ② → (③?) → ④ → ⑤ 线性不回流见上方流程图;唯一例外是下方「事实订正」。)
• ❌ 别让评审 sub-agent 替 ① 重做系统钻取——它只对正在判的主张做定点源码核验;全量摸底是 ① 的活,回流是禁的。
• 🔁 ④⑤ 的实现步骤本 Skill 内联拥有——别委托外部技能、别引脚本,也别在既定 gates / 停点之外加冗余评审。
• 🔁 不引入跨会话持久件、不发持久编号。进度账本是本次产物目录内的 per-change scratch、随归档清,不属此列。

事实订正(线性不回流的唯一例外 · 跨全程总账)

directed-report 一过 ① 质量门进入 ②,即视为封存。此后任何环节用证据推翻它写下的一条事实主张(区别于「① 没写的新面」——那走 design.md 前向、不算订正),就在原文条目正下方追加订正块、原文标 [已订正]:

⚠️订正:原文已被推翻 → 真相:… | 证据:file:line 或查询结果

落点(重映射到五阶段):②③ 阶段证伪在对应 ⏸ 落、动摇设计走 ③ 三档;④ 写计划 / ⑤ 实施途中推翻——主会话落订正块(诚实留痕、不算重排链),动摇设计就就地暂停、surface 给用户定方向(续做 / 回 ②③ 改),本 Skill 不自动重判。

① 封存前 directed-report 还是草稿、直接改不计订正(此即 ① 阶段的封存边界,directed-analysis.md 用指针引、不另持一份)。核验与落订正由主会话(主 agent)做;评审 sub-agent 只把推翻真实记进 review.md、绝不碰 directed-report。