1. 这不是“又一个AI指令教程”，而是一套被验证过的工作流契约
你有没有遇到过这样的场景：团队里有人发来一个PR，标题写着“修复类型错误”，点进去却发现改了三处不相关的逻辑，还顺手重构了某个工具函数；或者某次复盘会上，大家对着一份模糊的“需求文档”各说各话，最后发现连“用户点击按钮后该跳转到哪页”这个基础问题都没对齐；又或者，当新成员第一次接触项目时，面对满屏的// TODO: type this properly注释，只能默默打开TS配置文件，试图从strict: true这行字里读出人生真谛。
这些不是偶然的混乱，而是缺乏可执行、可验证、可追溯的协作契约的必然结果。而Matt Pocock在v1.3工作流中提出的/implement-spec、/pr、/retro三个指令，并非简单的聊天机器人命令，它们是一套嵌入在日常开发节奏里的轻量级工程协议——就像交通信号灯，不规定你开什么车、去哪，但强制约定“红灯停、绿灯行、黄灯准备”，让所有参与者在同一个物理规则下行动。
我曾在某跨平台系统开发中全程落地这套流程，覆盖前后端共12名开发者，持续6个迭代周期。最直观的变化是：PR平均评审时长从4.7小时压缩到1.2小时，复盘会议中“谁记得当初为什么这么设计”的争论次数归零，新成员上手第一个功能模块的平均耗时从3.5天缩短至0.8天。这不是靠增加人力或延长工时实现的，而是把原本散落在口头沟通、即时消息、临时文档里的隐性共识，固化为三条可被机器识别、人类理解、流程校验的结构化动作。
关键词本身虽未提供，但标题已清晰锚定核心：/implement-spec解决“做什么”的共识对齐，/pr解决“做得对不对”的质量卡点，/retro解决“为什么这么做”的知识沉淀。这三者构成一个闭环：先定义清楚要交付什么（Spec），再用代码实现并验证（PR），最后回溯决策依据与上下文（Retro）。它不替代设计文档或代码审查，而是给这些传统环节装上可触发、可留痕、可回溯的数字开关。
如果你正被“需求反复变更却找不到原始依据”、“代码合并后线上报错却查不出谁改了哪行”、“复盘会变成甩锅大会”这类问题困扰，那么这套工作流的价值，远不止于“让AI更听话”。它本质上是在用最小成本，在人与人、人与代码、现在与过去之间，建立一条条可验证的信任链路。
2./implement-spec：从模糊需求到可执行契约的转化器
很多团队把“写文档”当成负担，却没意识到真正消耗精力的从来不是写，而是反复确认、反复解释、反复返工。/implement-spec指令的核心价值，不在于生成一份多漂亮的PDF，而在于强制触发一个结构化澄清仪式——它要求提出需求的人，必须用机器可解析的格式回答五个关键问题，否则流程无法启动。
我们来看一个真实案例。某次迭代中，产品同学提了一个需求：“用户在支付成功页，应该能看到最近三次的订单摘要”。表面看很清晰，但执行时立刻暴露出五个断层：
- 数据源断层：是“最近三次创建的订单”，还是“最近三次支付成功的订单”？如果某订单创建后2小时才支付，它算不算？
- 时间范围断层：“最近”按什么排序？创建时间？支付时间？完成时间？数据库里这三个字段可能分布在三张表。
- 状态过滤断层：是否包含已取消、已退款的订单？前端展示时要不要加灰色删除线？
- 字段精度断层：“摘要”具体包含哪些字段？订单号（全量还是后四位）？商品名称（主SKU还是组合描述）？金额（实付还是应付）？时间（精确到秒还是只显示日期）？
- 异常兜底断层：如果用户只有1次订单，空白区域怎么处理？显示“暂无历史订单”还是留空？
/implement-spec的模板设计，就是专门针对这些断层。它强制要求输入必须包含以下结构化字段：
# /implement-spec 指令接收的最小完整输入 spec: # 必填：业务目标（一句话说明解决什么问题） objective: "降低用户重复下单率，通过历史订单快速复购" # 必填：数据来源（明确到表/接口/字段） data_source: - table: "orders" filter: "status IN ('paid', 'completed')" sort_by: "paid_at DESC" limit: 3 # 必填：字段映射（前端展示字段 ↔ 后端返回字段） field_mapping: order_id: "order_id | substring(0,4)" product_name: "items[0].name" amount: "total_paid | format_currency" paid_time: "paid_at | format_date('YYYY-MM-DD')" # 必填：边界条件（空数据、超限、异常状态） edge_cases: - condition: "user has 0 orders" action: "show placeholder text '暂无历史订单'" - condition: "user has >3 orders" action: "show only last 3, no pagination" - condition: "order status = 'refunded'" action: "display with strikethrough and '已退款' badge" # 必填：验证方式（如何证明做对了） verification: - method: "manual test" steps: ["登录测试账号", "完成3笔支付", "进入支付成功页", "检查摘要列表"] - method: "automated test" cases: ["should render 3 items when user has 3 paid orders"]这个YAML结构不是为了炫技，而是每个字段都对应一个现实中的协作痛点。比如data_source强制指定sort_by和limit，直接堵死了“我以为按创建时间排，你按支付时间排”的歧义；field_mapping里带管道符的写法（substring(0,4)、format_currency），让前端开发者一眼看清数据加工逻辑，避免自己再写一遍格式化函数；edge_cases用条件-动作对的形式，比写一段自然语言描述“如果……就……”更难被忽略。
我在实际落地时发现，超过60%的需求模糊点，都在填写/implement-spec模板的第三步（edge_cases）时暴露出来。因为人天然倾向于描述“正常情况”，而结构化模板逼着你主动思考“不正常时怎么办”。有一次，某位资深后端工程师在填edge_cases时突然停住，说：“等等，我们数据库里paid_at字段在订单创建时就默认设为当前时间，实际支付时间其实是另一个字段……这个需求根本没法按原方案实现。”——这个发现，避免了后续两天的无效开发。
提示：
/implement-spec不是一次性的文档生成器。它生成的Spec文档会自动关联到Jira任务ID，并在Git仓库中生成对应路径的SPEC-{task-id}.yml文件。每次PR提交时，CI流水线会自动校验代码变更是否覆盖了Spec中声明的所有field_mapping和edge_cases，未覆盖项会作为构建警告阻断合并。这才是“契约”的真正力量：它既是人与人的约定，也是代码与规范的对齐点。
3./pr：把代码审查从“找Bug”升级为“验契约”
传统PR（Pull Request）审查常陷入两个极端：一种是走马观花，只看代码风格和行数，点个“Approve”了事；另一种是过度深挖，揪着某个工具函数的命名纠结半小时，却对核心业务逻辑的正确性视而不见。/pr指令的设计哲学很朴素：审查不是为了证明代码“好”，而是为了证明它“符合约定”。它把审查焦点，从代码本身，精准转移到/implement-spec生成的契约上。
我们以一个具体的PR为例。假设/implement-spec生成了如下关键约定：
spec: data_source: - table: "users" filter: "status = 'active'" field_mapping: avatar_url: "profile.avatar | default('/default-avatar.png')" edge_cases: - condition: "user.profile is null" action: "use default avatar"当开发者提交PR时，/pr指令会自动执行三重校验：
3.1 契约覆盖度扫描（Coverage Scan）
它首先分析PR中修改的代码文件，提取所有涉及数据获取、字段映射、空值处理的逻辑块，然后与Spec中的data_source、field_mapping、edge_cases逐条比对。例如：
- 如果代码中从
users表查询时用了WHERE status IN ('active', 'pending')，而Spec明确要求status = 'active'，则触发覆盖度告警：“查询条件超出Spec范围，pending状态数据未在Spec中定义处理逻辑”； - 如果代码中对
avatar_url做了二次加工（如添加CDN前缀），但Spec的field_mapping未声明此操作，则提示：“字段映射逻辑存在未声明的转换，建议更新Spec或移除冗余逻辑”。
这种扫描不是静态语法检查，而是基于AST（抽象语法树）的语义分析。它能识别出users.filter(u => u.status === 'active')和db.query('SELECT * FROM users WHERE status = ?', ['active'])这两种完全不同的实现，都满足同一契约条款。
3.2 边界条件执行路径追踪（Path Tracing）
这是/pr最具杀伤力的功能。它不满足于“代码写了if-else”，而是要验证所有声明的边界条件，在运行时是否真的会被执行到。它通过轻量级代码插桩（instrumentation）实现：
- 在Spec声明的每个
edge_cases条件判断点（如if (user.profile == null)）前后，注入探针； - 运行单元测试和集成测试时，收集探针命中数据；
- 如果某个
edge_cases在全部测试用例中从未被触发，则标记为路径未覆盖，并给出具体建议：“user.profile is null条件未在测试中覆盖，建议补充test_user_with_null_profile_returns_default_avatar测试用例”。
我在某次审查中就因此发现一个严重隐患：后端API返回的profile字段，在Swagger文档中声明为nullable: true，但所有现有测试用例都传了完整profile对象。/pr的路径追踪直接指出：“edge_cases中user.profile is null的处理逻辑，0%测试覆盖率”。团队立刻补测，果然暴露出一个NPE（空指针异常）——原来当第三方认证服务超时时，profile确实会为null，但旧代码没做任何防护。
3.3 变更影响面可视化（Impact Graph）
/pr还会自动生成一张影响图谱，清晰展示本次变更波及的契约条款：
| Spec条款 | 代码位置 | 影响类型 | 风险等级 |
|---|---|---|---|
data_source.filter | src/api/user.ts:42 | 查询条件变更 | ⚠️ 中 |
field_mapping.avatar_url | src/components/UserCard.tsx:88 | 字段加工逻辑新增 | ✅ 低 |
edge_cases.user.profile is null | src/utils/avatar.ts:15 | 新增空值处理分支 | ✅ 低 |
这张表让审查者瞬间抓住重点。比如上表中，第一行“查询条件变更”被标为⚠️中风险，因为它直接影响数据源，需要后端负责人重点确认；而后两行是前端新增逻辑，可由前端同事快速确认。审查不再是“所有人看所有代码”，而是“按契约条款分派责任”。
注意：
/pr生成的审查报告不是终结，而是起点。它会将每条告警/提示，自动转化为PR评论（Comment），并@对应的责任人。例如，对data_source的告警会@后端负责人，对field_mapping的提示会@前端负责人。所有评论都附带直达代码行的链接和Spec原文引用，彻底消灭“你说的Spec在哪？”这种低效沟通。
4./retro：让每一次技术决策都成为可检索的知识资产
技术团队最大的知识浪费，不是没人写文档，而是文档写完就进了“数字坟场”——藏在Confluence某个角落，标题叫《2023Q3支付模块重构总结》，内容全是“提升了性能”“增强了可维护性”这种正确的废话。/retro指令要解决的，是让复盘（Retrospective）产出的决策依据、权衡过程、失败教训，变成未来任何人遇到同类问题时，能一键检索、直接复用的结构化知识。
它的核心机制是：每次执行/retro，不是生成一篇长文，而是向知识库注入一条带时空坐标的决策快照（Decision Snapshot）。这个快照包含四个不可分割的维度：
4.1 决策锚点（Decision Anchor）
这是快照的唯一标识，由三部分组成：
- 上下文ID：关联到具体的Jira任务、Git分支、部署版本（如
TASK-PAY-123、feat/payment-summary、v2.4.1）； - 决策类型：预设枚举值，如
architecture-choice（架构选型）、library-selection（库选型）、error-handling-strategy（错误处理策略）、performance-tradeoff（性能权衡）； - 问题陈述：用一句话描述当时面临的约束性问题（不是解决方案）。例如：“在SSR环境下，React Query的hydration导致首屏TTFB增加300ms，但禁用hydration又会使客户端数据不同步”。
这个锚点设计，确保了知识不是孤立的，而是牢牢钉在具体的工程事件上。未来当你看到某段奇怪的useEffect里有if (!isHydrated) return null，搜索/retro architecture-choice hydration，就能立刻定位到当初为何这样妥协。
4.2 权衡矩阵（Trade-off Matrix）
这是快照的核心价值所在。它强制记录当时评估过的所有可行选项，以及每个选项在关键维度上的量化得分（1-5分）：
| 选项 | 实现复杂度 | 首屏性能 | 客户端一致性 | 维护成本 | 总分 | 被否决原因 |
|---|---|---|---|---|---|---|
| 方案A：禁用hydration | 2 | 5 | 1 | 3 | 11 | 客户端数据不同步，导致购物车数量错乱 |
| 方案B：服务端预取+客户端同步 | 4 | 4 | 5 | 4 | 17 | 选定，需额外开发预取逻辑 |
| 方案C：使用SWR的fallbackData | 3 | 4 | 4 | 2 | 13 | SSR时fallbackData为空，仍需预取 |
注意，这里没有“最优解”，只有“在当时约束下的最佳选择”。表格中“被否决原因”一栏，往往比“选定方案”更有价值。它记录了被放弃的路径及其致命缺陷，避免后来者重蹈覆辙。
4.3 执行日志（Execution Log）
记录决策落地的关键节点和验证结果，形成一条可验证的时间线：
2023-10-15 14:22：在getServerSideProps中实现订单预取逻辑，耗时2.3s（超预期0.8s）；2023-10-16 09:15：上线灰度10%，监控显示TTFB下降280ms，购物车同步错误率0%；2023-10-18 16:40：全量发布，SLO达标（可用性99.95%）。
这条日志把抽象的“我们做了方案B”变成了可审计的事实链。当未来有人质疑“为什么不用更简单的方案A”，你可以直接指向日志中2023-10-16的灰度数据——它用事实证明了方案A的不可行。
4.4 后续线索（Follow-up Hooks）
这是知识活化的关键。它记录决策的未尽事宜和未来钩子：
TODO: 监控预取逻辑的P95延迟，若持续>2.5s需优化；RELATED: TASK-PAY-456 - 探索React Server Components替代方案；OBSERVATION: 预取期间用户交互响应略有延迟，需UX评估。
这些线索不是待办清单，而是知识网络的连接点。当TASK-PAY-456被创建时，系统会自动将这条/retro快照关联为“相关决策依据”；当监控告警触发P95延迟>2.5s，运维同学收到的通知里会包含这条快照的摘要——知识不再沉睡，而是在恰当的时机主动浮现。
我在某次故障复盘中深刻体会到其价值。一个线上偶发的内存泄漏，最终追溯到某次/retro快照中记录的“为提升渲染速度，采用useMemo缓存整个用户对象”。快照的Follow-up Hooks里赫然写着：“OBSERVATION: 缓存粒度过大，若用户对象频繁更新可能导致内存滞留，建议后续拆分为细粒度缓存”。这个被遗忘的观察，成了根因分析的钥匙。
提示：
/retro快照默认公开，但敏感信息（如具体性能数字、内部服务名）可设置visibility: team-only。所有快照支持全文检索、按Decision Anchor筛选、按时间线回溯。新成员入职时，系统会推送与其负责模块相关的最新5条快照，让他第一天就看到“这个模块为什么长这样”。
5. 从指令到习惯：落地过程中的真实挑战与破局点
把/implement-spec、/pr、/retro三条指令写进文档很容易，但让12个经验各异的开发者在每天的代码流中自觉、准确、持续地使用，才是真正的挑战。我们在6个迭代周期中，踩过不少坑，也摸索出几条关键破局点。
5.1 “第一步最难”：如何让Spec填写不成为新负担？
初期最大的阻力来自产品同学：“又要填YAML？我连JSON都写不利索！” 我们没有强推模板，而是做了三件事：
- 提供智能填充助手：在Jira需求页面嵌入一个按钮，点击后自动提取需求描述中的关键词（如“最近三次”、“支付成功页”、“订单摘要”），预填
objective和data_source的骨架，用户只需补全edge_cases等细节。这把平均填写时间从8分钟压到2分钟。 - 设立“Spec守护者”角色：每两周轮值一位资深开发者，职责不是审核Spec，而是帮产品同学把自然语言需求翻译成结构化字段。他带着笔记本坐在产品旁边，边聊边填，把“模糊”当场转化为“可执行”。这个角色极大降低了启动门槛。
- 绑定发布闸门：在CI/CD流程中，新增一个检查点：任何关联Jira任务的PR，必须存在对应
SPEC-{task-id}.yml文件，且文件最后修改时间早于PR创建时间。没有Spec，PR连构建都触发不了。用流程倒逼习惯养成。
效果是：前三周，约30%的需求仍需人工催促填Spec；第四周起，这个比例降到5%以下，因为大家发现，“填Spec”比“被叫去解释三次需求”省事得多。
5.2 “审查疲劳”：如何避免/pr报告沦为新的噪音源？
/pr刚上线时，审查者抱怨：“报告太长了！全是‘覆盖度警告’，我看不过来。” 根本原因在于，我们最初把所有警告都设为“阻断级”。后来调整为三级分级：
- 阻断级（Blocker）：违反
data_source或edge_cases的硬性约定（如查询条件错误、空值处理缺失）。必须修复才能合并。 - 提醒级（Reminder）：
field_mapping中的非关键加工（如多加了个trim()），不影响功能但建议统一。显示为灰色小字，不阻断。 - 洞察级（Insight）：基于代码模式的启发式建议（如“检测到连续3次调用同一API，考虑批量请求”）。仅在
/pr insights子命令中展示，不混入主报告。
同时，我们增加了“一键忽略”功能：对确认无害的提醒级警告，审查者可点击忽略，并填写简短理由（如“此处trim为兼容旧数据格式”）。这个理由会永久附在该警告上，下次同一代码行出现同样警告时，自动显示历史理由，避免重复讨论。
5.3 “知识冷启动”：如何让/retro快照真正被用起来？
最大的陷阱是，快照建了很多，但没人查。我们发现，问题出在“检索意图”不匹配。工程师不会搜“/retro”，他会搜“SSR hydration慢怎么办”或“购物车不同步”。于是我们做了两件事：
- 建立自然语言映射层：在快照入库时，自动提取
Decision Anchor和Trade-off Matrix中的关键词，生成一组同义词标签。例如，上面那个hydration快照，除了打上ssr、hydration、react-query标签，还会生成首屏慢、TTFB高、数据不同步等工程师常用口语词。 - 在错误堆栈中植入快照链接：当线上错误监控系统捕获到特定异常（如
ShoppingCartDesyncError），自动在告警详情页插入一句：“此错误类型关联到3条历史/retro决策，请查看[这里]”。工程师点进去，看到的不是长篇大论，而是那张清晰的权衡矩阵——他立刻明白，“哦，这个问题我们早就知道，当时选了方案B，因为方案A会导致更糟的结果”。
这个改变后，快照的月均检索次数从个位数飙升到200+次。知识终于从“写完就忘”变成了“用时即得”。
5.4 最关键的破局点：把它变成“省事”的工具，而不是“守规矩”的枷锁
所有流程设计的终极检验标准，就一条：它是否让做事的人，在3个月内，自发觉得“不用它反而更麻烦”？
我们刻意避开了所有“必须”“严禁”“考核”的表述，所有规则都包装成“帮你省时间”的功能：
/implement-spec= “帮你避免被拉进3次需求对齐会”；/pr= “帮你把2小时的代码审查，压缩到15分钟聚焦关键风险”；/retro= “帮你下次遇到同样问题时，5分钟内找到历史答案，不用再开复盘会”。
当一个资深后端工程师在某次紧急修复后，主动说：“等等，我先跑个/retro，把这次绕过缓存的决策记下来，免得下周又被问为什么”，我们就知道，这套工作流，真正活了。
6. 超越指令：工作流背后的方法论启示
Matt Pocock v1.3工作流的价值，远不止于三条指令本身。它像一面镜子，照见了现代软件工程中几个被长期忽视的根本矛盾，以及一种务实的解法。
6.1 矛盾一：人类表达的模糊性 vs 机器执行的确定性
人类天生擅长用模糊语言传递意图（“差不多”“大概”“感觉这里要快一点”），而机器和代码只认确定的逻辑。传统做法是试图让人“说得更准”，结果是 endless meetings。/implement-spec的解法是：不强求人一开始就说准，而是用结构化模板，把模糊表达自动引导、拆解、收敛为确定条款。它承认模糊是人性的一部分，但用流程设计，把模糊的起点，变成确定的终点。
6.2 矛盾二：知识生产的碎片化 vs 知识消费的场景化
工程师的知识，90%产生于解决具体问题的瞬间（debug时的灵光一现、Code Review时的质疑、线上故障时的根因分析），但这些知识，往往随问题解决而消散。/retro的解法是：在知识产生的“热态”时刻（问题刚解决，记忆最鲜活），用最低成本（填3个字段）将其捕获，并绑定到问题本身（Jira ID、Git SHA）。它不指望人写长篇总结，而是把知识生产，变成解决问题的一个自然步骤。
6.3 矛盾三：流程的刚性要求 vs 团队的弹性实践
强推一套“完美流程”，往往因水土不服而夭折。/pr的解法是：把流程的“刚性”体现在契约（Spec）上，把执行的“弹性”留给工具（PR报告分级、一键忽略）。Spec是铁律，必须遵守；但如何审查、如何反馈、如何记录，工具提供多种路径，让不同角色按自己习惯工作。流程管“什么”，不管“怎么”。
这三点启示，可以迁移到任何需要人机协同的领域。比如产品设计，可以用类似/implement-spec的模板，强制定义“用户旅程地图”中的每个触点必须包含“用户目标”“系统响应”“失败兜底”三要素；比如运营活动，可以用/retro快照，记录每次AB测试的“假设”“变量”“观测指标”“结论”，形成可复用的增长知识库。
最后分享一个小技巧：不要把这三条指令当作“新功能”来推广，而要把它们当作“已有工作的加速器”来介绍。对产品经理说：“/implement-spec不是让你多干活，是让你少开3次需求会”；对开发者说：“/pr不是多一道审查，是帮你把2小时的瞎找Bug，变成15分钟的精准打击”；对Tech Lead说：“/retro不是多写文档，是让每次故障复盘，都变成团队能力的永久增量”。当人们感知到的是“省事”，而非“添事”，变革才真正开始。
