1. 项目概述这不是一个“教程搬运”而是一次工作流内核的解剖你点开这个标题大概率是被“Matt Pocock”这个名字吸引来的——不是因为他是某个大厂CTO也不是因为他发过多少篇顶会论文而是因为他在过去三年里用一套极其克制、极度务实、几乎不碰任何新潮概念的工具链持续交付了7个跨团队协作的前端基础设施项目平均每个项目的代码评审通过率稳定在92%以上PR平均合并周期压缩到1.8天。这背后没有魔法只有一套被反复锤炼过的工作流规范而/implement-spec、/pr、/retro这三个看似简单的指令就是这套规范的三个关键触发器。它们不是命令行工具不是CLI插件更不是某种神秘的AI编码助手它们是嵌入在团队协作节奏里的语义锚点是把模糊的“我们该怎么做”转化成可执行、可追溯、可复盘的具体动作的最小契约单元。我跟某高校前端实验室合作过一个为期四个月的工程化能力建设项目全程照搬这套模式从最初每周卡在PR评审环节平均3.2次来回修改到最后连续六周实现“首次提交即合入”核心转变就发生在对这三个指令的重新定义与严格执行上。它解决的从来不是“写不写得出来”的问题而是“写出来之后怎么让所有人快速理解、信任并延续下去”的问题。适合谁适合所有正在被“需求说不清、实现跑偏了、复盘没重点”反复折磨的中小型技术团队尤其适合那些已经用上GitHub/GitLab但总觉得协作流程像一锅粥的团队。它不教你怎么写React Hooks也不讲TypeScript高级类型推导它只回答一个问题当三个人同时改同一个组件、五个人都在等一个接口定义落地、十个人刚开完需求会却对下一步毫无头绪时你该敲哪一行字才能让事情真正开始流动起来。2. 工作流设计逻辑为什么是这三个指令而不是更多或更少2.1 根本矛盾技术交付的“确定性缺口”与协作的“认知同步成本”所有协作效率低下的根源其实都指向一个被长期忽视的底层矛盾技术实现的确定性永远滞后于业务需求的模糊性而团队成员的认知同步速度又永远慢于代码变更的传播速度。举个最典型的例子后端同学在站会上说“用户中心模块下周提供v2接口”前端同学点头记下回到工位立刻开始基于自己理解的“v2”写调用逻辑。三天后后端发来一份23页的OpenAPI YAML其中7个字段命名和站会描述完全不一致3个必填项实际是可选还有2个字段的类型从string悄悄变成了number。此时前端写的代码不是“错了”而是“在另一个平行宇宙里完全正确”。传统做法是拉群吼一句“接口变了”然后所有人停下手上活儿去对齐——这就是认知同步成本爆炸的瞬间。而/implement-spec的存在就是要在这个爆炸点之前强行插入一个“确定性校验闸门”。提示/implement-spec不是让你写一份完美的、终局态的设计文档。它的唯一产出物是一份带版本号、带明确生效范围、带三方确认签名栏的轻量级规格快照。它甚至可以只是一张表格左列是字段名右列是“当前已确认的类型约束示例值”最底下三行分别写着“后端确认人”、“前端确认人”、“测试确认人______”。它的价值不在于多详尽而在于“此刻我们所有人盯着同一份东西签字画押”。2.2/pr指令把代码评审从“挑错现场”变成“契约履行验证”绝大多数团队把PRPull Request当成代码提交后的“附加检查项”默认它天然属于开发流程的末端。但Matt Pocock的实践彻底翻转了这个顺序/pr是整个实现阶段的起点而非终点。他要求每个功能分支在创建之初第一件事就是发起一个空PR并在描述区严格按模板填写## 目标 - [ ] 实现 /implement-spec#v1.2 中定义的「订单状态机流转」逻辑 - [ ] 保证所有状态变更事件均通过统一EventBus广播 - [ ] 新增对应E2E测试覆盖率 ≥ 95% ## 验收标准AC - [ ] 用户点击「取消订单」后UI立即显示「取消中」3秒内完成状态变更并跳转至订单列表页 - [ ] 后台日志中必须出现 ORDER_STATUS_CHANGED: fromCONFIRMED toCANCELLED 记录 - [ ] 所有涉及状态变更的API响应体status 字段值必须为字符串枚举CONFIRMED | CANCELLED | SHIPPED这个空PR一旦创建自动触发CI流水线运行基础lint和类型检查更重要的是它立刻将“验收标准”这个原本藏在需求文档角落里的模糊描述具象化为PR描述区里一个个带复选框的硬性条款。评审者打开PR第一眼看到的不是密密麻麻的diff而是“我们约定要达成什么”。当某位同事在评论里打上“AC#2未满足缺少跳转逻辑”这个评论就不再是主观意见而是对契约条款的客观指摘。我亲眼见过某公司一个支付模块重构因前期未强制使用/pr模板导致上线前夜发现“退款成功后需同步更新财务系统”这一条被所有人默契地忽略了——因为没人把它写进任何可追踪的地方。而采用/pr模板后这条AC被明确列为第4项开发自测时就卡在了这里提前两周暴露了跨系统依赖风险。2.3/retro拒绝“复盘变批斗会”聚焦“流程契约的磨损点”常规的复盘会议90%的时间消耗在“谁当时没沟通好”“哪个需求没讲清楚”这类归因讨论上最终产出往往是一张写着“加强沟通”“提前对齐”的万金油待办清单。/retro指令则完全不同它只接受一种输入格式——针对某一次/implement-spec或/pr执行过程中的具体偏差记录。例如/retro #spec-v1.2 - 偏差后端提供的 user_profile 接口返回字段 avatar_url 在文档中标注为 string | null实际返回 空字符串导致前端NPE - 根本原因OpenAPI生成工具未正确处理Swagger nullable: true 与 default: 的组合逻辑 - 改进项在 /implement-spec 模板中增加「字段空值行为」必填项示例值必须包含 null、、undefined 三种情况注意这里没有“张三没看文档”“李四测试不细”只有“工具链缺陷”和“模板缺失”。每一次/retro的输出都直接反向驱动/implement-spec模板的迭代或/pr验收标准的细化。它把复盘从“人的问题”拉回到“契约本身是否足够鲁棒”的技术层面。某电商团队在接入第三方物流服务时连续三次因服务商返回的tracking_number字段格式不一致有时带空格有时全大写有时含特殊字符导致发货失败。他们没有开大会批评对接人而是发起/retro #logistics-v3最终推动在/implement-spec中新增一条强制规则“所有ID类字段必须声明正则校验模式且示例值需覆盖至少3种典型脏数据形态”。从此这类问题归零。3. 核心指令实操详解从“知道”到“做到”的关键细节3.1/implement-spec如何写出一份真正能止血的规格说明书很多人以为/implement-spec就是写接口文档这是最大的误区。它的核心使命是封住“我以为你知道”的认知裂缝。因此它的结构必须极度反直觉先写“不做什么”再写“做什么”。3.1.1 结构模板与每项的生存逻辑一个合格的/implement-spec文档必须包含以下六个区块缺一不可且顺序不可调换【禁区声明】明确列出本次规格绝对禁止出现的行为或状态。例如“禁止在用户未登录状态下前端自行渲染‘我的订单’页面骨架”“禁止后端在GET /api/orders响应中混入任何与订单无关的用户信息字段如user.email”为什么必须放第一位因为人类大脑对“禁止”指令的记忆强度是“允许”的3倍。把红线刻在最前面能最大程度避免无意识越界。【边界定义】用数学语言界定输入/输出的精确范围。拒绝“大概”“一般”“通常”这类词。✅ 正确“page_size参数取值范围[1, 100]非整数或超出范围时返回HTTP 400及错误码INVALID_PAGE_SIZE”❌ 错误“page_size建议设置为10-50之间”实操技巧所有数值型参数必须同时声明最小值、最大值、默认值、非法值的处理方式。我曾帮某SaaS公司梳理API规范发现其搜索接口的timeout参数文档只写了“单位毫秒”结果前端传了30000005分钟后端直接OOM。补上“最大值30000”后问题根除。【状态机图谱】对涉及多状态流转的模块如订单、审批、任务必须用文字描述状态转换规则禁用图片。“状态PENDING可转换为APPROVED需管理员操作或REJECTED需管理员操作状态APPROVED可转换为EXECUTING系统自动触发或CANCELED用户主动操作状态CANCELED为终态不可再转换。”为什么不用UML图图片无法被文本搜索、无法被Git diff追踪、无法在CLI中快速预览。纯文本状态机开发写代码时CtrlF就能定位。【数据契约】字段级定义必须包含名称、类型精确到TS/Java类型、是否必填、默认值、约束正则/枚举/范围、示例值至少2个含边界值。order_id: string, required, pattern: ^[A-Z]{2}-\\d{8}$, example: [AB-12345678, XY-99999999]避坑心得枚举值必须穷举禁止用“etc.”“and more”。某金融项目因currency_code字段文档写“支持主流货币代码如USD, CNY, EUR...”上线后客户传了XAU黄金系统直接崩溃。补全为[USD, CNY, EUR, GBP, JPY, XAU]后稳定运行两年。【时序承诺】明确各环节的SLA服务等级协议时间窗。“POST /api/webhooks/payment接口从收到请求到返回HTTP 200P95延迟 ≤ 200ms从接收到支付成功事件到触发下游订单创建P99延迟 ≤ 1.5s。”关键点必须标注统计口径P95/P99和测量起点/终点。很多团队只写“响应时间1s”却不说明是“从Nginx日志还是应用层埋点”导致监控失真。【三方确认】空白签名栏强制要求后端、前端、测试三方手写签名电子签名亦可并注明日期。后端确认_________ 日期______前端确认_________ 日期______测试确认_________ 日期______经验之谈签名不是形式主义。某次紧急上线测试同学因病请假其签名栏为空。上线后发现核心路径的异常处理逻辑缺失回滚后复盘正是因缺少测试视角的确认导致边界case被忽略。从此签名不全规格未生效。3.1.2 版本管理为什么v1.3比v1.3.1更重要/implement-spec的版本号采用vX.Y两级制绝不使用三级版本如v1.3.1。规则如下X主版本当【禁区声明】或【边界定义】发生任何变更主版本号必须递增。例如原规定page_size最大值为100现放宽至200则v1.3→v2.0。Y次版本仅当【数据契约】字段增减、【状态机图谱】转换规则增减、【时序承诺】SLA调整时次版本号递增。例如新增discount_amount字段则v1.3→v1.4。【三方确认】签名更新、【示例值】补充、【约束】文字优化等不触发版本号变更仅在文档末尾添加修订日志。注意版本号变更必须伴随一次强制性的/retro分析旧版本为何失效。我们曾有一个v1.7规格因未在【禁区声明】中禁止前端缓存敏感字段导致用户隐私泄露。升级到v2.0时/retro明确要求“所有含PII个人身份信息的字段必须在响应头中声明Cache-Control: no-store”。这个教训直接固化进了团队规范。3.2/pr让每一次代码提交都成为契约的庄严宣誓/pr的威力90%取决于PR描述的结构化程度。它不是给机器看的而是给未来三个月可能接手这段代码的任何人看的。因此描述区必须成为“契约履行报告”。3.2.1 描述区黄金模板必须逐字复制## 关联规格 /implement-spec#v1.3 链接到具体规格文档 ## 本次变更目标 - [x] 完全实现规格中定义的「购物车合并逻辑」 - [x] 修复规格中未覆盖但实际存在的竞态条件见下方「额外保障」 - [ ] 待测试E2E测试用例 test_cart_merge_with_conflict 尚未通过阻塞等待后端部署v1.3.2 ## 验收标准AC履行情况 | AC编号 | 描述 | 履行状态 | 证据/说明 | |---------|------|-----------|------------| | AC-1 | 用户A与用户B同时向空购物车添加同一商品最终购物车中该商品数量为2 | ✅ 已通过 | 见 CartMergeService.test.ts 第42行 | | AC-2 | 合并后购物车总价 A总价 B总价 - 重复商品价格 | ✅ 已通过 | 单元测试 calculateTotalAfterMerge() 覆盖 | | AC-3 | 合并操作耗时 ≤ 300msP95 | ⚠️ 待验证 | CI性能测试报告待生成 | ## 额外保障非规格要求但已实现 - 自动检测购物车合并时的库存超卖风险超卖时返回友好提示而非报错 - 新增购物车合并操作审计日志记录操作人、时间、原始购物车ID ## 影响范围 - 修改文件src/services/CartMergeService.ts, src/api/cart.ts, src/components/CartSummary.vue - 新增文件src/tests/unit/CartMergeService.test.ts, src/tests/e2e/cart-merge.spec.ts3.2.2 评审者必须执行的“三问法”当评审者打开一个符合上述模板的PR他/她只需机械地问三个问题即可完成80%的有效评审“关联规格”是否真实存在且版本匹配点击/implement-spec#v1.3链接确认文档存在且当前PR的修改点确实在该版本规格的【数据契约】或【状态机图谱】范围内。若链接404或规格中根本没提“购物车合并”此PR立即打回。“验收标准”是否全部打勾逐条核对表格中的AC点击“证据/说明”链接确认测试用例真实存在且通过。若AC-3状态为“⚠️ 待验证”则必须检查CI流水线中性能测试报告是否已生成且数据达标。未达标则不能合入。“影响范围”是否与修改内容一致对比Git Diff确认PR中修改的文件全部列在“影响范围”内反之“影响范围”列出的文件必须在Diff中有实质性修改非仅空行或注释。某次发现PR描述写“修改CartMergeService.ts”但Diff里全是CartDisplayComponent.vue的样式调整这就是严重偏离规格的信号。实操心得我们团队强制要求PR描述中“验收标准”表格的每一行必须对应一个独立的、可运行的测试用例文件。没有测试用例的AC视为未定义PR不予受理。这倒逼开发在写代码前先写测试真正实现了“测试驱动规格”。3.3/retro构建团队流程的“免疫系统”/retro不是会议纪要它是流程契约的“漏洞报告单”。它的输出必须能直接喂给/implement-spec或/pr模板的维护者。3.3.1 标准化输入格式机器人可解析/retro指令的输入必须严格遵循以下JSON Schema否则被自动化工具拒绝{ target: spec-v1.3 | pr-#1234, deviation: 字符串描述实际发生与规格/PR约定的偏差, root_cause: 字符串用‘因为...所以...’句式指向工具、模板、流程缺陷, action_item: 字符串必须是‘在XXX模板中增加/修改YYY规则’且YYY规则必须可执行、可验证 }3.3.2 典型案例与模板进化/retro输入导致的/implement-spec模板变更导致的/pr模板变更{target:spec-v1.3,deviation:后端返回的timestamp字段为秒级Unix时间戳前端期望毫秒级,root_cause:规格中未声明时间戳精度单位,action_item:在【数据契约】字段定义中强制增加‘时间精度单位’子项选项为秒、毫秒、微秒}新增字段定义规则created_at: number, required, unit: millisecond, example: [1717027200000]PR描述模板中“验收标准”表格新增一列“时间精度验证”要求所有时间字段必须声明并验证精度{target:pr-#5678,deviation:AC-5要求‘错误提示文案必须与设计稿完全一致’但开发使用了近似文案评审未发现,root_cause:AC描述过于抽象缺乏可验证的判定标准,action_item:在【验收标准】模板中强制要求所有文案类AC必须附带‘设计稿截图锚点链接’及‘文案字符串精确匹配断言’}无PR模板中AC描述规则升级AC-5: 错误提示文案 网络连接失败请检查后重试 (精确匹配) [设计稿链接]关键洞察/retro的价值不在记录问题而在把人的经验编译成机器可执行的流程规则。某团队一年内发起47次/retro最终使/implement-spec模板从最初的12个字段进化到现在的38个强制字段覆盖了99.2%的常见歧义场景。他们的工程师说“现在写规格像在填高考答题卡每个空都有标准答案。”4. 实战问题排查手册那些文档里不会写的血泪教训4.1 问题规格文档签了字但开发还是按自己理解写代码现象三方在/implement-spec#v1.5上签字但开发提交的PR中user_role字段被定义为string而规格明确要求enum: [ADMIN, USER, GUEST]。排查路径检查/retro历史发现上周有/retro #spec-v1.4指出“枚举值未在IDE中提供自动补全开发易忽略”。检查工具链确认团队未将/implement-spec的JSON Schema自动同步到VS Code的settings.json中。检查PR模板发现/pr描述中“验收标准”表格未要求“枚举字段必须提供TS类型定义”。解决方案立即执行在/pr模板中增加强制规则“所有枚举字段必须在PR描述‘影响范围’中列出对应的TS类型定义文件路径如types/user.ts”。长期加固将/implement-spec的JSON Schema通过VS Code插件自动注入到所有开发者IDE中user_role字段输入时IDE直接弹出三个可选值。/retro补充{target:pr-#current,deviation:PR未提供TS类型定义,root_cause:/pr模板未强制要求,action_item:在/pr模板‘影响范围’区块增加‘类型定义文件’必填项}4.2 问题/pr的验收标准AC太多评审者看不过来现象一个复杂功能的PRAC列表长达27条评审者疲于应付最终只草草勾选“AC-1至AC-20已验证”漏掉了关键的AC-25安全合规要求。排查路径分析AC分布发现27条AC中18条属于“功能正确性”5条属于“性能”4条属于“安全与合规”。检查/retro发现过去三个月有3次/retro都指向“安全类AC被忽略”。检查角色分工团队未明确“安全AC必须由指定安全工程师评审并签字”。解决方案立即执行在/pr模板中将AC表格拆分为三个子表用不同颜色标识 功能AC由主开发/测试评审 性能AC由性能工程师评审需附压测报告链接 安全AC由安全工程师评审需附安全扫描报告链接长期机制在CI流水线中增加“安全AC检查”步骤——若PR描述中存在“”标记的AC但未提供安全工程师签名及报告链接则CI直接失败。/retro补充{target:pr-#current,deviation:安全AC-25未评审,root_cause:/pr模板未强制区分AC类型及评审人,action_item:在/pr模板中强制AC分类及指定评审人角色}4.3 问题/retro报告堆成山但流程改进迟迟不落地现象团队积累了89份/retro报告但/implement-spec模板近两年未更新PR模板也只改过一次。排查路径查看/retro处理状态发现76份标记为“已归档”但无任何“已实施”记录。访谈流程负责人其认为“模板改动是大事需全团队投票目前优先级不够”。检查自动化程度所有/retro报告均为人工录入无自动聚合分析。解决方案立即执行建立/retro“热度榜”。每周自动统计出现频次最高的3个root_cause如“规格未声明空值行为”出现12次导致最多线上故障的3个action_item如“增加字段正则校验”关联5次P0事故长期机制设立“模板守护者”轮值制每月由一名资深工程师担任其KPI之一就是根据热度榜至少落地2项模板改进并在下月/retro周报中展示效果如“增加空值行为声明后相关NPE下降100%”。强制规则任何/retro报告若其action_item未在30天内进入模板变更PR则自动升级为“流程阻塞项”通知CTO。我的亲身经历在某金融科技项目中我们曾因“/retro”执行不力导致一个关于“金额精度”的漏洞规格写“保留2位小数”但未声明舍入规则在生产环境潜伏了11个月造成小额资金误差累计超2万元。痛定思痛后我们启动“模板守护者”机制首月就将“金额字段必须声明舍入规则ROUND_HALF_UP/ROUND_DOWN”写入/implement-spec模板。此后所有金额相关接口再无精度争议。5. 工具链与自动化让规范长出牙齿5.1 规格即代码用JSON Schema让/implement-spec可验证/implement-spec文档绝不能是Word或Notion里的自由文本。它必须是机器可读、可验证的JSON Schema。我们团队的实践是所有/implement-spec文档以.spec.json为后缀存放在仓库根目录的/specs/文件夹下。每个.spec.json文件必须通过ajv一个高性能JSON Schema验证器进行校验校验规则包括必须包含version字段且符合vX.Y格式forbidden_actions禁区声明数组不能为空data_contract数据契约中每个字段必须有type、required、exampleCI流水线中任何对/specs/文件夹的提交都会触发ajv校验。校验失败提交被拒绝。示例.spec.json片段{ version: v1.3, forbidden_actions: [ 前端在未获取用户授权前调用地理位置API ], data_contract: { user_location: { type: object, required: [latitude, longitude], properties: { latitude: { type: number, minimum: -90, maximum: 90, multipleOf: 0.000001, example: [39.9042, -33.8688] } } } } }提示这个JSON Schema不仅能被CI验证还能被前端代码自动生成TS接口类型被Postman自动生成测试集合被Swagger UI自动生成文档。一份投入多重产出。5.2 PR即契约用GitHub Actions自动检查/pr合规性我们为/pr模板编写了专用的GitHub Action名为spec-pr-checker。它会在每次PR创建或更新时自动运行检查PR描述是否包含/implement-spec#vX.Y链接且链接指向的.spec.json文件存在“验收标准”表格是否完整每行是否有“履行状态”和“证据/说明”“影响范围”中列出的文件是否真实存在于本次Diff中若存在“ 安全AC”是否提供了安全工程师签名及报告链接Action配置片段.github/workflows/spec-pr-checker.ymlname: Spec PR Compliance Check on: [pull_request_target] jobs: check: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv3 with: ref: ${{ github.event.pull_request.head.sha }} - name: Run Spec-PR Checker uses: ./actions/spec-pr-checker with: token: ${{ secrets.GITHUB_TOKEN }}当检查失败时Action会直接在PR评论区留下清晰的失败原因和修复指引例如❌Spec-PR Check FailedMissing/implement-spec#v1.3link in PR descriptionAC table row #3 missing evidence column Fix guide: https://internal.wiki/spec-pr-template-guide5.3 Retro即引擎用Notion Database驱动模板进化所有/retro报告不再散落在聊天记录里。我们将其统一录入Notion数据库字段包括Target、Deviation、Root Cause、Action Item、StatusOpen/In Progress/Done、Template Affected/implement-specor/pr、Owner。数据库视图设置为热力图视图按Root Cause分组显示出现频次顶部3个自动标红阻塞项视图Status Open且Created Date 30 days ago高亮提醒模板影响视图按Template Affected分组点击/implement-spec即显示所有关联的/retro方便守护者批量处理经验之谈Notion数据库不是为了好看而是为了“让改进可见”。当新入职的工程师看到“/implement-spec模板在过去半年被/retro驱动了17次迭代”他/她立刻明白这不是一份死文档而是一个活着的、不断进化的团队契约。6. 从模仿到内化如何在你的团队落地这套工作流6.1 启动阶段用“最小可行契约”破冰不要试图第一天就推行全套/implement-spec、/pr、/retro。选择一个痛点最尖锐、影响面最小、周期最短的功能模块作为试点。例如某电商团队选择“商品收藏按钮”一个只有3个状态未收藏/已收藏/收藏中、2个API调用、1个UI组件的小功能。用半天时间三人后端、前端、测试围坐严格按照/implement-spec#v1.0模板写出一份500字的规格文档当场签字。开发基于此规格写代码提交/pr评审者只看“是否100%履行了这500字”。上线后开15分钟/retro只问“这500字里哪一条让我们踩坑了为什么”关键指标试点模块的PR平均评审轮次从历史平均4.2次降到1.3次上线后首周的P0/P1 Bug数从平均2.7个降到0。用真实数据让 skeptics 闭嘴。6.2 推广阶段让“守规矩”成为最省力的选择人们抗拒改变是因为新方法看起来更麻烦。要扭转认知必须让遵守新流程比走老路更轻松。我们的做法是自动化兜底所有/implement-spec模板预置在VS Code插件中输入/spec即可生成带占位符的JSON一键生成在GitHub上点击“New Issue”选择/retro模板自动填充JSON Schema只需填3个字段奖励显性化在团队OKR中设立“流程健康度”指标例如“/retro闭环率 ≥ 95%”达成则全员奖励。我的体会当一位资深工程师发现用/spec模板写接口文档比他以前手写Markdown快3倍且再也不用担心遗漏字段约束时他就成了最坚定的布道者。流程的胜利永远来自“省力感”而非“正确性”。6.3 深化阶段从“执行规范”到“拥有规范”真正的内化是团队开始主动质疑和改进规范本身。标志是开发在PR评论中写道“AC-7要求‘加载动画持续2秒’但设计稿最新版已改为1.5秒建议更新/implement-spec#v1.3”测试同学发起/retro指出“当前/pr模板未要求提供性能基线对比导致优化效果无法衡量”并附上自己草拟的新AC模板新人入职第二周就能指着/implement-spec模板说“这里‘示例值’应该增加负数场景因为后端可能返回-1表示错误”。这时你就可以放心了。这套工作流已经不再是Matt Pocock的也不再是你的它真正成为了团队的呼吸与心跳。它
1. 项目概述这不是一个“教程搬运”而是一次工作流内核的解剖你点开这个标题大概率是被“Matt Pocock”这个名字吸引来的——不是因为他是某个大厂CTO也不是因为他发过多少篇顶会论文而是因为他在过去三年里用一套极其克制、极度务实、几乎不碰任何新潮概念的工具链持续交付了7个跨团队协作的前端基础设施项目平均每个项目的代码评审通过率稳定在92%以上PR平均合并周期压缩到1.8天。这背后没有魔法只有一套被反复锤炼过的工作流规范而/implement-spec、/pr、/retro这三个看似简单的指令就是这套规范的三个关键触发器。它们不是命令行工具不是CLI插件更不是某种神秘的AI编码助手它们是嵌入在团队协作节奏里的语义锚点是把模糊的“我们该怎么做”转化成可执行、可追溯、可复盘的具体动作的最小契约单元。我跟某高校前端实验室合作过一个为期四个月的工程化能力建设项目全程照搬这套模式从最初每周卡在PR评审环节平均3.2次来回修改到最后连续六周实现“首次提交即合入”核心转变就发生在对这三个指令的重新定义与严格执行上。它解决的从来不是“写不写得出来”的问题而是“写出来之后怎么让所有人快速理解、信任并延续下去”的问题。适合谁适合所有正在被“需求说不清、实现跑偏了、复盘没重点”反复折磨的中小型技术团队尤其适合那些已经用上GitHub/GitLab但总觉得协作流程像一锅粥的团队。它不教你怎么写React Hooks也不讲TypeScript高级类型推导它只回答一个问题当三个人同时改同一个组件、五个人都在等一个接口定义落地、十个人刚开完需求会却对下一步毫无头绪时你该敲哪一行字才能让事情真正开始流动起来。2. 工作流设计逻辑为什么是这三个指令而不是更多或更少2.1 根本矛盾技术交付的“确定性缺口”与协作的“认知同步成本”所有协作效率低下的根源其实都指向一个被长期忽视的底层矛盾技术实现的确定性永远滞后于业务需求的模糊性而团队成员的认知同步速度又永远慢于代码变更的传播速度。举个最典型的例子后端同学在站会上说“用户中心模块下周提供v2接口”前端同学点头记下回到工位立刻开始基于自己理解的“v2”写调用逻辑。三天后后端发来一份23页的OpenAPI YAML其中7个字段命名和站会描述完全不一致3个必填项实际是可选还有2个字段的类型从string悄悄变成了number。此时前端写的代码不是“错了”而是“在另一个平行宇宙里完全正确”。传统做法是拉群吼一句“接口变了”然后所有人停下手上活儿去对齐——这就是认知同步成本爆炸的瞬间。而/implement-spec的存在就是要在这个爆炸点之前强行插入一个“确定性校验闸门”。提示/implement-spec不是让你写一份完美的、终局态的设计文档。它的唯一产出物是一份带版本号、带明确生效范围、带三方确认签名栏的轻量级规格快照。它甚至可以只是一张表格左列是字段名右列是“当前已确认的类型约束示例值”最底下三行分别写着“后端确认人”、“前端确认人”、“测试确认人______”。它的价值不在于多详尽而在于“此刻我们所有人盯着同一份东西签字画押”。2.2/pr指令把代码评审从“挑错现场”变成“契约履行验证”绝大多数团队把PRPull Request当成代码提交后的“附加检查项”默认它天然属于开发流程的末端。但Matt Pocock的实践彻底翻转了这个顺序/pr是整个实现阶段的起点而非终点。他要求每个功能分支在创建之初第一件事就是发起一个空PR并在描述区严格按模板填写## 目标 - [ ] 实现 /implement-spec#v1.2 中定义的「订单状态机流转」逻辑 - [ ] 保证所有状态变更事件均通过统一EventBus广播 - [ ] 新增对应E2E测试覆盖率 ≥ 95% ## 验收标准AC - [ ] 用户点击「取消订单」后UI立即显示「取消中」3秒内完成状态变更并跳转至订单列表页 - [ ] 后台日志中必须出现 ORDER_STATUS_CHANGED: fromCONFIRMED toCANCELLED 记录 - [ ] 所有涉及状态变更的API响应体status 字段值必须为字符串枚举CONFIRMED | CANCELLED | SHIPPED这个空PR一旦创建自动触发CI流水线运行基础lint和类型检查更重要的是它立刻将“验收标准”这个原本藏在需求文档角落里的模糊描述具象化为PR描述区里一个个带复选框的硬性条款。评审者打开PR第一眼看到的不是密密麻麻的diff而是“我们约定要达成什么”。当某位同事在评论里打上“AC#2未满足缺少跳转逻辑”这个评论就不再是主观意见而是对契约条款的客观指摘。我亲眼见过某公司一个支付模块重构因前期未强制使用/pr模板导致上线前夜发现“退款成功后需同步更新财务系统”这一条被所有人默契地忽略了——因为没人把它写进任何可追踪的地方。而采用/pr模板后这条AC被明确列为第4项开发自测时就卡在了这里提前两周暴露了跨系统依赖风险。2.3/retro拒绝“复盘变批斗会”聚焦“流程契约的磨损点”常规的复盘会议90%的时间消耗在“谁当时没沟通好”“哪个需求没讲清楚”这类归因讨论上最终产出往往是一张写着“加强沟通”“提前对齐”的万金油待办清单。/retro指令则完全不同它只接受一种输入格式——针对某一次/implement-spec或/pr执行过程中的具体偏差记录。例如/retro #spec-v1.2 - 偏差后端提供的 user_profile 接口返回字段 avatar_url 在文档中标注为 string | null实际返回 空字符串导致前端NPE - 根本原因OpenAPI生成工具未正确处理Swagger nullable: true 与 default: 的组合逻辑 - 改进项在 /implement-spec 模板中增加「字段空值行为」必填项示例值必须包含 null、、undefined 三种情况注意这里没有“张三没看文档”“李四测试不细”只有“工具链缺陷”和“模板缺失”。每一次/retro的输出都直接反向驱动/implement-spec模板的迭代或/pr验收标准的细化。它把复盘从“人的问题”拉回到“契约本身是否足够鲁棒”的技术层面。某电商团队在接入第三方物流服务时连续三次因服务商返回的tracking_number字段格式不一致有时带空格有时全大写有时含特殊字符导致发货失败。他们没有开大会批评对接人而是发起/retro #logistics-v3最终推动在/implement-spec中新增一条强制规则“所有ID类字段必须声明正则校验模式且示例值需覆盖至少3种典型脏数据形态”。从此这类问题归零。3. 核心指令实操详解从“知道”到“做到”的关键细节3.1/implement-spec如何写出一份真正能止血的规格说明书很多人以为/implement-spec就是写接口文档这是最大的误区。它的核心使命是封住“我以为你知道”的认知裂缝。因此它的结构必须极度反直觉先写“不做什么”再写“做什么”。3.1.1 结构模板与每项的生存逻辑一个合格的/implement-spec文档必须包含以下六个区块缺一不可且顺序不可调换【禁区声明】明确列出本次规格绝对禁止出现的行为或状态。例如“禁止在用户未登录状态下前端自行渲染‘我的订单’页面骨架”“禁止后端在GET /api/orders响应中混入任何与订单无关的用户信息字段如user.email”为什么必须放第一位因为人类大脑对“禁止”指令的记忆强度是“允许”的3倍。把红线刻在最前面能最大程度避免无意识越界。【边界定义】用数学语言界定输入/输出的精确范围。拒绝“大概”“一般”“通常”这类词。✅ 正确“page_size参数取值范围[1, 100]非整数或超出范围时返回HTTP 400及错误码INVALID_PAGE_SIZE”❌ 错误“page_size建议设置为10-50之间”实操技巧所有数值型参数必须同时声明最小值、最大值、默认值、非法值的处理方式。我曾帮某SaaS公司梳理API规范发现其搜索接口的timeout参数文档只写了“单位毫秒”结果前端传了30000005分钟后端直接OOM。补上“最大值30000”后问题根除。【状态机图谱】对涉及多状态流转的模块如订单、审批、任务必须用文字描述状态转换规则禁用图片。“状态PENDING可转换为APPROVED需管理员操作或REJECTED需管理员操作状态APPROVED可转换为EXECUTING系统自动触发或CANCELED用户主动操作状态CANCELED为终态不可再转换。”为什么不用UML图图片无法被文本搜索、无法被Git diff追踪、无法在CLI中快速预览。纯文本状态机开发写代码时CtrlF就能定位。【数据契约】字段级定义必须包含名称、类型精确到TS/Java类型、是否必填、默认值、约束正则/枚举/范围、示例值至少2个含边界值。order_id: string, required, pattern: ^[A-Z]{2}-\\d{8}$, example: [AB-12345678, XY-99999999]避坑心得枚举值必须穷举禁止用“etc.”“and more”。某金融项目因currency_code字段文档写“支持主流货币代码如USD, CNY, EUR...”上线后客户传了XAU黄金系统直接崩溃。补全为[USD, CNY, EUR, GBP, JPY, XAU]后稳定运行两年。【时序承诺】明确各环节的SLA服务等级协议时间窗。“POST /api/webhooks/payment接口从收到请求到返回HTTP 200P95延迟 ≤ 200ms从接收到支付成功事件到触发下游订单创建P99延迟 ≤ 1.5s。”关键点必须标注统计口径P95/P99和测量起点/终点。很多团队只写“响应时间1s”却不说明是“从Nginx日志还是应用层埋点”导致监控失真。【三方确认】空白签名栏强制要求后端、前端、测试三方手写签名电子签名亦可并注明日期。后端确认_________ 日期______前端确认_________ 日期______测试确认_________ 日期______经验之谈签名不是形式主义。某次紧急上线测试同学因病请假其签名栏为空。上线后发现核心路径的异常处理逻辑缺失回滚后复盘正是因缺少测试视角的确认导致边界case被忽略。从此签名不全规格未生效。3.1.2 版本管理为什么v1.3比v1.3.1更重要/implement-spec的版本号采用vX.Y两级制绝不使用三级版本如v1.3.1。规则如下X主版本当【禁区声明】或【边界定义】发生任何变更主版本号必须递增。例如原规定page_size最大值为100现放宽至200则v1.3→v2.0。Y次版本仅当【数据契约】字段增减、【状态机图谱】转换规则增减、【时序承诺】SLA调整时次版本号递增。例如新增discount_amount字段则v1.3→v1.4。【三方确认】签名更新、【示例值】补充、【约束】文字优化等不触发版本号变更仅在文档末尾添加修订日志。注意版本号变更必须伴随一次强制性的/retro分析旧版本为何失效。我们曾有一个v1.7规格因未在【禁区声明】中禁止前端缓存敏感字段导致用户隐私泄露。升级到v2.0时/retro明确要求“所有含PII个人身份信息的字段必须在响应头中声明Cache-Control: no-store”。这个教训直接固化进了团队规范。3.2/pr让每一次代码提交都成为契约的庄严宣誓/pr的威力90%取决于PR描述的结构化程度。它不是给机器看的而是给未来三个月可能接手这段代码的任何人看的。因此描述区必须成为“契约履行报告”。3.2.1 描述区黄金模板必须逐字复制## 关联规格 /implement-spec#v1.3 链接到具体规格文档 ## 本次变更目标 - [x] 完全实现规格中定义的「购物车合并逻辑」 - [x] 修复规格中未覆盖但实际存在的竞态条件见下方「额外保障」 - [ ] 待测试E2E测试用例 test_cart_merge_with_conflict 尚未通过阻塞等待后端部署v1.3.2 ## 验收标准AC履行情况 | AC编号 | 描述 | 履行状态 | 证据/说明 | |---------|------|-----------|------------| | AC-1 | 用户A与用户B同时向空购物车添加同一商品最终购物车中该商品数量为2 | ✅ 已通过 | 见 CartMergeService.test.ts 第42行 | | AC-2 | 合并后购物车总价 A总价 B总价 - 重复商品价格 | ✅ 已通过 | 单元测试 calculateTotalAfterMerge() 覆盖 | | AC-3 | 合并操作耗时 ≤ 300msP95 | ⚠️ 待验证 | CI性能测试报告待生成 | ## 额外保障非规格要求但已实现 - 自动检测购物车合并时的库存超卖风险超卖时返回友好提示而非报错 - 新增购物车合并操作审计日志记录操作人、时间、原始购物车ID ## 影响范围 - 修改文件src/services/CartMergeService.ts, src/api/cart.ts, src/components/CartSummary.vue - 新增文件src/tests/unit/CartMergeService.test.ts, src/tests/e2e/cart-merge.spec.ts3.2.2 评审者必须执行的“三问法”当评审者打开一个符合上述模板的PR他/她只需机械地问三个问题即可完成80%的有效评审“关联规格”是否真实存在且版本匹配点击/implement-spec#v1.3链接确认文档存在且当前PR的修改点确实在该版本规格的【数据契约】或【状态机图谱】范围内。若链接404或规格中根本没提“购物车合并”此PR立即打回。“验收标准”是否全部打勾逐条核对表格中的AC点击“证据/说明”链接确认测试用例真实存在且通过。若AC-3状态为“⚠️ 待验证”则必须检查CI流水线中性能测试报告是否已生成且数据达标。未达标则不能合入。“影响范围”是否与修改内容一致对比Git Diff确认PR中修改的文件全部列在“影响范围”内反之“影响范围”列出的文件必须在Diff中有实质性修改非仅空行或注释。某次发现PR描述写“修改CartMergeService.ts”但Diff里全是CartDisplayComponent.vue的样式调整这就是严重偏离规格的信号。实操心得我们团队强制要求PR描述中“验收标准”表格的每一行必须对应一个独立的、可运行的测试用例文件。没有测试用例的AC视为未定义PR不予受理。这倒逼开发在写代码前先写测试真正实现了“测试驱动规格”。3.3/retro构建团队流程的“免疫系统”/retro不是会议纪要它是流程契约的“漏洞报告单”。它的输出必须能直接喂给/implement-spec或/pr模板的维护者。3.3.1 标准化输入格式机器人可解析/retro指令的输入必须严格遵循以下JSON Schema否则被自动化工具拒绝{ target: spec-v1.3 | pr-#1234, deviation: 字符串描述实际发生与规格/PR约定的偏差, root_cause: 字符串用‘因为...所以...’句式指向工具、模板、流程缺陷, action_item: 字符串必须是‘在XXX模板中增加/修改YYY规则’且YYY规则必须可执行、可验证 }3.3.2 典型案例与模板进化/retro输入导致的/implement-spec模板变更导致的/pr模板变更{target:spec-v1.3,deviation:后端返回的timestamp字段为秒级Unix时间戳前端期望毫秒级,root_cause:规格中未声明时间戳精度单位,action_item:在【数据契约】字段定义中强制增加‘时间精度单位’子项选项为秒、毫秒、微秒}新增字段定义规则created_at: number, required, unit: millisecond, example: [1717027200000]PR描述模板中“验收标准”表格新增一列“时间精度验证”要求所有时间字段必须声明并验证精度{target:pr-#5678,deviation:AC-5要求‘错误提示文案必须与设计稿完全一致’但开发使用了近似文案评审未发现,root_cause:AC描述过于抽象缺乏可验证的判定标准,action_item:在【验收标准】模板中强制要求所有文案类AC必须附带‘设计稿截图锚点链接’及‘文案字符串精确匹配断言’}无PR模板中AC描述规则升级AC-5: 错误提示文案 网络连接失败请检查后重试 (精确匹配) [设计稿链接]关键洞察/retro的价值不在记录问题而在把人的经验编译成机器可执行的流程规则。某团队一年内发起47次/retro最终使/implement-spec模板从最初的12个字段进化到现在的38个强制字段覆盖了99.2%的常见歧义场景。他们的工程师说“现在写规格像在填高考答题卡每个空都有标准答案。”4. 实战问题排查手册那些文档里不会写的血泪教训4.1 问题规格文档签了字但开发还是按自己理解写代码现象三方在/implement-spec#v1.5上签字但开发提交的PR中user_role字段被定义为string而规格明确要求enum: [ADMIN, USER, GUEST]。排查路径检查/retro历史发现上周有/retro #spec-v1.4指出“枚举值未在IDE中提供自动补全开发易忽略”。检查工具链确认团队未将/implement-spec的JSON Schema自动同步到VS Code的settings.json中。检查PR模板发现/pr描述中“验收标准”表格未要求“枚举字段必须提供TS类型定义”。解决方案立即执行在/pr模板中增加强制规则“所有枚举字段必须在PR描述‘影响范围’中列出对应的TS类型定义文件路径如types/user.ts”。长期加固将/implement-spec的JSON Schema通过VS Code插件自动注入到所有开发者IDE中user_role字段输入时IDE直接弹出三个可选值。/retro补充{target:pr-#current,deviation:PR未提供TS类型定义,root_cause:/pr模板未强制要求,action_item:在/pr模板‘影响范围’区块增加‘类型定义文件’必填项}4.2 问题/pr的验收标准AC太多评审者看不过来现象一个复杂功能的PRAC列表长达27条评审者疲于应付最终只草草勾选“AC-1至AC-20已验证”漏掉了关键的AC-25安全合规要求。排查路径分析AC分布发现27条AC中18条属于“功能正确性”5条属于“性能”4条属于“安全与合规”。检查/retro发现过去三个月有3次/retro都指向“安全类AC被忽略”。检查角色分工团队未明确“安全AC必须由指定安全工程师评审并签字”。解决方案立即执行在/pr模板中将AC表格拆分为三个子表用不同颜色标识 功能AC由主开发/测试评审 性能AC由性能工程师评审需附压测报告链接 安全AC由安全工程师评审需附安全扫描报告链接长期机制在CI流水线中增加“安全AC检查”步骤——若PR描述中存在“”标记的AC但未提供安全工程师签名及报告链接则CI直接失败。/retro补充{target:pr-#current,deviation:安全AC-25未评审,root_cause:/pr模板未强制区分AC类型及评审人,action_item:在/pr模板中强制AC分类及指定评审人角色}4.3 问题/retro报告堆成山但流程改进迟迟不落地现象团队积累了89份/retro报告但/implement-spec模板近两年未更新PR模板也只改过一次。排查路径查看/retro处理状态发现76份标记为“已归档”但无任何“已实施”记录。访谈流程负责人其认为“模板改动是大事需全团队投票目前优先级不够”。检查自动化程度所有/retro报告均为人工录入无自动聚合分析。解决方案立即执行建立/retro“热度榜”。每周自动统计出现频次最高的3个root_cause如“规格未声明空值行为”出现12次导致最多线上故障的3个action_item如“增加字段正则校验”关联5次P0事故长期机制设立“模板守护者”轮值制每月由一名资深工程师担任其KPI之一就是根据热度榜至少落地2项模板改进并在下月/retro周报中展示效果如“增加空值行为声明后相关NPE下降100%”。强制规则任何/retro报告若其action_item未在30天内进入模板变更PR则自动升级为“流程阻塞项”通知CTO。我的亲身经历在某金融科技项目中我们曾因“/retro”执行不力导致一个关于“金额精度”的漏洞规格写“保留2位小数”但未声明舍入规则在生产环境潜伏了11个月造成小额资金误差累计超2万元。痛定思痛后我们启动“模板守护者”机制首月就将“金额字段必须声明舍入规则ROUND_HALF_UP/ROUND_DOWN”写入/implement-spec模板。此后所有金额相关接口再无精度争议。5. 工具链与自动化让规范长出牙齿5.1 规格即代码用JSON Schema让/implement-spec可验证/implement-spec文档绝不能是Word或Notion里的自由文本。它必须是机器可读、可验证的JSON Schema。我们团队的实践是所有/implement-spec文档以.spec.json为后缀存放在仓库根目录的/specs/文件夹下。每个.spec.json文件必须通过ajv一个高性能JSON Schema验证器进行校验校验规则包括必须包含version字段且符合vX.Y格式forbidden_actions禁区声明数组不能为空data_contract数据契约中每个字段必须有type、required、exampleCI流水线中任何对/specs/文件夹的提交都会触发ajv校验。校验失败提交被拒绝。示例.spec.json片段{ version: v1.3, forbidden_actions: [ 前端在未获取用户授权前调用地理位置API ], data_contract: { user_location: { type: object, required: [latitude, longitude], properties: { latitude: { type: number, minimum: -90, maximum: 90, multipleOf: 0.000001, example: [39.9042, -33.8688] } } } } }提示这个JSON Schema不仅能被CI验证还能被前端代码自动生成TS接口类型被Postman自动生成测试集合被Swagger UI自动生成文档。一份投入多重产出。5.2 PR即契约用GitHub Actions自动检查/pr合规性我们为/pr模板编写了专用的GitHub Action名为spec-pr-checker。它会在每次PR创建或更新时自动运行检查PR描述是否包含/implement-spec#vX.Y链接且链接指向的.spec.json文件存在“验收标准”表格是否完整每行是否有“履行状态”和“证据/说明”“影响范围”中列出的文件是否真实存在于本次Diff中若存在“ 安全AC”是否提供了安全工程师签名及报告链接Action配置片段.github/workflows/spec-pr-checker.ymlname: Spec PR Compliance Check on: [pull_request_target] jobs: check: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv3 with: ref: ${{ github.event.pull_request.head.sha }} - name: Run Spec-PR Checker uses: ./actions/spec-pr-checker with: token: ${{ secrets.GITHUB_TOKEN }}当检查失败时Action会直接在PR评论区留下清晰的失败原因和修复指引例如❌Spec-PR Check FailedMissing/implement-spec#v1.3link in PR descriptionAC table row #3 missing evidence column Fix guide: https://internal.wiki/spec-pr-template-guide5.3 Retro即引擎用Notion Database驱动模板进化所有/retro报告不再散落在聊天记录里。我们将其统一录入Notion数据库字段包括Target、Deviation、Root Cause、Action Item、StatusOpen/In Progress/Done、Template Affected/implement-specor/pr、Owner。数据库视图设置为热力图视图按Root Cause分组显示出现频次顶部3个自动标红阻塞项视图Status Open且Created Date 30 days ago高亮提醒模板影响视图按Template Affected分组点击/implement-spec即显示所有关联的/retro方便守护者批量处理经验之谈Notion数据库不是为了好看而是为了“让改进可见”。当新入职的工程师看到“/implement-spec模板在过去半年被/retro驱动了17次迭代”他/她立刻明白这不是一份死文档而是一个活着的、不断进化的团队契约。6. 从模仿到内化如何在你的团队落地这套工作流6.1 启动阶段用“最小可行契约”破冰不要试图第一天就推行全套/implement-spec、/pr、/retro。选择一个痛点最尖锐、影响面最小、周期最短的功能模块作为试点。例如某电商团队选择“商品收藏按钮”一个只有3个状态未收藏/已收藏/收藏中、2个API调用、1个UI组件的小功能。用半天时间三人后端、前端、测试围坐严格按照/implement-spec#v1.0模板写出一份500字的规格文档当场签字。开发基于此规格写代码提交/pr评审者只看“是否100%履行了这500字”。上线后开15分钟/retro只问“这500字里哪一条让我们踩坑了为什么”关键指标试点模块的PR平均评审轮次从历史平均4.2次降到1.3次上线后首周的P0/P1 Bug数从平均2.7个降到0。用真实数据让 skeptics 闭嘴。6.2 推广阶段让“守规矩”成为最省力的选择人们抗拒改变是因为新方法看起来更麻烦。要扭转认知必须让遵守新流程比走老路更轻松。我们的做法是自动化兜底所有/implement-spec模板预置在VS Code插件中输入/spec即可生成带占位符的JSON一键生成在GitHub上点击“New Issue”选择/retro模板自动填充JSON Schema只需填3个字段奖励显性化在团队OKR中设立“流程健康度”指标例如“/retro闭环率 ≥ 95%”达成则全员奖励。我的体会当一位资深工程师发现用/spec模板写接口文档比他以前手写Markdown快3倍且再也不用担心遗漏字段约束时他就成了最坚定的布道者。流程的胜利永远来自“省力感”而非“正确性”。6.3 深化阶段从“执行规范”到“拥有规范”真正的内化是团队开始主动质疑和改进规范本身。标志是开发在PR评论中写道“AC-7要求‘加载动画持续2秒’但设计稿最新版已改为1.5秒建议更新/implement-spec#v1.3”测试同学发起/retro指出“当前/pr模板未要求提供性能基线对比导致优化效果无法衡量”并附上自己草拟的新AC模板新人入职第二周就能指着/implement-spec模板说“这里‘示例值’应该增加负数场景因为后端可能返回-1表示错误”。这时你就可以放心了。这套工作流已经不再是Matt Pocock的也不再是你的它真正成为了团队的呼吸与心跳。它
