内部指南 · AI 原生研发效能

AI 原生开发工作流落地指南
基于 Matt Pocock Skills

把一套经过实战验证的工程师技能集，变成团队每天默认的开发方式。不是流程改造，不是工具采购，是把三件老功夫重新做进智能体时代：对齐、反馈、设计。

核心主张：把对齐做在写码之前（拷问而不是许愿），把反馈做进每一秒（红绿循环而不是事后补测），把设计当成日常（深模块而不是泥球）。AI 写得越快，这三件事越值钱。
蓝本 · mattpocock/skills（Skills For Real Engineers） 技能总数 · 27（engineering 20 / productivity 7） 适用 · 任何模型、任何代码仓、任何规模团队
01

一张图看全工作流

所有工作沿一条主流走：想法到上线。三条匝道从特定起点汇入，地下词表层托住一切。这张图看不懂，先别往下翻。

AI 原生 SDLC 全图 · THE WHOLE GAME 主流: 想法 → 上线 · 匝道: 三种起点汇入 · 底层: 共享词表与文档 匝道 A · /triage 外部 issue / PR 排队进来 分诊 → 验证 → 拷问 → 附简报 产出: ready-for-agent 的 agent 简报 匝道 B · /diagnosing-bugs 硬 bug · 性能回退 · 间歇 flake 先造一条变红的反馈环, 再谈理论 产出: 修复 + 回归测试 + 教训 匝道 C · /wayfinder 大雾级目标: 一个会话装不下的想法 在跟踪器上画决策票地图, 逐张开路 产出: 决策, 不是交付物 简报入队待领 修完带回归测试归队 地图走通 → /to-spec 1 · /grill-with-docs 拷问式访谈, 边聊边沉淀 GLOSSARY.md 与 ADR 问题能在 对话里定死? 多会话 大构建? 4 · /to-spec 对话直接合成 规格并发布 5 · /to-tickets 追踪弹票 + blocking 边 聊得清 是 得跑起来才算数 2 · /prototype 一次性原型回答一个设计问题 /handoff 出去, 学完交回来 3a · /implement 单窗口直接实现, 内部驱动 /tdd 也从 ready-for-agent 简报领活 /code-review 双轴并行: Standards × Spec, 互不污染 3b · /implement-spec 实现者子代理 × 前沿并发 整份 spec 落一条集成分支 否, 单窗口就够 票 = 任务图 /pr 最小 Summary 图 + 证据 + 合并危险度 ★ 合并上线 PR 合并, 票按跟踪器 方式关闭 /retro 回顾对象: agent 的环境, 不是代码 构建结束后回顾, 翻车时必做 把教训写进环境: 导航指针 · CI 检查 · 编码规范 地下词表层 · 每个技能都在说的语言 /grilling（访谈原语） · /domain-modeling（领域词表 + ADR） · /codebase-design（深模块词汇） · /writing-for-agents（写给 agent 的文档怎么写） 物理载体: GLOSSARY.md · docs/adr/ · CODING_STANDARDS.md · docs/agents/*.md · CLAUDE.md / AGENTS.md 蓝条 = 人敲命令（user-invoked） · 白框黑边 = 模型可自动接管（model-invoked） · 虚线 = 反馈与沉淀
主流: 想法 → 上线 反馈 / 沉淀 / 匝道汇入 记忆载体: 词表 · ADR · 规范
02

四个失败模式，四味药方

这套技能不是凭空设计的，每一味药都对着一种真实翻车现场。团队里出现以下症状，直接按方抓药。

症状 1

做出来的不是我要的

最常见的失败不是技术问题，是错位。你以为 agent 懂了，看到产物才发现完全没懂。人和 agent 之间有沟通鸿沟，和当年你和产品经理之间的一模一样。

药方：拷问，而不是许愿。开工前让 agent 反过来面试你，把设计树的每个分支都问到有答案。/grill-with-docs（在代码仓里，顺带沉淀词表和 ADR）或 /grill-me（无仓场景）。
症状 2

agent 啰嗦，20 个词说 1 个词的事

agent 被丢进项目，只能靠上下文猜黑话，于是用 20 个词描述本来 1 个词能说清的概念。每次会话都在重复付这笔税。

药方：共建一门共享语言。/grill-with-docs 访谈过程中持续打磨 GLOSSARY.md 与 ADR。回报是长期的：变量、函数、文件命名一致，代码仓更好导航，agent 思考也更省 token。 Matt Pocock 称之为这套仓库里最厉害的一招。
症状 3

代码跑不通

对齐了需求，agent 交出来的还是一堆坏代码。问题出在反馈环：代码写出来之后没有任何信号告诉它对不对，等于蒙眼飞行。

药方：红绿循环。静态类型、浏览器访问、自动化测试三件套。/tdd 强制先红后绿、一次一个垂直切片；硬骨头 bug 走 /diagnosing-bugs，先造一条对这个 bug 变红的命令，再许任何假设。
症状 4

泥球越滚越大

agent 把编码速度提了一个数量级，也把软件熵的积累速度提了一个数量级。大多数 AI 写的应用复杂到难以改动，而且劣化速度快到史无前例。

药方：每天投资设计。/to-spec 动笔前先问动哪些模块；/improve-codebase-architecture 每隔几天扫一次深化机会；/codebase-design 提供深模块词汇：多行为、小接口、净接缝。
03

主流六步：每步只记一件事

步骤 1 到 5 必须在同一个不断开的上下文窗口里完成，思考是连续的。实现阶段每张票换一个全新窗口，票是自包含的，上下文用完即弃。

STEP 1 · 对齐 /grill-with-docs

任何改动之前。agent 按轮次抛出整个「问题前沿」，每题附推荐答案，你只对决策点头或摇头。聊定的术语当场写进 GLOSSARY.md，难逆转的决定写成 ADR。

查得到的事实不许问人；决策才属于人。前沿问空、设计树无静默假设，访谈才算完。
STEP 2 · 定不死的就跑起来 /prototype（支线）

状态机合理吗，UI 到底长什么样：这类问题纸上谈不出答案。经 /handoff 出去开个新会话做一次性原型，答案（判决 + 依据）带回来，原型留在 prototype 分支上当一手证据。

从第一天起就是扔着用的：不写测试、不做抽象、状态全露出来给人看。
STEP 3 · 固化 /to-spec

对话已经聊透，且这是多会话的大构建。不再提问，直接把已有讨论综合成 spec 发布到跟踪器：问题、方案、长长的用户故事清单、实现决策、测试决策、范围外。

spec 里禁止出现文件路径和代码片段，它们过期最快。原型产出的决策性片段（类型形状、状态机）是唯一例外。
STEP 4 · 切票 /to-tickets

把 spec 拆成追踪弹票：每张票是一条纵向窄切片，穿透 schema、API、UI、测试全层，独立可演示；票与票之间声明 blocking 边，于是永远存在一条「就绪前沿」。

一张票必须装得进一个新鲜上下文。宽重构别硬切片，走 expand（新旧并存）、分批 migrate、contract（删旧）的序列，批批保绿。
STEP 5 · 实现 · 二选一 /implement 或 /implement-spec

票小、单窗口：/implement，内部驱动 /tdd，收工前 /code-review 再提交。整份 spec：/implement-spec 把票图当任务图，多个实现者子代理沿就绪前沿并发，各自 worktree 各自分支，merger 子代理合入集成分支。

每个子代理以全新上下文出发；子代理之间只靠指针通信（spec、票、研究笔记、commit），不重复搬运信息。
STEP 6 · 收尾三连 /code-review → /pr → /retro

双轴 review 并行跑：Standards（仓库规范 + Fowler 坏味道基线）与 Spec（是否忠实实现原始诉求）互不污染，防止一轴通过掩盖另一轴失败。PR 三段式：最小 Summary 图、前后对照证据、合并危险度（单向门还是双向门 + 爆炸半径）。

/retro 只改环境不改代码：导航指针、自动化检查、编码规范。机械错误落成确定性检查，判断错误落成规范。
04

三条匝道：从别的起点上车

不是所有工作都从「我有个想法」开始。issue 堆积、线上 bug、大雾级目标，各有专用入口，处理完再汇回主流。

匝道 A · /triage
issue 和外部 PR 堆成山的时候
把外部涌入的 issue / PR 当「带代码的 issue」走同一台分诊机器：分类角色（bug / enhancement）× 状态角色（needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix）。分诊动作：查重（按领域概念搜代码仓，不是按请求措辞）、查拒收知识库、复现验证，然后才拷问补全，最后附上一段耐久型 agent 简报。
/to-tickets 产出的票天生就是 agent-ready，绝不再拿去 triage。AI 在跟踪器上发的每条评论都要以「本内容在分诊期间由 AI 生成」开头。
匝道 B · /diagnosing-bugs
一眼看不穿的硬 bug、间歇 flake、两个好版本之间潜入的回退
六相位纪律：先造反馈环（一条已经亲手跑过、对这个 bug 变红、秒级、确定的命令），再复现并最小化，然后排出 3 到 5 个带预测的可证伪假设，逐变量插桩验证，修复之前先写回归测试，最后清理全部调试痕迹。没有红环就不许进假设阶段，这是本技能存在的全部理由。
如果找不到正确的回归测试接缝，这本身就是发现：代码仓架构在阻止 bug 被锁定，记下来交给 /improve-codebase-architecture。
匝道 C · /wayfinder
目标大到看不全路：绿地项目、巨型特性，一个会话装不下
在跟踪器上画一张「地图」issue（label: wayfinder:map），把通往目的地的路切成决策票：研究（AFK，子代理跑）、原型（HITL）、拷问（HITL）、任务（可人工可代理）。每解决一张票，前方战争迷雾退一格，新问题的轮廓才显现出来。票只引用名字不引用编号，阻塞边用跟踪器原生依赖，让人在 UI 里直接看见前沿。
一次会话只解一张票。地图产出的是决策不是交付物；雾散了它移交而非施工：汇入 /to-spec 把链接起来的决策折叠成可构建的计划，跳过这步等于扔掉全部细节。
05

上下文卫生：最贵的资源怎么花

上下文窗口是 agent 的工作记忆，也是最贵的消耗品。原则只有一条：相位边界上做决定，相位中间不纠结。

上下文标尺 · 单位: token 推理劣化区 0 50k 100k ~150k smart zone 一个不断开的窗口: 拷问 → spec → 票 ① /grill-with-docs　② /prototype 支线　③ /to-spec　④ /to-tickets 这段思考是连续的, 中途 compact 或 clear 等于把设计树砍一半 逼近 smart zone → 在最近相位边界 /compact, 带种子续跑 . /implement · 票 01 /implement · 票 02 /implement · 票 03 ……每张票一个全新窗口, 票自包含, 用完即弃 实现阶段（另一头） /retro 要在清窗口之前跑: 它回顾的是这一整场会话, clear 之后只能去翻会话日志
相位边界五选一 Continue（先排除，成本最低）· /clear（什么也不带走）· /handoff（跨 harness、跨目录、给同事、相位中途分叉）· 子代理（ tightly-scoped 任务发独立窗口）· /compact（默认项，压缩后播种新会话）。
子代理纪律 每个子代理以全新上下文出发，有些 harness（如 Codex）默认 fork 父会话，那正是子代理要逃离的上下文，必须显式要求 fresh window。
指针优先于搬运 通信主要靠上下文指针：指向 spec、票、研究笔记、commit。指针指向的内容不复制，仓库里已有的信息不重复。
06

团队落地路线：四周见形

不需要大爆炸式推广。先装、再立规矩、然后挑一个中等特性跑通全程，剩下的交给惯性。

阶段动作验收标准
第 0 周
装机
  • 全员安装技能集：Claude Code 一行 claude plugin install mattpocock-skills@claude-plugins-official，其余 harness 走 marketplace 或 npx skills@latest add mattpocock/skills，二选一，别装两遍。
  • 每个代码仓跑一次 /setup-matt-pocock-skills：定跟踪器、定分诊标签、定词表布局。
 docs/agents/ 三件套齐（issue-tracker · triage-labels · domain）；CLAUDE.md 或 AGENTS.md 出现 ## Agent skills 块
第 1 周
立规矩
  • 建 GLOSSARY.md，哪怕只有 5 个词；建 docs/adr/；写第一版 CODING_STANDARDS.md。
  • 接通护栏：CI 或 pre-commit 跑 lint + typecheck + test。没有护栏本身就是一种发现。
 空跑 /code-review 能找到标准文件；新 PR 的双轴 review 有据可依
第 2 周
跑主线
  • 挑一个中等特性，完整走 ①拷问 → ③spec → ④票 → ⑤实现 → ⑥review + PR。
  • 团队围看一次 /grill-with-docs 现场：这是全工作流里最需要体感的一步。
 票图带 blocking 边；PR 有 Summary 图、前后证据、合并危险度三段
持续
成习惯
  • 每隔几天跑一次 /improve-codebase-architecture，保持代码仓对 agent 可导航。
  • 每次构建后 /retro，机械错误落成 CI 检查，判断错误落成规范。
  • issue 多的仓库把 /triage 排进每周固定时段。
 retro 的改进项有归宿（CI / 规范 / 导航指针），不再重复犯同一个错
07

八条反模式：看见就喊停

这些是工作流自带的保险丝，烧断的时候说明有人在抄近路。近路即远路。

让 agent 自问自答。HITL（人在环）的票只能通过与真人的现场交锋解决；替人回答自己问题的拷问 agent 已经坏了。
没有先红就写实现。先写一堆测试再补实现，测的是想象中的行为形状，对真实变化无感。一次一个垂直切片，先红后绿。
没有反馈环就猜病因。读代码建立理论是本病技能要阻止的确切失败。先有一条对这个 bug 变红的命令，才配进入假设阶段。
拿 /to-tickets 的票去 /triage。分诊只管外部涌入的原始 issue 和 PR；流水线产出的票天生 agent-ready。
spec 和票里写文件路径。它们过期最快。唯一例外：原型产出的决策性片段，裁剪到只剩决策浓度高的部分。
水平切片排期。先写完全部 schema、再写完全部 API 是假垂直。每张票必须穿透全层、独立可验证。
上下文撑爆也不 compact。接近 smart zone 还硬撑，推理质量悄悄崩坏。在最近相位边界压缩，带种子续跑。
指望实现 agent 盯规范。实现者上下文压力最大；规范由 review agent 在 diff 上强制执行，各司其职。
08

技能速查表

27 个已发布技能，按调用权分两栏。人敲的负责编排，模型可自动接管的负责纪律。不知道用哪个，先问 /ask-matt。

USER-INVOKED · 人敲命令（16）

/ask-matt路由器：不知道此刻该用哪个技能，问它
/grill-with-docs拷问 + 沉淀词表与 ADR，主流第一步
/grill-me无代码仓场景的同款拷问，不留痕
/to-spec把当前对话综合成 spec 并发布，不再提问
/to-tickets拆追踪弹票，票票声明 blocking 边
/implement单票或小活，单窗口实现，收尾 review
/implement-spec整份 spec 编排实现，子代理前沿并发
/wayfinder大雾级目标的决策票地图，产出决策
/triage外部 issue / PR 分诊，产出 agent 简报
/improve-codebase-architecture扫描深化机会，出 HTML 报告再拷问
/retro回顾 agent 环境：导航、检查、规范、工具
/setup-matt-pocock-skills每仓一次：跟踪器、标签、词表布局
/handoff把会话压成交接文档，给下一个窗口
/to-questionnaire答案在别人脑子里时，生成问卷发过去
/wait-what消息没听懂？让它用 GLOSSARY 词汇重讲
/teach多会话教学，当前目录即教学工作台

MODEL-INVOKED · 模型自动接管（11）

/grilling访谈原语：轮次、前沿、决策属于人
/domain-modeling打磨领域词表，写 GLOSSARY.md 与 ADR
/codebase-design深模块词汇：接口、深度、接缝、杠杆
/writing-for-agents写给 agent 消费的文档怎么写
/tdd红绿循环：先红后绿，一次一个垂直切片
/code-review双轴并行 review：Standards × Spec
/prPR 三段式：最小图、证据、合并危险度
/diagnosing-bugs六相位诊断环，先红环后假设
/prototype一次性原型回答设计问题，留作一手证据
/research后台子代理查一手来源，产出带引用的笔记
/wizard只有人能点的步骤，编成交互式 bash 向导
misc / in-progress 桶里的技能未发布，不进本表。