AI 原生软件开发生命周期
mattpocock/skills 工作流程与技能全景

做什么

每个仓库跑一次。探索仓库现状（git remote、AGENTS.md/CLAUDE.md、是否 monorepo），然后依次确认三件事：① 问题追踪器用哪个（GitHub / GitLab / 本地 markdown .scratch/ / 其他）；② 分诊标签是否沿用默认五态（needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix）；③ 领域文档布局（默认单上下文：根目录一个 CONTEXT.md + docs/adr/）。结果写入 docs/agents/*.md，并在 AGENTS.md / CLAUDE.md 里加一个 ## Agent skills 块。

为什么

后面所有编排技能（to-spec、to-tickets、triage、wayfinder）都要回答"票发到哪、标签叫什么、词汇表在哪"。把这三个答案物化成文件而不是每次口头重申，是整个体系能跨会话运转的前提。这也是典型的"prompt 驱动而非脚本"设计：先探索、再确认、后写入，绝不覆盖你已有的编辑。

落地要点

个人项目 / 没有远端仓库 → 选本地 markdown 模式，票落在 .scratch/<feature>/issues/ 下，一票一文件。团队项目 → GitHub Issues + 原生 blocking 关系。

做什么

智能体把你的想法画成一棵设计树：每个决策分叉出挂在它下面的子决策。然后按"轮"推进——每一轮把前沿（frontier，即前置条件都已敲定、现在就能问的问题）一次性全问出来，每个问题编号并附推荐答案，等你回答后重算前沿、进入下一轮，直到前沿为空：设计树的每个分支都被访问过，没有留下任何"默认假设"。

为什么有效

三条精巧的分工规则让它区别于普通问答：① 事实是智能体的活——问题需要环境里的事实（文件、配置、API 行为）时，派子代理去查，不拿来烦你；② 决策是你的活——每个真正需要拍板的点都摆到你面前并附推荐答案，一个词就能接受；③ 一轮一计算——依赖未决问题的留到下一轮，避免你回答"看情况"后前功尽弃。结束前不动手，直到你确认达成共识。

grill-with-docs 的加成

它在拷问的同时驱动 /domain-modeling：当场把敲定的术语写进 CONTEXT.md，把"难以逆转 + 没有上下文会让人费解 + 真实权衡的结果"三条全满足的决策记成 ADR。副产品是项目的共享语言——README 里的例子：以前说"课程章节里的课被'实化'（在文件系统里拿到位置）时出问题"，有了词汇表之后一句"materialization cascade 出问题"就够了。省 token、命名一致、代码库更好导航。

何时用 grill-me

不在工作目录里时（打磨一份计划、一篇文档、一个没有仓库承载的想法）。同一套拷问，但什么都不落盘。有仓库就用 grill-with-docs——它严格更优：同样的访谈，还留下书面痕迹。

何时分支

拷问中遇到对话无法裁决的问题：这个状态机摸起来对不对？这段业务逻辑对不对？UI 该长什么样？——需要"跑起来看"才能回答的问题。

怎么做

原型分两个形态，选错形态浪费整个原型：逻辑/状态问题 → 单个可分享的 HTML 文件（自由操作按钮 + 分步引导），非开发者也能上手推演；UI 问题 → 同一路由下生成若干个 radically different 的变体，用 URL 参数切换。铁律：第一天就是一次性的、明显标注、一条命令能跑、不持久化、不抛光、每步操作后把完整状态打印出来让你看见变化。

分支的桥接

原型活在独立目录，正好用 /handoff 双向桥接：handoff 出去 → 开新会话做原型 → handoff 回来带着结论 → 回到原想法线程继续拷问。原型本身不进主干：验证出的决策折进真实代码，原型提交到一个 prototype/<name> 分支留作"一手证据"，在实现票上留个指针。

做什么

不再访谈——直接把当前会话里已经讨论清楚的东西合成为规格，发布到追踪器并打上 ready-for-agent 标签（无需再分诊）。规格模板六段：问题陈述（用户视角）→ 解决方案（用户视角）→ 超长的用户故事编号清单 → 实现决策 → 测试决策 → 范围外。

关键动作：先定接缝

写规格前先画出"准备在哪些接缝（seam）上测试"，并与你确认。优先复用现有接缝、尽量用最高的接缝——"接缝越少越好，理想数量是一"。这是整个体系里测试纪律的源头：/tdd 会拒绝在任何未确认接缝上写测试。

刻意的禁令

规格里禁止写具体文件路径和代码片段——它们过期得最快。唯一例外是原型产出的"决策密集"片段（状态机、类型形状）。

做什么

把规格切成一组曳光弹（tracer bullet）垂直切片，每张票声明自己被哪些票阻塞。切片规则四条：每片窄但完整地穿过所有层（schema → API → UI → 测试）；完成即独立可演示/可验证；每片大小正好装进一个全新上下文窗口；prefactoring（"先让改动变容易，再做容易的改动"）放在最前面。

宽重构的例外

改一个共享符号、重命名一列——爆炸半径横跨全库，垂直切片没法保持绿色。此时改走 expand–contract：先"扩张"（新旧形式并存）→ 分批迁移调用点（每批一票，批间 CI 常绿）→ 最后"收缩"（删掉旧形式）。批次也撑不住时共享一个集成分支，只承诺最终集成票是绿的。

先给你看，再发布

拆完先以编号列表呈现（每票：标题 / 被谁阻塞 / 交付什么端到端行为），问你三件事——粒度对不对？阻塞边对不对？要不要合并或再拆？——你批准后才发布到追踪器，按依赖序编号，打 ready-for-agent。

之后怎么干活

沿前沿（frontier）推进：任何阻塞者全部完成的票都可以抓走。每个 /implement 会话结束后 /clear，从下一张票冷启动。

做什么

实现票/规格描述的工作，指令刻意简短：在预先约定的接缝上尽量用 /tdd；定期跑类型检查、定期跑单个测试文件、最后跑一次全量测试；完成后跑 /code-review，然后提交到当前分支。

tdd 的三条纪律

① 红先于绿：先写失败的测试，再写恰好让它通过的代码，不预写未来的测试、不加投机功能。② 一次一片：一个接缝、一个测试、一个最小实现。③ 重构不在循环里——它属于评审阶段。好测试的标准：通过公共接口验证行为而非实现细节；测试读起来像规格说明书。三大反模式：实现耦合（重构就挂）、同义反复（expect(add(a,b)).toBe(a+b) 这种按实现复算期望值的测试永不可能失败）、水平切片（一次写完所有测试再写实现——验证的是想象中的行为）。

上下文配套

动手前读 CONTEXT.md，让测试命名和接口词汇与项目领域语言对齐；尊重所触区域的 ADR。

做什么

对 git diff <固定点>...HEAD 做双轴评审：Standards 轴——代码是否符合仓库书面编码规范 + 一组固定的 Fowler 代码坏味道基线（Mysterious Name、Duplicated Code、Feature Envy、Primitive Obsession、Shotgun Surgery 等 12 条，每条都是"是什么→怎么改"的判断题而非硬违规，仓库规范永远覆盖基线）；Spec 轴——代码是否忠实实现了来源规格：缺了什么、多了什么（scope creep）、看似实现了但实现得不对。

怎么跑

两轴各派一个并行子代理，互不污染上下文；固定点无效或 diff 为空要先失败在这里而不是子代理里；Spec 轴按顺序找规格（commit 里的 issue 引用 → 用户传的路径 → docs/specs/.scratch 下按分支名匹配 → 问用户）。最后聚合呈现为两节，不合并、不重排序，各轴内部给出最严重问题。

做什么

把 issue（以及配置开启后的外部 PR，"一个 PR 就是带代码的 issue"）推过一个五态状态机：needs-triage → needs-info / ready-for-agent / ready-for-human / wontfix。流程：收集上下文 → 给出分类/状态建议及理由 → 验证声称（bug 按报告者步骤复现；PR 检出跑测试）→ 需要时拷问补全 → 应用结果。ready-for-agent 的票附上 agent brief（面向智能体的任务简报）。

两个值得抄的细节

① 分诊时先查重复实现（按领域概念而非措辞搜索）和 .out-of-scope/ 拒绝知识库——被拒的增强请求记档，防止同一个请求下个月再来一遍；② 所有 AI 产的 issue 评论强制带免责声明。注意：/to-tickets 产出的票天生 agent-ready，不要再分诊。

做什么

六阶段纪律环，跳过任何阶段都要显式说明理由：① 造反馈回路（十种手段按序尝试：失败测试→curl 脚本→CLI+快照→无头浏览器→重放 trace→一次性 harness→fuzz→bisect harness→差分循环→HITL bash 脚本；验收标准是一条"红 capable、确定性、秒级、可无人值守"的命令）→ ② 复现并最小化（逐个砍掉非承重元素）→ ③ 提假设（先列 3–5 个可证伪假设再动手，防止单假设锚定；列表给用户看一眼，领域知识常能立刻重排）→ ④ 插桩（一次只改一个变量；调试日志统一加 [DEBUG-xxxx] 前缀方便最后一把清理；性能问题先测基线再二分）→ ⑤ 修复 + 回归测试（回归测试写在使用"真实 bug 模式"的正确接缝上；找不到正确接缝本身就是发现——说明架构拦不住这类 bug，转交架构巡检）→ ⑥ 清理（原始 repro 不再红、插桩全删、把最终成立的假设写进 commit）。

红线

没有红命令之前禁止进入假设阶段——"盯着代码读出理论"正是这个技能要防止的失败。真造不出回路就明说，向用户要环境/脱敏产物/临时插桩授权。

做什么

想法太大、一个会话装不下、路还看不清时，不硬写规格。先拷问出目的地（固定 scope 的锚点），再广度优先铺开决策票：每张票是一个问题，票的产出是一个决策而非交付物。票分四类——research（AFK，派研究子代理）、prototype（HITL）、grilling（HITL，默认）、task（为解锁决策而做的手工活）。地图刻意不完整："雾中之战"（fog of war）区域先记在 Not yet specified，决策推进到哪里、雾就散到哪里、新的票才被具体化出来。判定标准：能不能现在把问题说精确，而不是能不能回答。

运作方式

地图是一张带 wayfinder:map 标签的 issue（索引而非存储，决策细节只活在票里）；票是它的子 issue，用追踪器原生 blocking 关系。开工前先认领（assign 自己）防多会话撞车；一次会话只解决一张票（research 票除外）。地图收口后移交而不建造：合并回主流程的 /to-spec，把散落的决策收敛成可建造的规格——直接从地图冲进 implement 会丢掉关联细节。

做什么

三步：① YAGNI 定范围——先看 git log 找热点（最近常改的地方优先，因为深化是为未来的改动服务的），读 CONTEXT.md 和 ADR，再派子代理自由探索，找"浅模块"（接口复杂度≈实现复杂度）、缺 locality 的纯函数抽取、跨接缝泄漏；对疑似浅模块做删除测试（删掉它是复杂度集中了还是只是搬家了）。② 产出一份可视化 HTML 报告（写到系统临时目录，不进仓库），每个候选一张卡：涉及文件 / 问题 / 方案 / 以 locality 和 leverage 表述的收益 / before-after 图 / 推荐强度徽章，最后给 Top 推荐。③ 你选中一个候选后进入 grilling 循环细化，术语和 ADR 沿途更新。

定位

它是巡检不是救援：在真正老化的代码库上会找到真实候选，但不会替你解开泥球。选中的候选作为一个"想法"，从环节 1（grill-with-docs）重新进入主流程。

domain-modeling 管领域语言：用词和词汇表冲突当场指出（"你的词汇表把'取消'定义为 X，你现在说的像 Y，到底是哪个？"）；模糊词给出精确的规范术语；用具体场景压力测试概念边界；用户陈述与代码矛盾时摆到桌面上；术语敲定当场写入 CONTEXT.md（纯词汇表，禁止当规格或便签用）。ADR 三条件才立：难以逆转 + 脱离上下文会费解 + 真实权衡的结果。

codebase-design 管架构词汇：module / interface / depth / seam / adapter / leverage / locality 七个术语严格统一（禁用 component、service、API、boundary 这些漂移词）。核心原则：深度是接口的属性而非实现的属性；删除测试；接口即测试面；一个 adapter 是假想接缝，两个才是真接缝。/tdd 和 /improve-codebase-architecture 都说这门语言——统一词汇让"哪里该深、哪里该薄"的讨论有共同坐标。