首页 文章 精选 留言 我的

精选列表

搜索[Skills],共2400篇文章
优秀的个人博客,低调大师

《WorkBuddy Skills 实战》第18招 串成开发闭环

## 01、痛点 你有没有遇到过这样的场景:代码写完了,测试也过了,可一上生产就冒烟;评审意见来回拉扯,上下文却丢了一半;需求文档和代码之间像是两个平行世界。我是老李,过去两年一直在带团队做研发效能,最头疼的不是某个工具不好用,而是每个环节都在“自动”,整条链路却没有任何“反馈”。 场景化问题:比如我们团队之前接手一个老项目,每次改功能都要先翻最近一个月的提交记录,再找人问当初为什么这么设计。好不容易理清一点,需求又变了。开发时靠记忆写代码,写完跑一遍本地测试就提交,评审靠人眼扫,合入后流水线挂了再回头修。上线后,浏览器端偶发白屏,只能等用户截图。这个链路不是没有工具,而是工具之间没有形成闭环:上一个环节的结论没有变成下一个环节的输入,下一个环节的失败也不会反过来校正上一个环节的判断。 为什么现在要讲:现在很多团队已经把单点自动化做到不错——代码生成、静态检查、自动测试、自动部署都有现成方案。但单点越强,越容易掩盖链路断裂的问题。一个能力模块能写代码,不等于它知道需求为什么变;一个流水线能跑测试,不等于它能告诉你生产上到底有没有问题。如果不把整条链串起来,我们只是在局部提效,全局仍然靠人肉搬运上下文。所以我今天想讲的不是某个新工具,而是一套越来越像现代软件交付流程的“反馈环”。 ## 02、是什么 这里说的反馈环,不是把一堆自动化脚本堆在一起。它的核心是:让研发过程中每一个关键节点都能产生可被下一个节点消费的产物,并且把下游的异常、变更、验证结果反向传导到上游,形成闭环。 我们可以把它抽象成一条十步链路:先做背景研究,再做需求发现,然后制定计划,接着实现,测试,诊断,评审,过流水线,浏览器验收,最后看生产。每一步都不是孤立动作,而是像接力一样,把上下文和校验条件传递下去。 举个例子:背景研究阶段产出的是“最近发生了什么、哪些模块被频繁改动、哪些历史决策容易踩坑”;需求发现阶段产出的是“经过追问后确定下来的验收条件”;计划阶段产出的是“按什么顺序改、改哪些文件、哪些地方必须加测试”。到了实现和测试,产物变成代码和测试报告;诊断阶段则把失败用例、报错堆栈、可疑提交找出来;评审阶段把人工意见整理成可执行列表;流水线阶段把构建、单测、集成测试结果汇总;浏览器验收阶段把真实页面交互结果录下来;生产阶段把线上指标和错误追踪接回来。 关键点是:每一个环节的输出不是给人看的“文档”,而是能被下一环节直接使用的结构化输入。比如需求澄清阶段给出的验收条件,可以直接变成测试阶段的断言;生产阶段看到的线上报错,可以直接触发诊断阶段去定位最近哪次变更引入的。这样,链路就不是一条直线,而是一个有反馈的环。 ## 03、为什么 为什么现在要做这件事?三个原因。 第一,现代软件交付的复杂度已经超过单点工具能覆盖的范围。一个需求从提出到上线,要经过背景调查、需求确认、方案设计、编码、测试、评审、构建、部署、验收、观测。任意一环的信息丢失,都会导致返工。过去我们可以靠有经验的老人把上下文装在脑子里,但现在团队流动快、系统拆得细,人脑已经装不下全貌。 第二,局部自动化反而可能放大风险。比如代码生成快了,但需求没澄清清楚,生成的代码越“漂亮”,埋下的错误越深;自动测试跑得欢,但用例没有覆盖真实浏览器行为,上线后照样翻车;流水线自动合入,但评审被跳过,质量问题后移。只有把整条链串起来,才能让自动化的速度被正确的反馈约束。 第三,反馈速度决定团队效能。软件开发本质上是一个持续做决策、持续验证的过程。验证越快越准,团队就能越快纠偏。如果评审意见要等一天,如果生产报错要等用户反馈,如果需求变更要等开会,那么这个环就是慢的。把环串起来,不是为了全自动,而是为了让每一个决策都有最短路径的验证。 ## 04、架构 我把这条链称为“WorkBuddy 反馈环”,它由十个节点组成,每个节点有明确的输入、动作、输出和门禁。 1. 背景研究:输入是仓库和最近一段时间的提交记录,动作是汇总变更、识别热点模块、找出可能影响本次需求的历史上下文,输出一份“背景简报”。 2. 需求发现:输入是背景简报和原始需求,动作是连续追问,把模糊需求变成可验收的规格,输出“澄清后的需求条目”和“验收条件”。 3. 计划制定:输入是需求条目和代码库结构,动作是拆解任务、确定修改范围、标注测试策略,输出“实施计划”。 4. 实现:输入是实施计划和验收条件,动作是写代码、补测试,输出“变更集”和“自测结果”。 5. 测试:输入是变更集和测试策略,动作是运行单元测试、集成测试,输出“测试报告”,失败时附上可定位的堆栈。 6. 诊断:输入是失败用例和变更集,动作是分析报错、定位可疑提交、给出修复建议,输出“诊断结论”。 7. 评审:输入是变更集和诊断结论,动作是人工评审、逐条提意见,输出“评审意见列表”。 8. 流水线:输入是变更集和评审结论,动作是跑完整构建、测试、静态检查,输出“流水线状态”,失败时阻止合入。 9. 浏览器验收:输入是部署到预发环境的变更,动作是模拟真实用户操作,输出“页面验收结果”,包括截图、交互录屏、控制台错误。 10. 生产观测:输入是线上版本号和监控数据,动作是观察错误率、性能、用户路径,输出“生产健康报告”,异常时反向触发诊断。 这些节点不是单向串行。真正的反馈环在于:生产观测发现的异常,可以回到诊断节点去定位变更;浏览器验收发现的页面问题,可以回到实现或计划节点;评审意见可以回到需求发现节点重新澄清。门禁分布在评审、流水线、浏览器验收、生产观测四个地方,确保关键质量关卡有人工确认或强自动化拦截。 ## 05、实战 为了验证这套链路,我们拿了一个真实功能走一遍:给项目增加“邀请成员加入团队”的功能。这个功能看着简单,但涉及权限、邮件通知、链接有效期、重复邀请、已有成员校验,很容易漏。 第一步,背景研究。我先让“历史盘点”组件拉取最近 30 天的提交,它返回了一份简报:成员模块最近改过三次,权限校验逻辑分散在三个 service 里,上周刚修过一个越权漏洞,相关测试覆盖不足。这个信息很重要,说明这个功能不能只写一个邀请接口,还要兼顾权限边界和回归测试。 第二步,需求发现。我让“需求追问”组件连续问了我几个问题:邀请链接有效期多长?被邀请人是否必须已注册?重复邀请是覆盖还是报错?邀请人有没有数量限制?是否需要邮件通知?我逐一回答后,它产出了七条验收条件,比如“链接 24 小时过期”“重复邀请返回可读错误”“邀请人单日上限 20 次”。这些条件后面直接变成了测试断言。 第三步,计划制定。我让“计划制定”组件根据需求和代码结构生成实施计划。它建议拆成四步:先抽出权限校验公共方法,再新增邀请记录表,然后实现创建和接受邀请两个接口,最后补邮件通知。计划里明确标出三个必须加测试的文件和两个需要回归的旧用例。 第四步,实现。我让“测试驱动开发”组件按计划写代码。它先写了失败测试,再实现功能。中间遇到一个边界:被邀请人已经是成员时,接口应该返回 409 还是 200?我让它按验收条件第三条实现为 409 并附带错误码。实现完成后,自测结果里有两个旧测试失败,因为旧测试直接操作了权限表,没有走新的公共方法。 第五步,诊断。我把失败用例和变更集交给“缺陷诊断”组件。它定位到旧测试里硬编码了旧的表结构,建议更新测试夹具,并指出新的公共方法需要兼容旧调用。修复后测试通过。 第六步,评审。我把变更集推上去,评审人提了三条意见:邮件模板里的链接没有 URL 编码;邀请记录缺少索引;权限校验方法命名不够清晰。我把这些意见交给“评审意见处理”组件,它逐条修改代码并回复评审人。其中有一条意见它判断不合理,回复了理由,我确认后放行。 第七步,流水线。合入前跑完整流水线,结果集成测试阶段挂了,原因是邀请记录表的迁移脚本在测试库上执行失败。“流水线修复”组件读取日志后,发现是迁移脚本里写死了开发库的名称,改成环境变量后重新触发,流水线通过。 第八步,浏览器验收。预发环境部署后,我用“浏览器验收”组件模拟真实用户操作:注册一个新用户,打开邀请链接,填写信息,提交,然后检查页面提示。它录下了一段 30 秒的交互视频,并发现控制台有一条 React 警告,虽然不影响功能,但建议修复。我们顺手清掉了这条警告。 第九步,生产观测。功能上线后,我在生产环境观察了三天。第一天错误率没有上升,但邮件发送成功率只有 92%。进一步查发现是部分企业邮箱把邀请邮件扔进了垃圾箱。我们调整了邮件标题和发件人策略,成功率回到 98% 以上。整个过程里,生产观测的数据反向触发了一次诊断,帮我们定位到邮件服务配置问题。 走完这一趟,最大的感受不是某个环节多聪明,而是每一步的产出都能被下一步直接用,且下游的异常能快速回到上游。以前这种功能从需求到稳定上线至少要一周,这次两天内走完,而且关键门禁一个没少。 ## 06、洞见 很多人第一次接触这套链路时,会先问“你用了哪几个能力模块”。但真正值得传播的不是那十几个模块的名字,而是这个越来越像现代软件交付流程的反馈环本身。 传统的软件交付流程(SDLC)强调阶段划分:需求、设计、编码、测试、发布。每个阶段之间有审批和文档传递。而现代研发越来越追求“小步快跑”,但快的前提是反馈环要短。这条链就是把传统 SDLC 的严肃性和现代迭代的速度结合了起来:它保留了评审、流水线、验收、生产观测这些关键门禁,同时用自动化把环节之间的信息搬运成本降下来。 但是,有一个原则不能妥协:不能为了追求全自动而取消关键人工门禁。评审、安全验收、发布审批这些环节,必须有人做最终判断。自动化可以做准备、提醒、汇总、建议,但不能替代人对业务风险和合规风险的判断。我们团队内部定了一条规矩:需求发现阶段必须有人确认验收条件,评审阶段必须有至少一个非作者通过,生产发布必须有人点击确认。这样,环可以快,但不会失控。 另一个洞见是:反馈环的价值取决于“反向传导”的质量。如果生产观测只出一个报警,而不能关联到某次变更、某个能力节点、某条需求,那它只是噪声。要让异常能溯源,就必须在链路上保留足够的元数据:每次变更关联需求、计划、测试、评审意见、流水线编号、上线版本。这样,生产上的一个错误,就能在几分钟内定位到是哪个环节的哪个决定出了问题。 ## 07、行动 如果你想把这条链作为团队标准工作流候选,我建议分四步走。 第一步,评估现状。把团队现有的研发流程画出来,标出每个环节的工具、产物、门禁、耗时。找出哪些环节的信息在靠人肉搬运,哪些反馈是断的。不要一上来就追求十步全通,先找最痛的一段。 第二步,选择试点。找一个边界清晰、风险可控的功能,用这条链完整走一遍。关键是让团队看到“背景研究如何影响需求澄清”“生产观测如何反向触发诊断”。试点过程要有记录,特别是每个环节的输入输出格式和时间成本。 第三步,固化门禁。无论自动化做到什么程度,人工门禁必须明确写进团队规约。比如:需求验收条件未确认不能进入计划;评审未通过不能进入流水线;生产发布前必须有人确认。门禁不是效率的敌人,而是反馈环的护栏。 第四步,度量与推广。试点结束后,用几项指标来验证效果:从需求提出到稳定上线的周期、评审往返次数、生产缺陷率、平均修复时间。如果数据有改善,再把这条链推广到更多团队。推广时重点讲清楚“反馈环”的收益,而不是某个具体模块的名字。 ## 08、小结 单点自动化的时代正在过去,真正决定研发效能的,是你能不能把需求、计划、实现、测试、评审、流水线、验收、生产串成一条有反馈的环。这条环不是要取代人,而是要让人在关键节点上做更高质量的判断。背景研究让你少踩坑,需求追问让你少返工,计划制定让你少跑偏,测试诊断让你少加班,评审流水线让你少背锅,浏览器验收让你少被用户骂,生产观测让你少熬夜。最后,请记住:环可以自动,门禁必须有人。 ## 09、链接与概念说明 - SDLC:软件开发生命周期,指从需求分析到设计、实现、测试、部署和维护的完整过程。本文中的十步链路可以理解为对现代 SDLC 的工程化拆解。 - 反馈环:系统输出的一部分被返回到输入端,用以校正后续行为。本文指下游验证结果反向影响上游决策。 - CI:持续集成,指频繁合并代码并自动构建测试,以尽早发现集成问题。 - 浏览器验收:在真实浏览器环境中模拟用户操作,验证页面功能和交互是否符合预期。 - 生产观测:对线上系统的运行指标、错误日志、用户行为进行持续监控和分析。 - 门禁:质量关卡,未满足条件时阻止流程继续,是防止自动化失控的关键机制。

优秀的个人博客,低调大师

《WorkBuddy Skills 实战》第1招 Skill不是提示词

## 01、痛点 你有没有算过,同一段交代要重复多少遍?我是老李,一个在研发一线待了十来年的工程师。最近大半年,我最常说的一句话是:“先读文档、先做计划、不要直接改代码、改完跑测试。”不是我喜欢唠叨,而是每次让 WorkBuddy 改代码,只要漏掉其中一句,它就可能直接打开核心模块动手。有一次我赶时间,只说了“把这个接口改成异步”,结果它没看现有设计文档,绕过了已经约定好的错误处理链路,测试跑挂了,我还得回头查半天。 这个问题不只是 WorkBuddy,换成人也一样。新同事入职,你要口头交代一遍;换个人协作,你又交代一遍;三个月后你自己回来,也得重新回忆。真正麻烦的不是说话花时间,而是每次交代的内容都不稳定。今天记得“先读文档”,明天可能只记得“不要直接改代码”。一次遗漏,就可能导致线上事故。 这就是典型的隐性经验没有固化。我们脑子里知道一套正确流程,但它只存在于某个会话、某段聊天记录或者某个人的习惯里。它没有被工程化,所以每次执行都有波动。 ## 02、是什么 要解决这个问题,先得把概念掰清楚。很多人以为,把一段常用的要求保存下来,下次粘贴,就是沉淀。这其实只解决了一小部分问题。真正有用的东西,不是一段保存下来的文字,而是一套可复用的指令、脚本、参考资料和资源组合。为了方便,我把它叫“方法包”。 方法包和一次性指令有本质区别。一次性指令解决一次任务。比如“帮我看看这个接口为什么超时”,这句话只对当前场景有效。方法包解决重复任务,它描述一类问题在什么条件下触发、按什么步骤执行、调用哪些脚本、参考哪些资料、产出什么结果。它更像操作手册,而不是口头交代。 举个具体例子。“先读文档、先做计划、不要直接改代码、改完跑测试”这几句话,如果只是存在聊天记录里,每次复制,它仍然需要人去判断是否漏项。但如果把它变成一个方法包,它就有明确结构:什么情况下触发;先做什么;后做什么;哪些目录是资料;哪些脚本是验证。这样无论谁来执行,或者无论哪次会话,行为都一致。 方法包至少包含四类要素: - 触发条件:什么场景下启用,例如“修改代码”“调整配置”“修复缺陷”。 - 执行规则:步骤、边界、禁止项,例如“先读文档”“只改最小必要文件”。 - 脚本资源:可以执行或调用的校验脚本,例如测试、静态检查、格式检查。 - 参考资料:设计文档、编码规范、目录说明、样例。 这四类要素组合起来,才会让重复任务从“靠记忆”变成“靠系统”。 ## 03、为什么 为什么现在值得把这件事认真做?有三个原因。 第一,重复任务是最值得消除的波动来源。一次偶然任务可以口头交代,但每周做三次以上的流程,哪怕每次只花一分钟提醒,错误概率也会随着次数累积。方法包解决的不是“省一分钟”,而是“降低每次执行结果的不确定性”。 第二,隐性经验只有固化下来才算资产。一个工程师脑子里知道发版前要检查什么,这叫个人经验;一个团队所有人都能调同一份检查清单,这叫组织能力。方法包就是个人经验向组织能力转化的载体。它可以版本化、可以评审、可以共享。 第三,模型或自动化工具的真正上限,不只取决于它本身多聪明,而取决于它能调用多少经过验证的工作方法。一个模型可能知道很多通用知识,但它不知道你们团队的特殊约定,不知道你们哪份文档是最新版本,也不知道你们发版前必须跑哪个脚本。这些只有通过方法包告诉它。换句话说,方法包是能力的放大器。 当然,这不是说方法包越多越好。后面我们会聊到数量带来的成本。这里先建立基本判断:高频、重复、有明确规则的任务,最值得先做。 ## 04、架构 一个方法包在工程上长什么样?我建议不要只写一个长文本,而是用一个目录承载。结构大致如下: ``` methods/ safe-change/ METHOD.md scripts/ check.sh references/ coding-style.md release-checklist.md examples/ before-after.md ``` 这里的 `METHOD.md` 是入口文件,包含触发描述、执行规则和资源声明。`scripts/` 放可执行脚本,让验证步骤不依赖记忆。`references/` 放团队约定、设计文档、规范。`examples/` 放前后对比或典型样例,帮助降低理解成本。 为什么要做成目录而不是单文件?因为单文件只能承载文本,不能真正调用脚本,也不方便管理资料版本。目录结构让方法包变成一个小型工程,规则、资源和验证可以各自演进。 在组织上,我通常按域划分方法包,比如: - 变更类:代码修改、配置调整、依赖升级。 - 发布类:发版前检查、回滚步骤、发布后验证。 - 故障类:接口超时、队列堆积、服务崩溃。 - 质量类:代码评审、测试补充、文档更新。 每个方法包只解决一个具体问题。触发词要尽量互斥,减少同时命中多个方法包的情况。例如“修改代码”和“性能优化”可能会有重叠,那就需要把“性能优化”拆成更细的场景,或者明确优先级。 ## 05、实战 先看一个最小示例。假设我们有一个高频场景:每次让 WorkBuddy 改代码,都要遵守同一套安全流程。我们把它写成 `METHOD.md`,内容如下: ``` name: safe-change description: 修改代码或配置时触发,先读文档、再计划、小步修改、测试验证。 triggers: - 修改代码 - 调整配置 - 修复缺陷 steps: - 读取 docs/ 下相关设计文档 - 列出修改计划和影响面 - 等待确认后再动手 - 只改最小必要文件 - 执行 scripts/check.sh resources: - references/coding-style.md - scripts/check.sh ``` 这个文件很短,但关键要素都在。`triggers` 告诉执行者什么时候用它;`steps` 规定了动作顺序和边界;`resources` 指向具体资料和脚本。它没有写“不要直接改代码”,而是用“等待确认后再动手”和“只改最小必要文件”把要求转成了规则。 接着补一个脚本。`scripts/check.sh` 可以简单写成: ``` #!/usr/bin/env bash set -e echo 'running unit tests' pytest -q echo 'running style check' ruff check . echo 'all checks passed' ``` 这样“改完跑测试”就不再是一句空话,而是一个可以稳定执行的命令。 再举一个稍微完整的例子:发版前检查。很多团队每周都做,但每次都靠人回忆。方法包可以这么写: ``` name: pre-release-check description: 发版前触发,检查变更记录、测试结果、回滚方案和监控配置。 triggers: - 发版 - 上线 - 打 tag steps: - 读取 CHANGELOG.md 确认变更范围 - 确认所有测试已在目标分支通过 - 确认回滚步骤和责任人 - 检查监控告警是否覆盖新增接口 - 输出发布检查结论 resources: - references/release-policy.md - scripts/release-check.sh ``` 这样每周发版时,不再需要反复解释“先看啥、再确认啥、最后输出什么”。执行者会自动按规则走。 从这两个例子可以看出,一个方法包不需要很复杂。它最小可行,也比没有强很多。先写 5 步以内,配一个脚本,跑两周,再慢慢补充。 ## 06、洞见 前面说方法包有用,但这里必须泼一盆冷水:方法包不是越多越好。 第一个问题是触发冲突。如果团队积累了很多方法包,一个请求可能同时命中“代码变更”“安全加固”“性能优化”。每个方法包都有不同步骤,可能一个要求“先读设计文档再动手”,另一个要求“先跑基准测试”。到底听谁的?如果优先级不清晰,执行者会混乱。 第二个问题是上下文负担。方法包带资料,资料会被读入当前上下文。但上下文空间有限,如果塞进太多方法包,真正重要的规则可能被稀释。你以为给了完整信息,实际上重点被淹没在大量文档里。 第三个问题是维护成本。流程会变。发布策略改了,方法包要更新;测试工具换了,脚本要重写;文档迁移了,资源路径要调整。如果方法包数量失控,维护成本会超过收益。 所以我的建议是:把方法包当作代码来管理。数量克制,按频率和风险分层。高频且高风险的先做,低频且低风险的可以暂时只写一段文字。每个方法包要有明确边界,触发词尽量互斥。定期清理已经不再使用的包,避免“收藏即学会”的幻觉。 这里有一个更本质的洞见:模型的能力上限,不只取决于模型本身,而取决于它能调用多少经过验证的工作方法。同样一个模型,没有方法包时,它只能靠通用知识猜测;有了方法包,它就能稳定执行你们团队的验证流程。差距不在参数,而在方法库的质量。 ## 07、行动 如果你只有五分钟,只做一件事:从自己每周重复三次以上的流程开始,写一个最小方法包。 具体可以分五步: 1. 选一个高频流程,比如发版前检查、代码修改、周报整理。 2. 记录这个流程的真实步骤,不是想象中应该怎么做,而是你实际怎么做。 3. 把步骤压缩到 5 步以内,写清触发条件和禁止项。 4. 至少补一个可执行脚本,用来验证结果。 5. 试用两周,再决定是补充资料还是拆分成多个包。 不要一上来追求大而全。先做一个能跑通的最小闭环,比写十个半成品更有价值。团队内部可以建一个公共目录,把方法包和代码放在同一个版本库里管理。评审时问三个问题:触发条件是否清晰?步骤是否可执行?有没有验证脚本? ## 08、小结 回到开头那个场景。以前我每次都要提醒 WorkBuddy“先读文档、先做计划、不要直接改代码、改完跑测试”。现在我把这套流程沉淀成方法包,触发条件、执行规则、脚本和资料都固定下来。少说的话,不再导致事故。 核心就几句话:一次性指令解决一次任务,方法包解决重复任务。真正值钱的不是模型多聪明,而是你积累了多少经过验证的工作方法。先从小处开始,把每周重复三次以上的流程变成可执行资产,再逐步迭代。 ## 09、链接与概念说明 - 方法包:本文统一用“方法包”指代一套可复用的指令、脚本、参考资料和资源组合。 - 触发条件:描述什么场景下启用一个方法包。 - 执行规则:明确规定步骤顺序、边界和禁止项。 - 资源目录:方法包内的脚本、文档、样例等资源。 - 上下文空间:一次执行能携带的资料量有限,需要控制方法包数量。 - 触发冲突:多个方法包同时命中同一场景,需要明确优先级或拆细边界。 进一步学习可以关注这些方向:运行手册、操作手册、可复用组件、版本化管理、自动化测试脚本。工程上很多思路是相通的,关键是把隐性经验变成显性资产,而不是停留在“我保存了一段话”。

优秀的个人博客,低调大师

《WorkBuddy Skills 实战》第2招 先学会造Skill

## 01、痛点 我是老李。最近一位做技术运营的朋友跟我抱怨,他们团队每周要写一篇实战文章,每次从查资料到成稿至少两天。更难受的是,换个人写质量就差很多,关键步骤经常遗漏,字符画也画得五花八门。另一个做数据库运维的同事,每次线上排障都要重新翻笔记,操作顺序靠记忆,一紧张就跳步。 这些问题的共同点不是“人不行”,而是工作方法没有被固化。重复工作每一次都在临时拼装流程,经验只存在于个别人脑子里。今天环境变化越来越快,文档、工具、组件版本更新频繁,如果方法不能沉淀成稳定流程,团队就会不断为同样的事情交学费。 为什么现在要讲?因为现在很多团队已经具备把方法封装起来、按条件自动调用的条件。我们缺的不是工具,而是把“怎么做”说清楚的能力。所以这篇文章想和你聊聊,如何把一个重复工作提炼成稳定可复用的能力包。 ## 02、是什么 这里说的“能力包”,不是一篇操作手册,也不是一个功能列表,而是把一段经过验证的工作方法封装成一个可以被按需调用的流程单元。它可以是一段结构化描述,也可以配置在调度工具里,关键是它必须包含六个要素:真实场景、触发条件、输入、执行步骤、资源、失败边界。 很多人以为把指令写长一点、写细一点,就能得到一个稳定能力包。其实不是。写得越长,反而越容易模糊重点。真正重要的是先把这六个问题回答清楚: - 这件事在什么场景下发生? - 什么信号出现时应该启动它? - 它需要哪些输入? - 执行步骤是什么,顺序能不能变? - 需要访问哪些资源? - 什么情况下它不适用,或者应该停止? 这六点回答了“什么时候用、用什么、怎么走、到哪里为止”。只要这六个要素明确,哪怕步骤只有五步,也能稳定执行;如果这六个要素含糊,写一百条指令也会跑偏。 ## 03、为什么 把重复工作沉淀成能力包,至少带来三个直接收益。 第一是稳定。人的状态有起伏,但流程不会。把代码 Review 的检查项固化成固定步骤后,审查者就不容易因为赶时间漏掉安全检查、边界条件。把数据库排障的排查顺序固化后,不会因为紧张跳过日志分析或备份确认。 第二是提效。省掉的是每次重新梳理思路的时间。以技术文章写作为例,如果已经有了“查官方资料—画字符图—实操—分析问题—提炼洞见—给出行动”的固定路径,每次只需要填充主题和实验环境,成稿时间大幅缩短。 第三是可传承。方法不再只存在某个人脑子里,而是可以交给别人使用、验证、修改。团队里新同事可以靠它快速达到及格线,老同事可以把节省下来的时间投入更难的判断。 从个人效率工具到团队知识资产,这一步沉淀的价值会随着使用次数增加而放大。它不会自动发生,但一旦开始做,收益会非常明显。 ## 04、架构 一个能力包的基本结构可以用下面这个骨架来表示。它不是代码,只是帮助你组织信息的框架。 场景:描述这件事在什么业务或技术背景下出现。例如“需要输出一篇技术实战文章,而不是新闻稿或宣传文案”。 触发条件:描述什么信号或请求出现时,应该调用这个能力包。例如“用户提供了文章主题、目标读者、可用的实验环境,并要求输出实战文章”。 输入:列出执行前必须提供的材料。例如主题、读者水平、实验环境信息、字数要求、是否需要字符画。 执行步骤:按顺序列出核心操作。步骤之间要有先后关系,不能只写一堆要点。例如: 1. 检索官方文档和源码,不采用二手解读; 2. 设计一条最小可复现路径; 3. 用字符画展示关键架构或数据流; 4. 执行操作并记录真实命令和输出; 5. 分析过程中出现的问题和根因; 6. 提炼可迁移的判断; 7. 给出下一步行动建议; 8. 检查是否有遗漏或误导。 资源:列出执行时需要访问的资料或工具,比如官方文档站点、代码仓库、测试集群、监控平台。 失败边界:描述什么情况下应该停止或转人工。例如“官方文档缺失且无法确认版本时,不要基于猜测继续写,应标记为不确定”。 这个框架里,最重要的是触发条件和失败边界。它们定义了能力包的适用范围。一个没有边界的流程,就像一个没有刹车的手术机器人,跑到不该跑的地方会出大问题。 ## 05、实战 我们拿“技术实战文章生成流程”走一遍。假设你要每周输出一篇关于云数据库排障的实战文章,但团队写手水平不一。可以这样固化。 第一,明确场景和触发条件。场景是“技术公众号或开发者社区发布实战文章”;触发条件是“给定主题、目标读者和实验环境,要求输出一篇带实操步骤和排障分析的文章”。注意这里不是“写文章”三个字,而是把条件写清楚。 第二,定义输入。你可以设计一个简短输入模板: 主题:云数据库连接池耗尽排障 读者:有两年以上后端经验的开发者 实验环境:云数据库 8.0,测试集群可用 要求:包含官方资料检索、字符画、复现步骤、问题分析、洞见和行动 字数:3500 字左右 第三,固定执行步骤。把前面骨架里的八步落成确认清单。每一步都有输出,比如“官方资料检索”输出文档链接和关键结论;“字符画”输出一张文本架构图;“问题分析”输出根因和证据链。 第四,运行验证。用同一个主题跑三遍,记录哪些步骤容易卡住。比如第一次执行时,字符画阶段没有定义使用什么工具,导致每个人画法不同。那就把字符画规范写进资源部分,比如“使用文本框图,统一用 ASCII 字符,不超过 20 行”。 第五,复盘修改。每次执行后更新触发条件和失败边界。比如发现如果官方文档没有中文版,部分写手会引用错误来源,就在失败边界里加一条“不确定时以官方英文文档为准,不引用二手翻译”。 这样得到的流程,就不再是一篇“写作指南”,而是一个可以被反复调用的能力包。新同事只要按照输入模板填写信息,按照步骤执行,就能产出质量接近的文章。这里并没有依赖任何复杂的指令技巧,只是把一件事的边界和顺序说清楚了。 ## 06、洞见 我在多次尝试后有一个明显感受:最值得固化的不是知识,而是已经经过多次验证的方法。 知识可以随时搜索,但方法包含判断顺序和上下文。比如“数据库排障要看慢查询日志”是知识,而“先确认连接数是否打满,再查看锁等待,最后分析慢查询”是方法。前者知道也不一定能执行,后者可以直接变成操作路径。 这引出一个关键问题:为什么能力描述那么重要?因为它决定调度器什么时候应该调用这个能力包。描述如果写得太宽,比如“处理数据库问题”,那任何相关请求都可能触发它,但其中很多并不适合这个流程。描述如果写得太窄,比如“处理 MySQL 8.0 连接池耗尽问题”,那稍微变一下场景就不会被调用。 好的描述应该包含场景和触发信号,而不是只写功能摘要。例如:“当用户需要一篇面向后端开发者的技术实战文章,并且已经提供主题和实验环境时,使用该能力包。”它说明白了两件事:一是适用场景,二是启动条件。调度器看到这样的描述,就能在合适的时候调用,而不是靠猜。 失败边界同样重要。一个能力包如果不声明“什么情况下不适用”,它就会在条件不具备时硬上,产出错误结果。比如资料检索不到官方文档时,流程应该停下并提示需要人工确认,而不是继续编造。 所以,能力包的质量不取决于步骤多少,而取决于边界是否清晰、描述是否精准。这也是为什么很多团队做了大量文档却用不起来:那些文档只有知识,没有触发条件,也没有失败边界。 ## 07、行动 看到这里,你可能会想,自己手头哪些工作适合先做。我的建议很简单:从过去一周重复最多的一项工作开始。 具体可以这样做: 1. 花三天记录自己每天重复做的任务,写下任务名、触发场景、输入输出、耗时。 2. 选一个频率高、边界清晰的任务,例如“整理周报”“检查发布配置”“分析接口超时”。 3. 用六个要素把它写下来,先不用追求完美,能回答清楚即可。 4. 在实际工作中按这个流程跑 3 次,每次记录哪里卡住、哪里多余。 5. 根据运行结果修改步骤、触发条件和失败边界。 6. 交给一位同事试用,看他能否独立完成。如果对方需要反复问,说明边界还不够清晰。 7. 给能力包加一个版本号,以后每次修改都简单记录变更原因。 不要一开始就选“架构调研”这种边界模糊、输入复杂的工作。先选一个高频小任务,把它跑顺,你会更容易理解什么是好的描述、什么是清晰的失败边界。做完一个之后,再逐步扩展到代码 Review、技术文章写作、数据库排障这些复杂场景。 ## 08、小结 重复工作之所以累,不是因为它难,而是因为我们每次都在重新发明流程。把重复工作沉淀成稳定能力包,核心动作不是写更多说明,而是把真实场景、触发条件、输入、执行步骤、资源和失败边界这六件事想清楚。最值得固化的不是知识,而是验证过的方法。能力描述决定它何时被调用,失败边界决定它何时停下来。从一个小任务开始,跑三遍,改三遍,你就能做出自己的第一个能力包。 ## 09、链接与概念说明 本文中的“能力包”指一套固定方法的结构化封装,可以供调度工具按条件触发执行。它不同于传统文档,因为它强调触发条件和失败边界,而不是单纯的知识陈列。 延伸概念: - 场景与触发条件:前者是背景,后者是启动信号。两者合在一起,才能让调度器判断“现在该不该用它”。 - 输入与资源:输入是执行者必须收到的材料,资源是执行过程中需要访问的外部资料和工具。 - 失败边界:明确在什么条件下应停止、升级或转人工,这是保证输出可信的关键。 你可以从以下入口继续了解: - 团队内部的知识库中,寻找已经沉淀的标准作业程序,对照六个要素检查缺了什么。 - 你使用的调度工具文档中,查看如何定义触发条件、输入输出和失败策略。 - 开源社区中关于可复用流程设计的讨论,例如“runbook”“playbook”相关实践(注意这些只是术语参考,不同工具叫法不同)。 (全文完)

优秀的个人博客,低调大师

《WorkBuddy Skills 实战》第4招 Skill也能变插件

## 01、痛点 上周,我们团队一个新来的同事在代码评审里被连续打回四次。不是他水平差,而是团队里那套“提交前检查规范”藏在不同人的笔记和脚本里,版本还不一样。有人笔记本里记的是三年前的规则,有人用的是自己改过的脚本,还有人干脆不知道有这个规范。新同事按A的笔记操作,结果被B的脚本拦下来,一脸茫然。 我是老李,这几年一直在做工程效率的事情。我见过太多个人顺手写的小工具,最后变成团队协作的绊脚石。很多人一开始只是想解决自己的问题,写个检查脚本、配个钩子,跑通了挺开心。但团队一铺开,问题就来了:脚本散落在各个仓库,配置互相冲突,规则更新靠口头通知。于是有人提议:“咱们把这些东西打包成一个插件吧,一键安装,统一发布。” 这个想法没错,但时机很关键。最近我在几个项目里看到两个极端:有的团队太早做封装,把还没跑稳的流程塞进插件,结果错误被快速复制到所有项目,一个地方踩坑,全部项目一起踩;有的团队一直不做,每个项目各搞一套,维护成本高得离谱,改一个规则要改七八个地方。所以我特别想聊聊“什么时候该从单个技能升级到插件”这件事。 现在很多团队都在做工具沉淀,但“沉淀”不等于“封装”。沉淀是知道什么有用,封装是让有用的东西可复制。两者之间隔着一段必须走完的路。 ## 02、是什么 先厘清两个基本概念。 技能,可以理解为一个原子能力。比如一段能自动整理代码格式的脚本,一个能检查提交信息是否符合规范的钩子,或者一个能调用外部工具查接口文档的任务描述。它通常只解决一个具体问题,输入输出清晰,边界明确。你可以把它想象成工具箱里的一把螺丝刀,只干一件事,但干得利索。 插件,则是一组能力的集合。它可以把多个技能、脚本、钩子、外部工具接入方式和配置项打包在一起,形成一个可分发、可版本化、可统一安装的单元。插件关心的是“一组能力如何协同工作”,而不是单个能力本身。它更像是一套完整的工作台,上面有螺丝刀、扳手、钳子,还有使用说明和摆放位置。 打个比方:技能像一块乐高积木,插件像一套主题套装。你手里的单个积木可能很好用,但当你需要把消防局、警察局和医院一起拼出来时,套装的价值就显现了。套装里不仅有积木,还有说明书、分类袋和缺件补发机制——这些对应到插件里,就是配置、依赖和更新策略。 回到日常场景:个人写作时只需要一个“检查错别字”的技能,没必要搞插件;但团队要统一发布“代码规范 + 持续集成 + 代码评审 + 部署检查”时,单独一个个技能散着发就很痛苦,这时插件开始体现价值。注意,价值体现在“统一”和“组合”上,而不是“打包”本身。 ## 03、为什么 为什么插件在这个阶段有价值?因为团队协作面临的不是“有没有能力”,而是“能力是否一致、是否可维护、是否可追溯”。 一个插件通常解决三类问题: 第一,分发一致性。团队里每个人拿到的配置和脚本版本完全一样,不会出现A项目还在用旧检查规则,B项目已经用新规则的情况。一致性是协作的基础,尤其当团队跨地域、跨时区时,版本不一致带来的排查成本往往超过开发成本。 第二,组合复用。多个技能之间往往有依赖关系,比如代码规范检查要在提交前运行,部署检查要在构建后运行。插件可以把这些执行顺序和依赖关系固化下来,避免每个人手动串联时出错。组合复用不是简单把文件放在一起,而是把“它们该怎么配合”也封装进去。 第三,维护成本。当规则需要更新时,只需升级插件版本,而不是通知每个人去改脚本。对于跨团队或跨项目协作,这一点尤其重要。一个五十人的团队,如果没有插件化,一次规则变更可能需要五十个人分别改本地配置,其中一半人会漏掉或改错。 但为什么不要过早插件化?因为插件化本质上是一种“标准化”。标准化本身没有错,但标准化的前提是流程已经被验证相对稳定。如果流程本身还在频繁变化,甚至存在已知错误,封装成插件只会让错误以更快的速度扩散到所有使用方。 举个例子:你有一个检查脚本,只在自己的项目里跑过两次,规则可能还有漏洞。这时候把它塞进插件发给三个团队,三个团队同时踩坑,你修一次插件要影响九个项目。原本修改一个脚本的成本是五分钟,现在变成升级、回滚、通知、重新验证的一整套动作。错误传播的速度,远比想象得快。未经验证的流程一旦标准化,错误就不再是个人问题,而是系统问题。 ## 04、架构 一个典型的插件内部通常包含这几层: 配置层:负责管理插件本身以及各类能力的开关、参数和路径。比如是否启用代码规范检查、检查的严重级别、需要忽略的目录等。配置层要做成可覆盖、可合并的形式,否则不同项目之间无法差异化。好的配置层能让插件“开箱即用,按需调整”。 能力层:由多个技能组成。每个技能是插件里的一个执行单元,可能是一个脚本、一个钩子,或者一个调用外部工具接入的任务。能力层之间尽量不要直接调用,而是通过配置层和事件机制串联,这样替换某个技能时不会影响整体。能力层是插件的地基,但地基不等于房子。 编排层:定义技能之间的执行顺序、触发时机和错误处理。比如“提交前先跑格式检查,再跑单元测试,如果格式检查失败就阻止提交并给出提示”。编排层是插件产品化的关键,它让插件从“一堆工具的压缩包”变成“一个有明确行为的产品”。很多插件失败不是因为能力不够,而是编排混乱,导致行为不可预期。 分发层:负责插件的版本号、更新渠道、兼容性声明和回滚机制。这一层常常被忽略,但对于团队长期使用来说,比能力层更重要。没有版本号和回滚机制,插件一旦出问题,团队只能手动卸载重装,效率极低。分发层就像软件的发布通道,决定了问题发生时你能不能快速止损。 以我们团队最近做的 WorkBuddy 插件为例,里面封装了两个常用技能:一个是“提交信息合规检查”,另一个是“变更影响范围提醒”。这两个技能原本是独立脚本,各自运行没问题,但单独分发很麻烦。我们把它们放进同一个插件,配置层统一管理规则文件,编排层规定“提交时先检查提交信息,再根据变更文件生成影响提醒”,分发层定义了版本号和升级命令。这样团队成员只需要安装一个插件,就能同时获得两个能力,并且规则更新只在一处发生。 ## 05、实战 说一个具体过程。我们想把两个常用技能封装到同一个 WorkBuddy 插件中。这两个技能:一个检查提交信息是否符合“类型 + 模块 + 简短描述”的格式;另一个在提交后扫描变更文件,提醒可能影响的下游模块。 第一步:确认每个技能本身已经稳定。我们在至少三个不同项目里分别使用过这两个技能,累计运行超过两个月,规则没有大的调整。这是封装的前提。如果还在频繁修改规则,封装后每次改规则都要走插件发版,得不偿失。稳定不是“我写完了”,而是“它在多个环境里跑了一段时间没出大问题”。 第二步:设计统一配置入口。我们定义了一个配置文件,包含两个技能的开关、检查规则路径、影响范围映射表。对于不同项目,只需要改这个配置文件,不需要改插件内部逻辑。配置入口要足够简单,让使用者不用读源码也能明白每个参数是干什么的。 第三步:处理冲突和依赖。两个技能都挂在提交相关事件上,需要明确顺序:先做提交信息检查,失败则直接阻止提交;通过后再生成影响范围提醒,提醒不阻止提交。这个顺序通过编排层写死,避免团队成员自行调整导致行为不一致。冲突处理是实战中最容易踩坑的地方,一定要在封装前把技能之间的交互边界想清楚。 第四步:发布预览版。先在一个小团队试点一周,收集反馈。果然发现一个问题:某些临时分支的提交信息不符合规范,但临时分支不需要严格检查。我们在配置层增加了“分支白名单”,让临时分支可以跳过检查。这个修改只影响配置文件,插件代码不变。如果没有预览期,这个问题会直接暴露给所有团队。 第五步:正式发布并设置版本号。我们给插件定了一个初始版本,约定后续规则调整必须走版本升级和变更说明。这样团队成员知道自己用的哪个版本,出问题时能快速定位。版本号不是为了好看,而是为了可追溯。 整个过程下来,团队里抱怨“检查规则不一致”的声音明显少了。但我也清楚,如果两个月前我们直接插件化,当时检查规则还在一周改三次,这个插件根本没法用。 ## 06、洞见 这件事让我越来越觉得:技能是经验复用,插件是能力产品化。 经验复用是个人层面的效率提升。你发现一个重复问题,写个脚本或整理一套检查步骤,下次遇到直接拿来用。这个阶段不需要给别人用,不需要考虑版本、兼容、文档,越快越好。经验复用的关键词是“快”。 能力产品化则完全不同。产品化意味着你要对这个能力集合负责:它的行为是否可预测?不同环境下是否一致?出错了怎么排查?升级会不会破坏老用户?这些问题都要求能力本身已经相对成熟。产品化的关键词是“稳”。 过早插件化最大的风险,就是错把“经验复用”当成“产品化”。一个未经验证的流程一旦被标准化,错误就不再是个别人的问题,而是整个系统的问题。原来错误只影响一个人,封装后错误影响所有使用方,而且修改错误的成本从改一个脚本变成发一个新版本。错误传播的速度,远比我们想象得快。 所以判断标准很朴素:这个东西是否已经跨项目重复出现且行为稳定?如果是,再考虑插件化;如果不是,继续把它当技能迭代。工具只是手段,判断力才是核心。 ## 07、行动 如果你正在纠结要不要做插件化,我的建议是: 第一步,个人先做技能。不要一开始就想做一个大而全的插件。把你日常重复的操作写成一个技能,只给自己用,快速迭代。这个阶段追求的是“能用”,而不是“通用”。 第二步,让技能在真实项目中跑起来。至少在两到三个不同项目中使用,观察它是否适应不同场景。记录哪些地方需要改,哪些规则还不成熟。真实项目会暴露很多单人使用时看不到的问题。 第三步,当技能已经跨项目重复且稳定后,再评估是否插件化。评估维度包括:是否有多人需要?是否需要统一更新?是否有依赖顺序需要固定?如果答案都是“是”,再做。 第四步,如果确定要做,从最小插件开始。不要一上来封装十几个技能。先封装两个最稳定的技能,建立配置、版本和回滚机制,跑通整个链路。最小可行产品原则在这里同样适用。 第五步,发布后保持克制。插件发布不代表流程固化。每三个月回顾一次插件的使用情况,及时淘汰已经不再需要的技能,保持插件精简。过重的插件反而会降低团队效率,因为维护成本会吃掉收益。 ## 08、小结 回到最开始的问题:为什么不要过早插件化?因为插件化是能力产品化的动作,它应该发生在经验复用已经稳定之后。技能解决的是“我怎么做”,插件解决的是“我们怎么做”。个人先做技能,跨项目重复稳定后再插件化,这个顺序不能反。顺序错了,工具越多,问题越多。 ## 09、链接与概念说明 文中涉及几个概念,简要说明: 技能:可独立运行的最小能力单元,通常解决单一问题。它是经验复用的载体。 插件:将多个技能、脚本、钩子、外部工具接入方式和配置打包而成的可分发、可版本化集合。它是能力产品化的形式。 钩子:在特定事件发生时自动触发的执行逻辑,比如提交代码前、构建完成后。它让能力能够嵌入到已有流程中。 外部工具接入:通过约定接口调用外部工具或服务的能力,帮助插件获取额外信息或执行额外操作。它是插件扩展性的来源。 配置:插件中用于适配不同项目环境的参数集合,通常独立于代码,便于修改。好的配置设计能显著降低使用成本。 如果需要进一步了解插件化实践,建议从团队内部一份“重复操作清单”开始,而不是从工具选型开始。工具会过时,判断力不会。把问题想清楚,再动手封装。

优秀的个人博客,低调大师

《WorkBuddy Skills 实战》第5招 动手前先出计划

凌晨一点十七分,生产环境的登录接口开始成片报 401,我盯着屏幕手有点抖。三小时前,我还在跟同事说“这个 OAuth2 改造不难,加个依赖、改下配置就行”。我是老李,一个在后端摸爬滚打十年的程序员。今天想跟你聊一件反直觉的事:AI 编程最大的坑,很多时候不是它不会写,而是它写得太快。 ## 01、痛点 团队引入 AI 编程之后,交付速度确实上来了,但返工率也跟着上来了。最典型的场景就是登录系统改 OAuth2。很多同学接到需求,第一步就是打开 SecurityConfig,直接往里面加 oauth2Login,再补一个依赖。跑起来一看,登录页跳不过去、回调地址报错、Session 策略没跟着改、测试用例挂了一片。 问题出在哪?不是 AI 不会写 SecurityConfig。它能写出语法正确、甚至框架用法都对的代码。但它不知道这个仓库里还藏着自定义的认证过滤器,不知道前端有一个回调处理组件写死了原来的表单登录返回结构,更不知道那套 Session 并发控制跟新的登录态有冲突。它看到的是局部文件,不是整条认证链。 我们缺的不是更强的生成能力,而是生成之前对仓库的理解能力。过去老程序员动手前会先翻几处代码、画一下调用链。现在 AI 一上来就能输出几十行,把“翻代码”这一步直接跳过了。速度是快了,方向却常常偏了。 ## 02、是什么 create-plan 的核心,是让 WorkBuddy 在真正修改代码之前,先理解仓库、影响面、依赖和测试路径。它不是生成一个漂亮的计划文档,而是先把“应该改哪里、先改哪里、改完怎么验证”想清楚,再动手。 仍以登录系统改 OAuth2 为例。创建计划时,WorkBuddy 不会一上来就改 SecurityConfig。它会先扫描认证相关代码,找到 SecurityFilterChain、自定义 Filter、UserDetailsService、Session 配置、前端回调所在目录,以及已有的登录测试。接着把这些信息拼成一张影响面清单:哪些文件必须改,哪些文件可能被间接影响,哪些测试需要补。 计划的输出通常包含几个部分:改动目标、前置依赖、影响面列表、执行顺序、风险点、验证方式。它更像一份施工前的放线图,而不是事后补的施工日志。有了这张图,哪怕 AI 生成得再快,也会被框在一个已经过验证的方向里。 ## 03、为什么 AI 编程最大的问题往往不是不会写,而是写得太快。快本身不是坏事,但在没有理解上下文时,快会把错误放大。 你可以把生成过程想象成一辆没有刹车的高速车。模型看到一个文件,就根据局部上下文输出代码;它不会主动去查另一个模块里的 Session 管理器,也不会意识到前端还有回调处理。没有减速带,车就直接冲进了 SecurityConfig。 计划相当于给高速生成加一道减速带。它在“理解”和“修改”之间插入一个中间层,强迫先把影响面看全。这个过程不需要人肉去翻所有文件,WorkBuddy 可以自动完成大部分扫描,但关键结论要落在计划里,成为后续修改的约束。 另一个好处是,计划能提前暴露错误方向。很多错误不在代码语法上,而是在选错了改动起点。比如把 OAuth2 的 state 校验写进后端过滤器,却忽略了前端回调会丢失 state 参数。如果先做影响面分析,第一轮计划就会标记出“前端回调参数不完整”,而不是等到联调时才发现。 ## 04、架构 create-plan 在 WorkBuddy 里不是单一功能,而是一条由多个环节组成的前置链路。整体上可以分成四层。 第一层是仓库感知。WorkBuddy 会先读取目录结构、构建文件、路由表、配置项,判断这是一个前后端分离项目还是单体应用,确认认证逻辑集中在哪些模块。它不直接读全部代码,而是先建立索引,减少无关文件的干扰。 第二层是依赖图谱。从入口如 SecurityConfig 出发,沿着注解、自动装配、过滤器链、拦截器、Cookie/Session 工具类,把相关类和方法串起来。这一步能发现那些藏在角落里的自定义组件,比如一个继承了 OncePerRequestFilter 的 Token 校验器,或者一个写了静态方法却在 12 个地方被调用的 SessionUtil。 第三层是影响面分析。依赖图谱建好之后,就能回答三个问题:改 A 会不会影响 B;先改哪个文件最安全;哪些改动需要同步调整前端或测试。对于登录改 OAuth2,它会列出 SecurityConfig、自定义过滤器、回调控制器、前端回调页面、测试夹具等。 第四层是测试路径提取。WorkBuddy 会搜索现有测试目录,找到登录相关的单元测试、集成测试和端到端测试,标记出哪些会在改动后失败,哪些覆盖不到新逻辑。比如授权码模式下需要测试 state 参数校验失败的情况,但原测试里根本没有这条用例,计划里就会自动补上这条验证路径。 这四层并非顺序执行完才出计划,而是边扫边出中间结果,最终汇总成一份执行计划。 ## 05、实战 为了看清“直接写”和“先计划再写”的差别,我在同一个需求上做了对比:把一个基于表单登录的 Spring Security 系统改成 OAuth2 授权码登录。 直接写的路径很典型。我先让 WorkBuddy 直接改 SecurityConfig,加入 oauth2Login 和 client 注册信息。第一次生成代码没有语法错误,依赖也加对了。但启动后登录页能跳转到 OAuth2 服务,回调回来却报 403。原因是项目里有一个自定义的 JwtAuthenticationFilter,它在 OAuth2 登录流程中仍然生效,把回调请求当成了未携带 JWT 的请求直接拦截了。 第二次修改,去掉那个过滤器对回调路径的拦截。登录终于通过,但前端页面没拿到用户信息。前端一直从 /api/me 接口取用户,而后端 /api/me 是根据 Session 中的老登录态来取。OAuth2 回调成功后,Session 里放的对象结构变了,前端解析直接抛异常。 第三次修改,统一 Session 对象结构。跑起来后,又发现测试环境有两条用例永远失败:一条是模拟表单登录的集成测试,一条是验证 Session 并发控制的测试。因为它们仍然依赖旧登录机制。为了改这两条用例,又顺手改了测试基类和两个工具方法。 整个过程下来,一共动了 9 个文件,返工 3 次,耗时将近一天。最麻烦的不是改代码,而是每次跑起来才发现漏了另一个环节。 再看“先计划再写”的路径。我先让 WorkBuddy 创建计划。它没有直接改 SecurityConfig,而是先列出认证链上的所有节点:SecurityFilterChain、自定义 JWT 过滤器、UserDetailsService、回调控制器、前端回调页面、/api/me 接口、Session 配置、登录相关测试。计划里标出三个关键风险:自定义过滤器会拦截回调;Session 对象结构不一致;测试用例覆盖不到新登录流程。 然后按照计划顺序执行:先调整过滤器放行规则,再统一 Session 结构,接着改前端回调参数处理,最后补两条 OAuth2 测试用例。执行过程没有出现“跑起来才知道漏了”的意外,一次通过,改动文件数也是 9 个,但返工次数为零。 同样的需求,同样的 9 个文件,差别不在代码生成质量,而在改代码之前的 20 分钟。 ## 06、洞见 很多人以为计划的价值是留下一份文档,方便以后复盘。其实不是。计划真正的价值,是在你投入精力和算力之前,提前暴露错误方向。 我们回头看登录改 OAuth2 的例子。最贵的错误不是写错了一行代码,而是把整个改造的起点选在了 SecurityConfig。第一步一旦选错,后面的过滤器拦截、Session 结构、前端解析都会变成连环坑。计划的作用,就是在动手前问一句:第一步真的该改 SecurityConfig 吗? 计划的另一个隐藏价值是,它把 AI 的“局部最优”拉回到“全局可行”。模型擅长根据当前文件给一个看似合理的方案,但它不擅长主动跨越模块去核对影响。计划机制通过仓库扫描和依赖图谱,把跨模块的信息补了回来。这样 AI 生成的快,就变成在正确方向上的快,而不是在错误方向上的快。 所以,不要把计划当成额外负担。它不产出产品功能,但能避免那些半夜把你叫起来的返工。 ## 07、行动 计划很有用,但也不能无限扩大。一个修拼写的小改动、一条日志级别调整、一个常量重命名,如果也要先扫描仓库、建依赖图谱、列测试路径,那成本就大于收益了。 我的判断标准很简单:中大型需求默认先 Plan,小修复直接执行。 具体来说,满足下面任意一条,就值得先走 Plan: 第一,预计改动文件超过 3 个;第二,涉及认证、权限、支付、数据迁移等敏感逻辑;第三,需求跨前后端或跨模块;第四,现有测试覆盖不清晰;第五,你无法立刻说出谁是下一个受影响的人。 反过来,如果只是改一个文案、修一个空指针、加一条日志,直接让 WorkBuddy 执行即可。小修复走完整计划,就像给自行车螺丝上四轮定位,看似严谨,实则浪费。 中大型需求里,Plan 的时间控制在 15 到 30 分钟比较合适。如果计划本身超过这个时间,说明需求拆得不够小,或者对仓库的索引还不够成熟。这时候应该先缩小需求范围,而不是继续扩大计划。 ## 08、小结 AI 编程的瓶颈已经从“能不能写出来”变成了“能不能改对地方”。写得太快而理解太少,是现在返工的主要来源。create-plan 用一道计划减速带,把仓库理解、影响面、依赖和测试路径放到修改之前,让高速生成不至于跑偏。 登录系统改 OAuth2 这个场景很典型:真正困难的不是加依赖、写回调,而是搞清楚原有认证链上的每个节点怎么配合。计划的价值不是文档,而是提前暴露错误方向。中大型需求默认先 Plan,小修复直接执行,这个尺度把握好,AI 编程的速度优势才能真正变成交付优势。 ## 09、链接与概念说明 OAuth2 授权码模式:客户端先跳转到授权服务器,用户同意后带回授权码,客户端再用授权码交换访问令牌。改造时重点确认回调地址、state 参数和令牌存储。 Spring Security 的 SecurityFilterChain:过滤链是安全配置的核心。多个过滤器按顺序执行,自定义过滤器如果没有放行 OAuth2 回调路径,会直接拦截请求,这是最常见的坑。 Session 并发控制与固定攻击防护:表单登录改 OAuth2 时,Session 中用户对象的字段变化,可能导致前端解析失败,也可能让原有的并发 Session 策略失效。计划分析时需要把 Session 看作认证链的一部分。 测试路径:至少包含三条——认证成功、认证失败、state 校验失败。现有测试如果没有 state 校验失败的用例,就需要在计划中补齐。 参考建议:在实际改造前,先跑一遍项目的登录集成测试,把认证链相关的文件列表拉出来。这样即使不用任何自动化扫描,也能手动做一个最小版的影响面清单。

优秀的个人博客,低调大师

《WorkBuddy Skills 实战》第6招 需求不清先拷问

项目又延期了。这次不是数据库挂了,也不是发布脚本出错,而是开发到第三周时,团队为一个问题吵了一上午:智能体平台里的“用户记忆”到底该保存多久?有人说永久保存能提升体验,有人说隐私风险太大,还有人问要不要做用户授权。产品经理被问懵了,最后说:“先按三个月吧,后面再说。” 我是老李。这几年带团队做后端和平台类项目,最怕的不是技术难,而是需求只有一句话。“帮我做一个智能体平台”这句话听起来清晰,实际上一旦动手,你会发现里面藏着一堆没有言明的设计决策。模型接入怎么管理?工具调用超时怎么处理?租户之间的数据边界在哪?计费按什么维度?观测日志要留下什么?这些问题任何一项拍错,后面都可能返工。 为什么现在要讲这个?因为越来越多团队开始让工作伙伴参与需求澄清和方案生成,但如果它只会顺着你说,或者为了显得聪明不停追问小问题,那还不如不用。今天要聊的 grill-me,就是一种反向追问机制:先让工作伙伴产出初步方案,再让它针对方案连续追问,把那些“你不问没人说、你不说就默认”的关键分支逼出来。 ## 01、痛点 大部分需求失败,不是少写了功能,而是关键边界从来没人说清楚。注意这里说的是边界,不是功能列表。功能列表往往一眼能看到,但权限、异常、数据边界、兼容策略和“这一版不做什么”,才是真正决定项目成色的部分。 举个例子。产品经理说“做一个智能体平台”,开发人员脑子里可能立刻浮现出:模型层、工具层、记忆层、对话层、管理后台。这个方案没错,但它只覆盖了主路径。真正干活时,问题全在分支上: - 权限:平台管理员和普通用户看到的界面一样吗?谁能创建智能体?谁能调用某个工具?授权粒度到角色、资源还是操作? - 异常:模型接口超时返回什么?工具执行失败要不要重试?重试几次?用户能看到错误细节吗? - 数据边界:用户上传的文档存在哪?跨租户会不会串数据?日志里能不能记录用户输入内容? - 兼容策略:不同模型供应商的返回格式差异怎么处理?接口版本升级后老客户端怎么办? - 不做范围:第一版不做工作流编排、不做本地模型、不做多语言,这些“不做”如果不写下来,后面会被当成缺陷来提。 这些不是开发拍脑袋能定的,也不是代码或技术资料能自动确认的。它们必须由业务、产品、安全甚至法务来给结论。可现实是,需求文档里几乎没有这些内容,于是开发只能“默认”。默认的结果就是,测试阶段发现一堆“需求没写,但你不能说我有错”的坑,然后返工。 更糟的是,这些坑往往不是一次性暴露,而是随项目推进分批出现。一开始只是问“权限多少种角色”,然后是“模型密钥谁填”,接着是“欠费了要不要停服”,最后是“审计日志保留多久”。每一次追问都像挤牙膏,项目节奏被反复打断。 ## 02、是什么 grill-me 是一个反向追问机制。它的用法很简单:先让 WorkBuddy 根据一句话需求生成一个初步方案,然后触发 grill-me,让 WorkBuddy 反过来对这份方案连续追问。 注意,它不是让工作伙伴漫无目的地问“你还有什么补充吗”,而是围绕五个固定维度做系统排查:权限、异常、数据边界、兼容策略、不做范围。每一次追问都必须指向方案里没写清楚、代码和资料又无法自行确认的决策点。 比如初步方案写了“支持多租户”。grill-me 不会问“什么是多租户”,因为这是技术常识;它会问:“租户之间如何隔离?是独立数据库、独立 Schema,还是共享表加租户字段?租户配额谁来配置?租户注销后数据保留多久?”这些问题,工作伙伴无法替你拍板,需求方也不能永远用“按行业惯例”来搪塞。 这套机制的核心,是把“隐性假设”和“未决分支”这两样东西从方案里抓出来。隐性假设是那些你没写、但方案默认成立的条件,比如“所有用户都经过企业认证”。未决分支是方案里出现了选择,但没人指定走哪条路,比如“计费方式按调用量还是按订阅席位”。这两类问题一旦被显性化,需求就从一句模糊的话,慢慢变成一张可执行的决策清单。 ## 03、为什么 为什么需要反向追问,而不是正向追问?因为正向追问通常由需求方发起,比如“你们能不能支持一下某某功能”。它往往是发散式的,想到哪问到哪,容易漏掉真正致命的部分。反向追问则不同,它要求工作伙伴先给出一个完整方案,再带着方案回到需求里找漏洞。方案就像一张地图,追问就是在地图上标记哪里没有路、哪里有悬崖。 从项目经验看,需求失败的主要成本不是“少做了功能”,而是“做错了假设”。少做一个功能,后续补上相对容易;做错一个权限模型,可能要把底层表结构、接口鉴权、前端控制全部翻一遍。前者是增量,后者是重构。这就是为什么我们要把追问前置。 另外,反向追问能降低协作摩擦。需求方大多不喜欢被问一堆基础问题,比如“你这个系统是给谁用的”“要不要登录”。但如果你拿一个初步方案过去,再问“这个方案里管理员角色可以删除其他租户的数据,是否符合你的预期”,对方会更容易给出有效回答。因为问题变得具体了,且带有上下文。 还有一个原因:工作伙伴的产出质量,很大程度上取决于输入质量。需求清楚,方案就稳;需求模糊,后面的代码生成、测试用例、部署配置全都会偏。grill-me 相当于在源头加一道关卡,把模糊拦在写代码之前。 ## 04、架构 grill-me 的运行机制可以拆成四个阶段。 第一阶段,生成初始方案。工作伙伴根据输入的需求,先产出结构化的初步方案。方案不要求完美,但至少要覆盖主流程、模块划分、数据流向和关键组件。这个方案的目的是给后续追问提供一个“靶子”。 第二阶段,识别假设与分支。grill-me 对初始方案做静态扫描,找出里面隐含的假设和未决分支。识别过程不是凭感觉,而是按维度扫描:权限、异常、数据边界、兼容策略、不做范围。每个维度下再细分子项,例如权限维度会扫描角色、资源、操作、隔离级别;数据边界维度会扫描存储位置、保留周期、脱敏策略、跨边界访问。 第三阶段,生成追问清单。每个识别出的假设或分支,必须有对应的追问。追问要满足三个条件:一是代码和资料无法自行确认,二是回答会改变设计或实现,三是可以用选项或范围来回答。满足不了这三个条件的,不进入清单。 第四阶段,按优先级追问并更新方案。grill-me 不会一次性把几十个问题全部抛出来,而是按影响面排序,先问会阻塞整体架构的问题,再问局部实现问题。需求方每回答一轮,就把答案合并进方案,并触发下一轮追问,直到关键分支闭合。 这里有一个非常关键的控制:grill-me 必须在追问数量上保持克制。它不是为了显得聪明无限提问,而是只问高价值问题。如果一个问题可以通过代码库、官方文档或技术验证自己确认,它就不该出现在清单里。只有那些必须由人拍板、且拍错代价很大的问题,才值得占用需求方的时间。 ## 05、实战 拿“帮我做一个智能体平台”这个需求来跑一遍。 第一步,先别急着让工作伙伴写代码,让它产出一份初步方案。方案可能长这样: > 本平台支持多模型接入,提供工具调用、会话记忆、多租户管理、按量计费和基础观测能力。用户可创建智能体,配置模型与工具,发布后通过接口调用。 这个方案看起来像那么回事,但里面全是坑。接下来触发 grill-me。 grill-me 第一轮追问可能包括: 1. 多租户的隔离级别是什么?共享数据库、独立 Schema,还是独立实例?租户删除后数据如何处理? 2. 模型密钥由平台统一管理,还是租户自行提供?如果租户提供,是否支持加密存储和轮换? 3. 工具调用的超时时间、重试次数、并发上限分别是多少?工具执行失败后,调用方收到什么错误码? 4. 会话记忆默认保存多久?是否包含用户输入原文?用户能否导出或删除? 5. 权限模型到角色、资源、操作哪个粒度?是否支持跨租户授权? 6. 计费按 token、调用次数还是订阅周期?欠费后是立即停止还是给宽限期? 7. 观测日志要记录哪些事件?是否包含请求体?日志保留多久?谁有权查看? 8. 第一版明确不做哪些能力?例如不做工作流编排、不做本地模型、不做多语言。 注意,这些问题没有一个是“模型有哪些类型”或者“工具接口怎么写”这类技术问题。因为那些是可以查资料、看代码解决的。grill-me 只问人才能拍板的业务决策。 团队拿到清单后,逐项找产品、安全、法务确认。比如数据边界那条,安全同事要求用户输入原文不得进入日志,会话记忆默认 7 天,延长需用户授权;计费那条,产品决定第一版按调用次数计费,欠费保留 72 小时;权限那条,第一版只做平台管理员和租户管理员两个角色,资源级权限后续再加。 每确认一轮,方案就更新一次。第二轮 grill-me 会继续追问新暴露的分支,例如“租户管理员能否查看该租户下所有智能体的会话记录”“模型供应商限额用尽后,排队还是直接失败”。但第二轮的追问数量明显减少,因为很多关键分支已经在第一轮闭合了。 这个过程的产出不是一堆聊天记录,而是一份不断收敛的需求决策表。开发拿到的不是“你看着办”,而是有据可查的边界说明。 ## 06、洞见 很多人以为好的工作伙伴协作,是问题越少越好,最好别烦我。但我的体会是:好的协作不是少问问题,而是只问高价值问题。 什么叫高价值问题?三个标准:一是答案无法从代码和资料中自动获得;二是答案一旦错误,返工成本很高;三是问题可以用选项或范围来回答,而不是让人写一篇小作文。符合这三个标准,哪怕多问几个,团队也愿意回答。不符合这三个标准,哪怕只问一个,也让人觉得烦。 grill-me 的一个重要设计,就是防止工作伙伴为了“显得聪明”无限提问。有些工具会不断说“还有一个小问题”“再确认一下这个细节”,最后把需求方问跑了。那样不是澄清,是消耗。grill-me 必须有预算意识:优先问阻塞性问题,批量给出,带默认建议。 还有一个容易被忽略的点:反问要带上下文。不要问“权限怎么做”,而是问“方案里管理员可以管理所有租户,是否符合你的预期?如果不符合,你希望限制在哪个范围?”后者更容易回答,因为它给出了具体的锚点。 最终,需求澄清的目标不是消灭所有不确定性,而是把不确定性降低到可以开工的程度。很多小分支可以在开发过程中通过日志、接口设计、配置项来吸收,不必全部提前确认。关键是别让那些会推翻架构的分支藏到最后。 ## 07、行动 落地起来其实就一句话:模糊需求先 grill,明确任务直接干。 判断标准很简单:如果你拿到需求后,脑子里能立刻列出主流程、权限边界、异常处理和不做范围,那就直接开工,别走流程。但如果你发现需求只有一句话,或者团队成员对“谁有权限”“数据存多久”“失败怎么办”这些问题答案不一致,那就先 grill。 具体可以这样操作: 1. 先让 WorkBuddy 产出初步方案,不要一上来就问问题。 2. 触发 grill-me,让它围绕权限、异常、数据边界、兼容策略、不做范围生成追问清单。 3. 人工筛选清单,合并重复项,标注每个问题的决策方是产品、安全、法务还是运维。 4. 带上候选答案或默认建议去问,减少对方思考成本。 5. 把确认结果回写进方案,更新需求文档,形成决策记录。 6. 明确任务不要强行套用 grill-me。比如“给这个接口加一个超时参数”这种需求,直接做就行,反问反而添乱。 另外,grill-me 不是一次性工具。需求变更时,可以重新触发,让工作伙伴检查变更是否破坏既有边界。例如产品突然说“第一版要支持多语言”,这就动了“不做范围”的边界,必须重新确认哪些模块受影响。 ## 08、小结 grill-me 的本质,是把需求评审里最容易漏掉的假设和分支,变成一套可复用的反向追问动作。它不负责替你做决策,而是逼着决策在人写代码之前发生。 回头再看“帮我做一个智能体平台”这句话,它本身没有错,只是粒度太粗。真正要落地的,是模型、工具、记忆、权限、租户、计费、观测这些子问题,而每个子问题背后都藏着权限、异常、数据边界、兼容策略和不做范围。谁能在动工前把这些说清楚,谁就能少返工。 下次再遇到一句话需求,别急着说“行,先做着”。先让工作伙伴出一个方案,再让它反过来问你几个高价值问题。问对了,比写快了更重要。 ## 09、链接与概念说明 本节对文中关键概念做简要说明,便于后续查阅。 - grill-me:一种反向追问机制,让 WorkBuddy 在生成初步方案后,针对方案中的隐含假设和未决分支连续追问。 - WorkBuddy:文中代指参与需求澄清与方案生成的协作工作伙伴,具体产品名以实际工具为准。 - 智能体平台:指支持模型接入、工具调用、会话记忆、多租户使用和观测的软件平台。 - 隐含假设:方案中未明确写出、但默认成立的前置条件,例如“所有用户都已实名认证”。 - 未决分支:方案中已经出现、但未被指定走向的决策点,例如“计费按调用量还是订阅制”。 - 权限维度:包括角色、资源、操作、隔离级别和跨边界授权。 - 数据边界:包括存储位置、保留周期、脱敏策略、导出与删除能力。 - 兼容策略:包括多版本接口、供应商差异、客户端升级与降级处理。 - 不做范围:当前版本明确不实现的能力,防止后续被误认为缺陷。 延伸阅读建议关注需求澄清、多租户架构、计费模型和审计日志设计等方向。若团队已有需求文档模板,可在模板中加入“权限、异常、数据边界、兼容策略、不做范围”五个小节,作为 grilling 的默认检查面。

优秀的个人博客,低调大师

《WorkBuddy Skills 实战》第7招 测试先亮红灯

## 01、痛点 先讲一个真实场景。团队最近用 WorkBuddy 开发订单中心,需求是“取消订单”。需求文档写着:已支付订单不能取消,待支付订单可以取消。听起来很简单。我们让编程助手直接生成实现,几秒钟就出了代码。我 review 一遍,代码结构清晰,字段判断也有,就提交了。结果测试环境一跑,发现已支付订单照样能取消。问题出在助手生成的代码只判断了订单状态是否等于“待支付”,其它状态一律放行,而测试环境里那笔订单是“已支付”。如果没有自动化测试,这种缺陷要么靠人眼盯,要么靠线上用户发现。更麻烦的是,后续改库存释放逻辑,又把取消校验改坏了一次。 这就是当前很多团队面临的情况:生成代码很快,验证代码很慢;看起来对的代码不一定能跑;改一处逻辑,其它地方悄悄坏掉。根本原因是缺少一个稳定、快速、可重复的反馈环。人工 review 只能抓风格问题,很难每次覆盖边界条件;手动点界面又太慢,回归一次成本很高。于是代码越多,心里越没底。订单取消只是一个小功能,但缺反馈的问题会放大到整个系统。 ## 02、是什么 TDD 并不神秘,它就是把开发过程拆成三步:红灯、绿灯、重构。红灯是写一个会失败的测试,表达你期望的行为;绿灯是写刚好让测试通过的最少代码,不额外设计;重构是在测试保护下整理结构,去掉重复、提升可读性。然后把这三步循环起来,形成反馈环。很多人以为 TDD 就是“先写测试”,其实重点不是先后顺序,而是循环:失败、通过、整理、再失败、再通过、再整理。 放到 WorkBuddy 里,这个循环可以被固化成开发节奏。比如开发订单取消,不是先让编程助手写完整实现,而是先让它生成一个针对“已支付订单不能取消”的失败测试。测试运行失败,说明这条规则被真实地表达了;然后让助手写最少代码让测试通过;测试通过后,再检查代码结构,做必要重构。这个循环每跑一次,就完成一次“规则确认”。红灯是确认测试有效,绿灯是确认实现满足规则,重构是确认结构不会腐烂。 需要澄清:TDD 不等于测试工具,也不是 QA 的职责。它是一种开发方法,用可执行测试驱动出实现。测试在这里不是附属品,而是需求的另一种表达方式。 ## 03、为什么 为什么在 AI 写码时代还要强调 TDD?因为自动编程工具没有可执行反馈时,本质上仍然在猜代码是否正确。这句话听起来有点抽象,拆开讲:模型生成代码依据的是海量代码和自然语言中学习到的概率分布,它知道“取消订单”通常会检查状态,但它不知道你们项目里“已支付不能取消”这条具体规则,更不知道这条规则在支付回调、退款、人工客服等多个入口都必须一致。没有测试,模型只是在生成“看起来合理”的代码;有了测试,判断就从语言概率变成了机器结果。 测试是机器给出的通过或失败,没有灰色地带。这个反馈对自动编程工具尤其重要。人可以边写边在脑子里运行一些场景,模型不行,它不会自己执行代码,也不会自动发现边界条件。只有测试运行器告诉它哪里红了,它才能在下一轮调整。换句话说,测试把“像不像正确”变成了“是不是正确”。 订单取消的例子特别典型。我们先写“已支付订单不能取消”的测试,运行后失败,说明测试真的在约束行为。然后让编程助手写最少代码,可能就是在取消函数里加一个状态判断,抛出一个业务异常。再跑测试,通过。这一瞬间,我们不再靠肉眼判断代码是否正确,而是有了一条机器可重复验证的规则。后续无论怎么重构,只要这条测试还绿,规则就没有被破坏。 TDD 还解决了一个协作问题:测试用例就是可执行的需求文档。你不需要反复用自然语言解释“已支付订单不能取消”,因为测试代码已经把这条规则钉死了。新成员或自动编程助手接手时,先跑测试就能理解边界。 ## 04、架构 从架构角度看,TDD 反馈环可以分为三层:规则层、实现层、反馈层。规则层由测试用例组成,表达业务约束,比如“已支付订单不能取消”。实现层是具体业务代码,比如订单取消服务。反馈层是测试运行器,它把规则层和实现层连接起来,输出红灯或绿灯。重构则是在三层之外加了一个守护:每次重构后,反馈层必须仍然是绿灯。 在 WorkBuddy 里,这个架构可以落成一条清晰的链路:先由需求生成规则层测试,再由测试驱动实现层代码,最后由反馈层自动运行全量测试。这个过程不依赖某个人记得所有细节,也不依赖口头交接。 这里有一个关键设计:测试应该绑定业务行为,而不是绑定实现细节。如果测试只通过公共接口验证结果,实现层就可以自由重构;如果测试频繁检查内部方法是否被调用、私有字段是否被修改,那么每次实现调整都会让测试变红,导致重构变成灾难。比如订单取消测试,比较好的做法是调用取消接口,验证订单状态和异常;而不是去断言内部一定调用了风控接口或库存接口。前者是行为验证,后者是实现绑定。 架构上还要注意反馈速度。测试越快,循环越短,自动编程助手迭代越高效。因此单元测试和轻量级集成测试优先,慢吞吞的端到端测试可以放到后续阶段。稳定、快速、可自动运行,这才是真正的反馈环。 ## 05、实战 下面用一个 Python 小例子走完整流程。需求只有一条:已支付订单不能取消。先写失败测试: ```python import pytest from order import Order, OrderStatus, OrderCancelError def test_paid_order_cannot_be_cancelled(): order = Order(id='ORD-1001', status=OrderStatus.PAID) with pytest.raises(OrderCancelError): order.cancel() ``` 这段测试在 order 模块还没实现时运行,会失败:可能是 ImportError 或 AttributeError。这就是红灯。接着写最少代码让测试通过: ```python class Order: def __init__(self, id: str, status: OrderStatus): self.id = id self.status = status def cancel(self): if self.status == OrderStatus.PAID: raise OrderCancelError('已支付订单不能取消') ``` 再跑测试,通过。绿灯达成。现在代码还可以,但规则直接散落在 cancel 里,后续可能有退款、风控等逻辑。我们做一次重构,把“能否取消”的判断抽出来: ```python class Order: def __init__(self, id: str, status: OrderStatus): self.id = id self.status = status @property def can_cancel(self): return self.status != OrderStatus.PAID def cancel(self): if not self.can_cancel: raise OrderCancelError('已支付订单不能取消') ``` 跑测试,仍然通过。这就是重构:结构变了,行为没变,测试保护了规则。接下来再加一条规则:待支付订单可以取消。先写失败测试: ```python def test_pending_order_can_be_cancelled(): order = Order(id='ORD-1002', status=OrderStatus.PENDING) order.cancel() assert order.status == OrderStatus.CANCELLED ``` 当前实现 cancel 只对已支付抛异常,但待支付订单调用后状态不会变成已取消,测试会失败。然后补充实现: ```python def cancel(self): if not self.can_cancel: raise OrderCancelError('已支付订单不能取消') self.status = OrderStatus.CANCELLED ``` 测试通过。这个循环很小,但完整展示了红、绿、重构。真正的好处不在这些小步里,而在于每一步都有机器反馈,不会出现“我以为可以了”的情况。 ## 06、洞见 为什么说 AI 时代 TDD 的价值被重新放大?因为自动编程工具比人更需要稳定、快速、可自动运行的反馈。人写代码时,会基于经验、上下文和直觉做很多隐含判断;模型没有这些,它只能从输入里获取信息。如果输入只有一句“实现订单取消”,模型就会按常见模式生成代码,至于你们项目里“已支付不能取消”的特殊规则,它猜不对也正常。测试就是把这些隐含判断外化出来,变成机器可读的约束。 另一个洞见:测试让自动编程工具从一次性生成变成可迭代优化。你不需要一次把需求说得很完美,只要先给出测试,模型就能根据失败信息调整实现。失败堆栈、断言错误,都是具体的信号,比“你再看看”有用得多。红灯、绿灯、重构,其实是一套适合人机协作的节拍。 但同时要警惕一个误区:测试如果过度绑定实现细节,会让每次重构都变成测试灾难。比如你写了一个测试,要求内部先调用风险检查,再调用库存锁定,最后更新状态。后续把风控改成异步,或者把库存锁定合并,测试就会连环失败。失败的原因不是业务规则被破坏,而是测试管得太细。这样的测试不但帮不上忙,反而会锁死实现,让重构寸步难行。好的测试应该像合同,只规定结果,不规定手段。 ## 07、行动 落到日常开发,我的建议是:规则明确的新功能优先 TDD,探索性原型不要机械套流程。具体可以这样做: 第一,动手前先问一句:这个功能的业务规则是否足够清楚?比如“已支付订单不能取消”,规则非常清楚,适合先写测试。如果是“做一个好看的订单详情页”,交互和视觉还在变,先写测试反而浪费。 第二,把规则翻译成失败测试,先看红灯。红灯不是形式主义,它是证明测试有效。如果测试不经任何修改就是绿的,很可能测试没有真正覆盖规则。 第三,写最少代码过绿灯,不做多余设计。不要顺手加一堆未来可能用到的扩展点,等测试逼出来再写。 第四,重构只在绿灯后进行。重构前先提交代码,重构后立即跑测试。如果测试红了,先回退或修正,不要让红灯过夜。 第五,探索性原型可以轻量 TDD。快速验证交互、性能、不确定性高的部分,等方向清晰后再补关键测试。探索阶段的目标是学习,不是永久的正确性。 第六,测试只绑定业务行为,不绑定实现细节。写完测试问自己:如果我把实现重写一遍,这个测试还会通过吗?如果不会,可能就绑得太死。订单取消测试只验证取消结果和异常,不关心内部调用顺序,这样以后换实现不用大改测试。 ## 08、小结 TDD 的核心理念不是“先写测试”,而是把开发变成一个有机器反馈的循环:红灯、绿灯、重构。在自动编程工具普及的今天,这个循环不但没有过时,反而更重要。因为没有可执行反馈时,再强的生成能力也只是在猜;测试能把判断从语言概率变成机器结果。订单取消的例子虽小,但它说明了规则如何被测试钉死、实现如何被最少代码驱动、结构如何被测试保护。规则明确的新功能优先 TDD,探索性原型保持轻量,这是我认为最适合当下的落地方式。 ## 09、链接与概念说明 TDD:测试驱动开发,用测试定义期望行为,再写实现使测试通过。 红灯-绿灯-重构:TDD 三步循环。红灯写失败测试,绿灯写最少代码通过,重构改善结构。 可执行反馈:测试运行器给出的通过或失败结果,是机器判断而非主观感觉。 回归测试:防止已有功能被修改破坏的自动化测试。 测试绑定实现细节:测试依赖内部方法、调用顺序或私有字段,导致实现调整时测试大量失败。 推荐阅读:Kent Beck《测试驱动开发》;Martin Fowler《重构:改善既有代码的设计》;Michael Feathers《修改代码的艺术》。

优秀的个人博客,低调大师

《WorkBuddy Skills 实战》第8招 修Bug先别猜

晚上十一点,告警群里突然跳出一条:订单服务间歇性 500,三分钟后自己恢复。你翻日志、看代码、改配置,折腾两小时还是没头绪。我是老李,今天想聊一件反直觉的事:很多时侯我们修不好 Bug,不是看得不够多,而是看得太早、猜得太快。尤其在智能助手普及之后,大家习惯把整个仓库丢进去,让它通读一遍再给结论。说实话,我踩过太多这种坑。真正可靠的调试,并不是先理解全部代码,而是先制造一个能稳定告诉你“错了”的信号。下面我把它拆成九个部分。 ## 01、痛点 偶发 500、CI flaky、性能回退,这三类问题最折磨人。它们有个共同点:现象时有时无,日志看不出所以然,测试跑一次绿一次红。传统做法是靠工程师经验,翻代码、猜路径、改几行然后重新部署看看效果。这个过程像蒙眼扔飞镖,偶尔命中,更多时候只是把问题掩盖得更深。后来大家开始借助自动化调试助手,把整个代码库和日志一股脑丢进去,让它通读一遍再给结论。结果更糟:助手能说出很多看似合理的猜测,甚至引用大段源码,但没有一条是被验证过的。很多人把这种输出当成了定位结论,直接照着改,上线后问题依旧。根因不是工具不聪明,而是我们省掉了最关键的环节:先建立起一个稳定的失败信号。没有这个信号,所有分析都是空中楼阁。 ## 02、是什么 diagnosing-bugs 不是某个黑盒功能,而是一套把调试变成纪律的流程,一共六步:复现 → 缩小范围 → 建假设 → 插桩 → 修复 → 回归。第一步复现,要求把线上或测试里的偶发问题,转化成一个能稳定失败的用例或脚本。如果做不到稳定复现,后面所有动作都缺少基准。第二步缩小范围,用二分法、版本对比、日志分流等手段,把问题从整个系统收敛到某个模块、某个函数,甚至某一行。第三步建假设,不是拍脑袋说“我猜是这里”,而是基于复现结果和观测数据,列出可能原因并按证据强弱排序。第四步插桩,在可疑路径上增加临时日志、计数器、断言,让程序自己暴露异常状态。第五步修复,只做与当前假设一致的最小改动,不顺手重构,不加无关防御代码。第六步回归,用测试、压测、灰度观察,确认修复有效且没有引入新问题。这套流程看起来平淡无奇,但它把调试从个人灵感变成了可复制、可审计的工程动作。 ## 03、为什么 很多辅助调试失败,是因为一开始就读大量代码然后猜答案。这背后缺的是一个能稳定变红的反馈信号。调试的本质是控制系统:你需要一个误差信号来指导下一步动作。测试先行的方法早就证明了这一点:先写一个必失败的测试,看到红灯,再写实现,看到绿灯。红灯就是你的反馈信号。如果没有红灯,你改任何代码都无法判断自己离问题更近还是更远。偶发 500 之所以难,是因为红灯忽明忽暗,信号不稳定;CI flaky 类似,测试结果本身就是噪声;性能回退则往往缺少明确的红线阈值。可靠调试的第一性原理,是先制造一个能稳定告诉你“错了”的系统。这个系统可能是一个失败测试、一段压测脚本、一个监控告警规则,甚至是一组断点条件。一旦有了它,你的每次修改都有明确的裁判。医生看病不会一上来把整本解剖学背一遍再猜病,而是先量体温、验血、拍片,拿到异常指标后再做判断。调试也应该一样:先让问题稳定变红,再谈修复。 ## 04、架构 把这套纪律抽象成系统,可以分成六层。最底层是信号层,包含测试、断言、监控指标、日志。它的职责只有一个:判断当前状态是对还是错,输出清晰的二值信号。没有信号,上层全部停摆。第二层是范围层,包括代码模块、调用链、版本差异、部署环境。它的任务是把搜索空间从整个系统逐步缩小到可疑单元。第三层是假设层,基于信号层的数据生成候选原因,并按证据强弱排序。假设不是越多越好,而是要可证伪。第四层是插桩层,在范围层划定的路径上增加临时观测点,把内部状态暴露出来。插桩要克制,只为验证当前假设服务。第五层是修复层,只做最小变更,保持与假设一致。第六层是回归层,用自动化测试、基准测试、灰度发布形成闭环,确保修复不会破坏其他部分。这六层形成一条反馈回路:信号变红 → 缩小范围 → 提出假设 → 插桩验证 → 最小修复 → 回归变绿。任何一步如果无法给出明确信号,就退回到上一步继续收敛。好的调试架构不是消灭问题,而是让问题无法隐藏。 ## 05、实战 讲三个真实场景。第一个是线上偶发 500。某天订单服务偶尔返回 500,三分钟后恢复。第一步不要急着看代码,先查监控和日志,确定错误集中出现的时间段、接口路径和堆栈信息。然后写一个最小复现脚本:用本地起同样服务,模拟相同请求参数和并发,直到稳定出现 500。这一步最难也最值得。复现成功后,用二分法缩小范围:对比最近发布版本,回滚可疑提交,或注释掉部分中间件,最终定位到一个连接池获取超时。建立假设:高并发下连接池耗尽且等待超时设置过短。插桩验证:在连接池获取前后打印等待时间和可用连接数,果然在复现时可用连接数归零。修复:把连接池上限和超时时间调整到合理值。回归:重跑压测脚本,错误消失,P99 延迟下降。第二个是 CI flaky。某个测试用例有时绿有时红,团队习惯点重试。正确做法是禁止直接重试,先记录失败时的运行顺序、时间戳和机器资源。把该用例单独抽出来跑一百次,配合全局变量检查,发现两个用例共享了静态状态,导致顺序依赖。写一个最小失败用例固定顺序,修复后增加隔离断言。第三个是性能回退。新版本上线后 P99 延迟上升 20%。用基准脚本固定 QPS,对比两个版本的耗时分布。缩小到某次构建后,用火焰图或耗时打点插桩,定位到一处新增的同步远程调用。修复改为异步,回归基准测试,延迟回到基线。可以看到三个场景路径完全一致:先复现,再缩小,建假设,插桩验证,最小修复,最后回归。 ## 06、洞见 调试最重要的不是“猜到答案”,而是先制造一个能告诉你“错了”的系统。这句话值得反复说。我们太习惯用“我猜是这里的问题”来开始修复,但猜中与否没有客观反馈,最终只能靠上线后的用户行为来验证,代价太高。一旦你有了稳定的红灯,调试就从开环猜测变成闭环控制:改一点,看红灯是否变化;红灯变绿,说明方向对了;红灯不变,说明还没碰到根因。这个红灯可以是失败测试,可以是监控告警,可以是压测脚本,甚至可以是一个简单的打印语句。关键不是形式,而是稳定。很多资深工程师在动手改代码前,总会先写一个能失败的测试,或者先用最小脚本重现问题。他们不是在浪费时间,而是在建立调试的坐标系。没有坐标系,再聪明的分析也只是空中楼阁。 ## 07、行动 第一,遇到复杂 Bug,第一问从“哪里错了”改成“怎么稳定复现”。第二,如果连问题都无法稳定复现,不要急着改代码,先继续收集日志、监控、环境差异。第三,用最小测试或脚本把问题变成红灯。第四,缩小范围时用二分法,不要大范围乱看代码。第五,建立假设清单,按证据强弱排序,优先验证最强假设。第六,插桩要克制,每个观测点都要服务于当前假设,避免信息过载。第七,修复后必须回归,跑测试、压测、灰度,别相信“应该没问题”。第八,团队层面建立模板:每个 Bug 报告必须包含复现步骤、期望结果、实际结果。这八条可以今天就开始执行。 ## 08、小结 调试不是阅读比赛,也不是猜谜游戏。可靠的调试是纪律化的反馈循环:复现 → 缩小范围 → 建假设 → 插桩 → 修复 → 回归。它的起点永远是一个稳定的红色信号。把“我猜”改成“我能证明”,把偶发变成稳定,把焦虑变成流程。下次再遇到那个半夜偶发 500,先别急着翻代码,先问自己:我有没有一个能稳定变红的测试? ## 09、链接与概念说明 红绿重构:先写一个会失败的测试,看到红灯,再写实现让它通过,看到绿灯。这是调试信号思想的最小实现。变异测试:故意在代码里注入小错误,看测试能否捕捉到,用来评估测试质量。属性测试:不只校验一组固定输入输出,而是用随机数据验证程序应满足的不变式。混沌工程:主动在生产或类生产环境制造故障,验证系统韧性与可观测性。可观测性:日志、指标、追踪三支柱,帮助建立红绿信号。二分定位:通过版本、代码、负载条件逐步对半缩小搜索范围。回归测试:防止修复引入新问题,是闭环的最后一环。这些概念与本文的调试纪律互相咬合:红绿重构和属性测试帮助你制造稳定失败信号;可观测性帮助你在线上发现问题;二分定位加速缩小范围;回归测试守住修复;混沌工程则把偶发问题提前逼出来。

优秀的个人博客,低调大师

《WorkBuddy Skills 实战》第9招 PR评论批量处理

## 01、痛点 你有没有经历过这样的场景:一个功能本身不大,PR 提上去之后,Reviewer 的评论却像撒了一把豆子,命名、异常处理、测试覆盖、架构边界全都有。你从上往下读,读到第五条时已经忘了第一条在哪个文件;你切到那个文件改两行,又得切到另一个测试文件补断言;中间还要回两条讨论,再切回来看原来的逻辑。真正改代码的时间可能不到半小时,但来回跳转和重新理解上下文却耗掉一整天。 我是老李。最近我们组一个支付模块的 PR 就撞上了这件事。改动本身只是调整手续费计算,结果 Review 意见拉出来有 14 条,分散在 6 个文件里。有同事说 fee 这个变量名表意不清;有同事说 catch 住异常后不能只打日志;有同事说缺少边界值测试;还有两条在讨论业务校验到底该放在 Service 还是 Controller。我一开始也是逐条处理,结果改到后面发现两条意见其实是冲突的,前面已经按其中一条改了,后面又得返工。 为什么现在要讲这个?因为 PR 高频的团队越来越多,Review 意见一多,最贵的不是改代码,而是不断在文件、意见和上下文之间切换。我们需要一套方法,先把散落的评论收拢、归类,再集中处理修改。 ## 02、是什么 gh-address-comments 就是用来读取 PR Review 评论、归类问题,再集中处理修改的工具。注意它的定位:不是自动回复机器人,也不是机械执行每一条 Reviewer 意见的执行器。它做的事情,是把当前 PR 里的 unresolved comments 拉下来,按问题类型分成几类,形成一张修改清单。 比如前面那 14 条意见,它会分成:命名与可读性、异常处理、测试覆盖、架构边界、文档一致性、其他。分类之后,你看到的不是一条条散落在文件里的评论,而是一个结构化的列表:哪个文件、哪一行、什么问题、建议动作是什么、优先级大概多高。这样你从读 14 条分散评论,变成看一张清单。 这里要特别强调:它解决的是整理问题,不是判断问题。它会告诉你有哪些问题、分别是什么类型、建议怎么改,但最终改不改、怎么改,仍然需要人来决定。 ## 03、为什么 为什么说这种做法适合现在的研发节奏?因为 AI 和自动化工具最擅长处理的是大量分散反馈的上下文整合,而不是机械执行每一条 Reviewer 意见。 Review 评论天然是碎片化的。同一条原则,可能在一个文件里被说成异常要包装,在另一个文件里被说成不要吞异常;同一个架构问题,可能有人在 Service 层提一句,有人在 Controller 层提一句。人如果逐条读、逐条改,很容易只见树木不见森林。工具先把评论拉平、归类以后,你才能看到这些意见之间的关联、重复和冲突。 举一个例子:一个 PR 里同时出现建议把 DTO 校验放到 Controller 和建议把业务校验放到 Service。如果分开看,你会改两处;但如果归到架构边界这一类里一起看,会发现它们其实在讨论同一条边界,只需要统一一个原则,再改一处即可。这种合并同类项的收益,远比帮你改一行变量名大得多。 另外,人脑的工作记忆是有限的。读第 10 条评论时,前 3 条的上下文可能已经模糊了。工具把评论分类后,你一次只需要关注一个类别,比如先处理所有命名问题,再处理所有异常处理问题。这样上下文切换的次数会明显下降。 ## 04、架构 从实现角度看,这个工具的整体链路可以分成四段:取数、过滤、归类、输出。 取数阶段,它通过 GitHub CLI 或 REST API 拿到当前 PR 的 Review Comments。这里关键是只取 Review Comments,而不是 Issue Comments,因为 Review Comments 是绑在代码行上的,Issue Comments 更多是讨论区里的总评。取数之后做一次过滤,只保留未解决状态的评论,已经解决或过期的先放一边。 归类阶段是整个工具的核心。它可以按预先定义的规则来分,也可以结合语义模型来判断。常见的分类维度包括:命名与可读性、异常处理、测试覆盖、架构边界、性能、安全、文档一致性、重复代码等。分类时还会保留原始上下文,比如文件路径、行号、评论内容、评论人、时间。 输出阶段生成一份修改清单,格式通常是 Markdown 表格或 JSON。清单里每一项至少包含:类别、文件、行号、意见摘要、建议动作、优先级。有的工具还会做一步冲突检测:如果两条意见在语义上矛盾,会在清单里标出来,提醒开发者不要直接同时执行。 再往后才是执行环节:开发者按清单逐项处理,每处理完一类就跑对应测试,最后回填评论。这个环节工具不替你决定,只负责把信息整理得足够清楚。 ## 05、实战 说回我们组那个支付模块的 PR。我的做法是让 WorkBuddy 拉取当前 PR 的 unresolved comments,生成修改清单。 第一步,确认本地 gh 已经登录,并且当前分支关联到远端 PR。然后运行 gh-address-comments,让它读取 PR 编号。几秒钟后,输出一张清单。我拿到的是这样的结构: - 命名与可读性:3 条,涉及 fee、amount、handler 命名; - 异常处理:2 条,涉及手续费计算失败时不能吞异常; - 测试覆盖:4 条,缺少边界值、超额退款、并发调用三个用例; - 架构边界:2 条,校验逻辑放在 Service 还是 Controller 有分歧; - 文档一致性:1 条,接口文档字段说明和代码不一致; - 其他:2 条,代码风格和日志级别。 我没有从第一条开始改,而是先处理命名和文档一致性,因为这两类影响面小,改完不会牵动业务逻辑。改完后跑一遍相关模块的单元测试,确认没有挂。接着处理异常处理,把原来 catch 后只打日志的逻辑改成包装成业务异常再抛出,同时补了两个失败场景的测试。到这里,测试类意见其实已经顺带覆盖了一部分。 最后才处理架构边界。原因是这两条意见有分歧,需要和 Reviewer 确认。我看了清单里的原始评论,发现一个同事建议把校验放 Controller,另一个建议放 Service。因为这次改动是手续费计算,校验必须靠近资金逻辑,我选择放在 Service,并在 PR 里回复了原因,同时把 Controller 的校验删除。这样既不是盲目执行,也没有留下 unresolved。 整个 PR 改完只花了一个下午,比之前逐条处理快了不少。最关键的是,中间没有再反复跳文件找上下文。 ## 06、洞见 这个工具真正省下来的,不是改一行代码本身的时间,而是阅读、分类、上下文切换和验证成本。 改一行代码可能只要几十秒,但知道该改哪一行、为什么这么改、改了会不会影响别的模块,才是真正耗时的地方。十几条 Review 评论如果散在 6 个文件里,你光是把它们全部读一遍并理解彼此关系,可能就要花掉半小时。分类之后,同类问题一起看、一起改、一起测,验证成本也会下降。 还有一个容易被忽略的点:Reviewer 评论不是绝对指令。它们有时是偏好,有时是误读,有时两条意见互相矛盾。工具如果被当成自动执行器,反而会放大错误。正确的用法是把它当成整理器,把信息归置清楚以后,技术判断仍然留给开发者。比如前面说的架构边界,如果直接两条都改,代码会变得很怪。 所以评价一个 PR 修改流程好不好,不要只看改了多少行,要看开发者在理解问题和来回切换上花了多少时间。这类工具的意义,是帮你把认知负担降下来,而不是替你写代码。 ## 07、行动 如果你的团队 PR 频率高,Review 评论经常超过十条,或者一个 PR 经常要来回好几轮,我建议优先安装 gh-address-comments 试一试。 具体可以这样做: 第一,先统计一下最近两周 PR 的平均评论数和 unresolved 比例。如果平均每个 PR 超过 8 条评论,或者 unresolved 占比超过三成,就很值得用。 第二,安装 gh-address-comments。先在一个小 PR 或个人分支上跑通,别一上来就全团队推广。确认它的分类结果和你们项目的实际关注点是否吻合。 第三,根据项目特点自定义分类关键词。比如你们关注事务、幂等、DTO、审计日志,就把这些词加进分类规则。这样清单会更贴近真实工作。 第四,把生成的清单纳入 PR 修改流程,但保留人工确认。不要设置成自动提交或自动标记已解决,因为技术判断必须由人来做。 第五,试用两周后对比一下:PR 的完成时长、Review 轮次、遗漏问题数量有没有变化。如果确实有改善,再在团队内推广。 ## 08、小结 PR 评论一多,最怕的不是意见多,而是上下文乱。gh-address-comments 这类工具的价值,是先把散落的 unresolved comments 拉下来,按命名、异常、测试、架构边界等维度归类,形成一张修改清单。你不再需要从第一条机械改到最后一条,而是可以一类一类处理,每改完一类就测试验证。工具帮你省阅读、分类、切换和验证的成本,但技术判断仍然要留在自己手里。对于 PR 高频团队,这种整理能力比自动改代码更实用。 ## 09、链接与概念说明 - GitHub CLI:https://cli.github.com/ - GitHub REST API - Pull Request Review Comments:https://docs.github.com/en/rest/pulls/comments - GitHub REST API - Pull Request Reviews:https://docs.github.com/en/rest/pulls/reviews - 概念:gh-address-comments,用于读取 PR Review 评论、归类问题并生成修改清单的工具。 - 概念:unresolved comments,指 Pull Request 中尚未标记为已解决的审查评论。 - 概念:修改清单,将散落的 Review 意见按类别、文件、优先级整理后的可执行列表。 - 概念:上下文切换成本,开发者在多个文件、多条意见之间来回切换时消耗的注意力和时间。 - 具体工具安装与用法请以官方仓库说明为准,不同团队的规则可以自定义。

优秀的个人博客,低调大师

《WorkBuddy Skills 实战》第15招 内容蒸馏成方法

不知道你有没有这种经历:一门讲架构的课程,从头到尾看完花了二十个小时,笔记也记了厚厚一沓,可到了真正要拍板“这里该同步还是异步”“这个存储该选 CP 还是 AP”的时候,脑子里跳出来的还是那几句零散的口诀,甚至干脆凭感觉。我是老李,这几年一直和团队做技术选型和系统设计,最近我逼着自己把过去收藏的课程和书籍重新翻了一遍,结果发现一个尴尬的事实:收藏夹越来越满,能直接帮我做判断的东西却越来越少。后来我换了一种处理方式,不再保存原文,而是把一门二十小时的架构课硬生生蒸馏成十几条决策规则。这件事让我重新理解了技术人知识管理的重点。今天正好展开聊聊。 ## 01、痛点 太多技术人把“学过”误认为“会做”。我们习惯的行为链路是:看到好课程先收藏,看到好文章先转发,看到好视频先放进稍后看。然后呢?没有然后。等你真正面对一个架构决策时,你不可能重新去看二十小时视频,也不可能把整本书翻一遍,你只会调用最容易被大脑提取的那一点印象。这个印象往往是零散的、情绪化的,甚至是被标题党污染的。 还有一个更隐蔽的问题:即使你去查询原文,原文也未必能直接给你答案。书和课程为了讲清楚来龙去脉,会花大量篇幅讲背景、讲演进、讲对比。但真实决策往往只需要一条边界条件:在什么情况下选 A,什么情况下选 B,什么代价可以接受。这些判断规则藏在内容的缝隙里,没有被提炼出来。于是你查得到内容,却查不到决策。 这不是说内容不重要,而是说内容没有被加工成可执行的形态。我们缺的不是更多资料,而是把资料变成判断依据的工序。尤其对架构师来说,决策窗口往往只有几分钟,你不可能在评审现场开始翻书。 ## 02、是什么 仓颉提炼法,简单说就是一句话:把书、视频、播客中的方法论蒸馏成可执行决策规则,而不是保留原文查询。它更偏向从内容里提取“什么时候用、怎么判断、怎么执行”的规则,而不是建立一套可以全文检索的资料库。 为什么叫“仓颉”?仓颉被传说是汉字的整理者,他把庞杂的符号系统归纳成可传播、可复用的字符。这里借这个意思,强调的是归纳和压缩。我们面对一堂二十小时的课程,不是要记住讲师的每一句话,而是要找到那些真正能指导行动的分岔口。 一条合格的决策规则通常包含五个部分:触发条件、判断依据、执行动作、反例和边界条件。比如“当系统调用链的 P95 延迟预算小于 200 毫秒,且下游支持幂等重试时,优先选择同步调用;否则引入消息队列做异步解耦”,这就是一条可以直接用的规则。它不像笔记那样告诉你“异步有很多好处”,而是直接告诉你什么时候别用异步,什么时候必须用异步。 这个方法和传统的目录式笔记、思维导图最大的区别在于:它不围绕内容结构组织,而是围绕决策场景组织。一本书的目录是按作者的逻辑展开的,而决策规则是按你未来可能遇到的问题展开的。前者帮助你理解,后者帮助你行动。 ## 03、为什么 为什么知识真正有价值的部分往往不是内容本身,而是“什么时候用、怎么判断、怎么执行”的规则?因为内容在没有场景之前只是信息,只有在特定场景下被调用,才变成知识。举例说,你知道“消息队列能削峰填谷”这句话,和你知道“当流量洪峰导致下游处理不过来,且允许短暂延迟时,可以在入口和下游之间加消息队列”,是两种完全不同的认知。前者是描述,后者是指令。 描述型知识的问题在于,它不告诉你什么时候用,也不告诉你用了以后要承担什么。你只能自己试错。而指令型知识的好处是,它把判断前置了,把代价也写出来了。对技术人来说,每次决策都是一次资源分配,时间、稳定性、人力都在里面。你越晚做出正确判断,成本越高。 这也是为什么光保存原文不够。原文可以提供描述,但描述到指令之间还隔着一层提炼。很多人以为大模型可以随时回答这些问题,但模型给你的往往是通用描述,而不是基于你项目上下文的判断。真正稀缺的是你自己的决策规则库,它嵌入了你的项目约束、团队能力和历史踩坑。 还有一个现实原因:技术节奏太快。课程和书籍的生产速度远赶不上工具和框架的变化,但决策原则的变化要慢得多。把一门二十小时架构课蒸馏成十几条决策规则,不是因为内容太多,而是因为真正能跨项目复用的判断原则,本来就没有想象中那么多。少而准,比多而杂更有价值。 ## 04、架构 要让这个蒸馏过程稳定工作,不能只靠灵感和耐心。我把它拆成四层,从下到上依次是:原料层、蒸馏层、规则层、调用层。 原料层负责存放原始内容,包括电子书、长视频、播客音频和课程讲义。这一层只做一件事:保留完整上下文,方便回查。它不直接参与日常决策,因为原始内容太慢、太散。 蒸馏层是核心加工环节。它的输入是原料层的内容,输出是规则候选。具体动作包括:标记内容中所有出现“选择”“取决于”“反例”“不适用”的地方;把作者表达的原则拆成条件和结论;把案例中的成功和失败分别归到正例和反例;最后补上该规则不适用的边界条件。这一层最重要的工作是过滤。不是每句话都能变成规则,有些内容只是过渡,有些只是观点,有些甚至是错的。 规则层存储已经成型的决策规则。每条规则保持短小,通常不超过一百字,但必须包含触发条件、判断依据、执行动作、反例和边界条件。规则之间可以有引用关系,比如“先看数据一致性要求,再选存储模型”,但每条规则必须能独立执行。 调用层负责在真实场景中把规则调出来。它可以是人工检索,也可以集成到内部工具里,在技术评审、方案设计时按场景推荐。最朴素的形式就是一张表格,按技术领域分类,例如“通信方式”“存储选型”“一致性策略”“容量规划”。关键不是工具多高级,而是规则能不能在几十秒内被找到并读懂。 需要注意的是,低质量内容如果进入蒸馏层,会产出低质量规则。所以原料层要有准入门槛:优先选择已经经过实践检验的书和课程,而不是追逐热点的零散内容。否则你只是把噪音变得更易调用。 ## 05、实战 拿一套二十小时的架构课程做例子。我选的是偏向分布式系统设计的课程,里面有大量关于同步异步、一致性、存储选型和容错的内容。传统做法是边看边记,最后得到一份几十页的笔记。但这次我换了一个目标:课程结束后,必须输出至少十条可以直接用于评审的决策规则。 第一步,通读时不记细节,只标记判断点。判断点是指讲师明确说“这里要选”“这里不能选”“我们当时踩过坑”的地方。二十小时课程里,这样的判断点大概有四十多处。 第二步,把每个判断点拆成规则骨架。比如课程里讲“同步调用适合低延迟链路,但会放大故障”,我先不管原话,而是问自己:什么条件下我会选择同步调用?答案是当调用链的 P95 延迟预算小于 200 毫秒,并且下游具备幂等重试能力。什么条件下选择异步?当链路延迟预算宽松,或者下游有突发流量需要削峰。于是得到第一条规则:当调用链 P95 延迟预算小于 200 毫秒且下游可重试时,优先同步;否则引入消息队列做异步解耦,同时为消息队列增加死信和监控。 第三步,补充反例和边界条件。课程中往往会讲到一些反例,比如金融支付链路里,不能因为想要低延迟就牺牲一致性。于是第二条规则:当操作涉及资金或关键状态变更时,一致性要求高于可用性,选择支持事务和强一致的方案;反例是日志采集链路,丢失少量日志可以接受,可选择异步和最终一致。 第四步,把课程里的案例归入规则。比如课程讲到某系统因同步调用导致雪崩,这就成为“同步调用不加超时和熔断”的反例。对应规则:任何远程调用必须设置超时和熔断,超时时间不超过调用链预算的三分之一。 第五步,合并和去重。课程中很多判断点其实在讲同一件事,只是换了个案例。比如“异步解耦”和“消息队列削峰”可以合并成一条:当流量存在明显峰值且下游处理能力有限时,在入口和下游之间引入消息队列,并设置积压告警和消费者限流。 第六步,把规则放到真实评审里试跑。我挑了两个正在进行的项目,把课程蒸馏出的十几条规则打印出来,在技术评审时逐条对照。结果发现其中两条规则因为公司内部组件限制无法落地,一条规则和现有运维体系冲突。于是我给这些规则标上“待验证”和“已适配”,并写清楚适用边界。 最终,二十小时课程沉淀出十四条决策规则。它们大多不超过一百字,但每一条都能直接回答一个具体的架构选择问题。这个过程最有价值的不是十四条规则本身,而是我以后再看类似内容时,会自动进入“这条能不能变成规则”的思维模式。 ## 06、洞见 这件事让我更确信一个变化:知识管理正在从“收藏内容”转向“提炼决策规则”。过去我们衡量一个人知识管理做得好不好,往往看他收藏了多少、读了多少、笔记有多少。但收藏和读过只是输入量,真正影响工作质量的是输出质量,是你在关键场景下能不能快速做出正确判断。 决策规则是比内容更高级的资产。内容可以被搜索到,但搜索到不等于想得到,想得到不等于用得好。规则则是把“搜索、判断、执行”压缩成了一条。你可以把规则库看成自己的外置判断系统,它不负责回答“世界是什么”,只负责回答“我该怎么办”。 但这里有一个必须警惕的陷阱:低质量内容如果被规则化,只会变成更容易调用的低质量知识。也就是说,蒸馏会放大内容的优缺点。一篇本来就肤浅的文章,做成规则后可能看起来很有操作性,实际害人不浅。所以蒸馏的前提是筛选,验证的前提是场景。没有经过真实项目检验的规则,不能进入个人规则库。 另一个洞见是,规则的多少并不值得炫耀。二十小时课程只提取出十几条规则,这恰恰说明真正可复用的判断原则是稀少的。那些动辄上百条的知识库,往往混入了大量未经筛选的摘要。少,意味着你真正理解并愿意负责。 ## 07、行动 如果你想立刻开始,可以分两步走。 第一步,处理长文查询。对于书和长课程,不要试图记住全部内容,而是建立“书到规则”的流程:先看目录,找到可能包含判断原则的章节;再快速标记判断点;最后输出规则卡片。每张卡片只写触发条件、判断依据、执行动作、反例和边界。遇到不确定的地方,回到原文核对,但最终留在库里的必须是规则,不是摘抄。 第二步,处理方法提炼。对于视频和播客,更适合用仓颉提炼法。因为这些内容的信息密度不均匀,但往往会在案例和问答里出现高质量判断。你可以在听的过程中暂停,把讲师说的“我们当时选择……因为……”改写成“当……时,优先……,但要避免……”。注意补上反例,反例是规则的免疫系统。 执行上建议先用两周时间做小规模试验:选一门已经学过的课程,重新提取规则,然后放到下一次技术评审中试用。记录每条规则被调用的次数、是否帮助你改变了决策、有没有出现不适用的情况。根据反馈淘汰和修改。 最后给自己定一个硬规则:任何一条规则进入个人库之前,必须经过一次真实场景验证或一次反例推演。没有验证的规则只是观点,不是资产。 ## 08、小结 技术人最大的浪费,不是学得不够多,而是学完之后没有留下可以调用的判断能力。把书、视频、播客中的方法论蒸馏成可执行决策规则,就是把一次性的学习体验变成长期的决策资产。它不追求记住更多,而追求在关键时刻判断得更快、更稳。 我们不需要成为移动的图书馆,而需要成为能快速做出正确选择的人。课程内容可以遗忘,但规则必须留下。低质量的东西不要蒸馏,蒸馏出来的规则必须验证。做到这两点,知识管理才算真正跨过了从知道到做到的鸿沟。 ## 09、链接与概念说明 本文涉及几个核心概念,在此统一说明。 仓颉提炼法:将书、视频、播客中的方法论蒸馏成可执行决策规则的工作方法,强调归纳和压缩,不保留原文查询。 决策规则包:由触发条件、判断依据、执行动作、反例和边界条件组成的最小知识单元。它面向决策场景,而不是面向内容结构。 原料层:书籍、视频、播客等原始内容的存储层,只作为蒸馏素材,不直接用于日常查询。 蒸馏层:对原始内容进行判断点标记、原则提取、案例归类、反例补充和边界条件确认的加工环节。 规则层:保存已经成型的决策规则,按技术领域分类,要求每条规则短小、独立、可验证。 调用层:在技术评审、方案设计等真实场景中快速找到并应用规则的入口,可以是人,也可以是内部工具。 场景验证:一条规则进入个人知识库前,必须在真实项目或反例推演中至少验证一次,确认其适用边界。 书到规则:面向书籍和长课程的结构化提取方式,以目录和判断点为入口,输出规则卡片而非原文摘抄。 低质量规则:由低质量内容蒸馏出的规则,看似可操作,但在真实场景中会放大错误判断,必须通过筛选和验证加以拦截。

资源下载

更多资源
优质分享App

优质分享App

近一个月的开发和优化,本站点的第一个app全新上线。该app采用极致压缩,本体才4.36MB。系统里面做了大量数据访问、缓存优化。方便用户在手机上查看文章。后续会推出HarmonyOS的适配版本。

腾讯云软件源

腾讯云软件源

为解决软件依赖安装时官方源访问速度慢的问题,腾讯云为一些软件搭建了缓存服务。您可以通过使用腾讯云软件源站来提升依赖包的安装速度。为了方便用户自由搭建服务架构,目前腾讯云软件源站支持公网访问和内网访问。

Nacos

Nacos

Nacos /nɑ:kəʊs/ 是 Dynamic Naming and Configuration Service 的首字母简称,一个易于构建 AI Agent 应用的动态服务发现、配置管理和AI智能体管理平台。Nacos 致力于帮助您发现、配置和管理微服务及AI智能体应用。Nacos 提供了一组简单易用的特性集,帮助您快速实现动态服务发现、服务配置、服务元数据、流量管理。Nacos 帮助您更敏捷和容易地构建、交付和管理微服务平台。

Sublime Text

Sublime Text

Sublime Text具有漂亮的用户界面和强大的功能,例如代码缩略图,Python的插件,代码段等。还可自定义键绑定,菜单和工具栏。Sublime Text 的主要功能包括:拼写检查,书签,完整的 Python API , Goto 功能,即时项目切换,多选择,多窗口等等。Sublime Text 是一个跨平台的编辑器,同时支持Windows、Linux、Mac OS X等操作系统。

用户登录
用户注册
修改密码
忘记密码