面对 300+ 仓库的重复劳动，我用 Guideline 优化了 Vibe Coding 工作流
导语：Guideline 是我在工作中总结出针对单次重复工作的 Vibe Coding 方式。可以简单理解为一种外置的临时 SKILL。
MCP、SKILL 已经是现在 Vibe Coding 的标配。MCP 用来解决 API 调用的问题；SKILL 用来规范具体的流程，在可复用的前提下保证每次产出的质量。这样的组合可以覆盖绝大多数场景，极大提高工作效率。
但针对单次重复性工作，SKILL 的定位就有些尴尬了。
单次重复性工作的定义
先来解释一下什么是单次重复性工作。这是我自己结合工作中实际场景总结出的定义。
我工作中的系统是基于 Node.js 的。因为历史原因，系统中有超过 300 个代码仓库，其中近 260 个是内部的私有依赖库（就是那种很小巧的私有库）。
每当遇到 Node.js LTS 版本升级、CVE 漏洞修复（依赖升级）、CI 中基础组件（DB、消息队列等）升级等需求时，中间的工作量简直让人头皮发麻。
而这类工作的工作流是无法被复用的。比如 Node.js 从 18 升级到 20 和从 20 升级到 24，API 的变化完全不同，需要针对性地做兼容处理。
像这类流程只能在单次工作中大量重复，却无法进行抽象和通用处理的工作，我称之为单次重复性工作。
轻量级的 Guideline 模式
针对单次重复性工作，我们面临一个“既要又要”的局面：因为重复性极高，我们需要一个类似 SKILL 的东西，让 Agent 可以按照固定的流程并行处理；但又因为工作流太过专一，未来几乎不会再用到，无论是做成项目级还是全局 SKILL 都不合适（比如 Node 24 中移除了 http_parser 模块，这只是这次升级特有的处理方式）。
面对这种需求，我想到了把工作流写到一个 Markdown 文件中，将流程外置化。在需要的时候，让 Agent 读取这个文件，并严格按照文件中的流程去处理。
因为带有指导和规范的性质，我称它为 Guideline。
为了更直观地理解，我们可以简单对比一下 SKILL 和 Guideline：
| 特性 | SKILL | Guideline |
|---|---|---|
| 复用性 | 高复用性，适合沉淀通用最佳实践 | 一次性使用，用完即走 |
| 作用域 | 全局或项目级生效，常驻可用 | 随用随建，针对单次任务 |
| 适用场景 | 覆盖日常开发中的绝大多数常规场景 | 适合单次高频、流程专一的特定任务 |
为什么不是脚本？
编写一个 Node/Shell 脚本以程序的方式其实局限性很大。对于固定文件的字符串替换（如 .nvmrc 文件的版本号、package.json 中的字段等）还算方便，但对动态或者不确定的内容处理就比较困难（比如找到 http_parser 引用的地方换成 pollyfill）。
反之使用 Agent，就不用操心动态或者更加复杂的内容，交给 Agent 处理就行。
编写脚本和使用 Agent 很类似“过程式”编程与“声明式”编程的区别。
Guideline 的实际应用
和 SKILL 一样，我们没法徒手搓 SKILL，自然也没法凭空编写 Guideline。
在实际处理时，我会先挑选一个最难啃的“骨头”（比如最核心或者最复杂的仓库）作为模板，一般这类仓库遇到的问题会最多。我会直接使用 Agent 工具（如 Cursor、Trae、OpenCode 等）进行一次完整的 Vibe Coding。
以升级 Node.js 24 为例，我会先针对这个仓库，一步一步与 Agent 结对编程：
我现在需要对仓库进行 Node.js 版本升级。你需要进行以下步骤：
1. 更新 .nvmrc 文件，将版本号设为 24
2. 更新 bitbucket-pipelines.yml 文件，将 Node.js 镜像的版本设为 24
3. 更新完成后，重新安装依赖。并使用 pnpm audit 修复 high 以上的漏洞
4. 运行单元测试，确保所有测试用例通过使用 Plan 模式让 Agent 先整理出一份计划，之后再让 Agent 执行。经过多轮的对话调整，直到这个仓库的升级彻底完成并符合期望。
此时，我们就得到了一个成功的“打样”模板。接下来，我们可以让 Agent 总结刚才的整个升级流程：
我需要你把升级 Node.js 24 的步骤和解决方案整理成一份 guideline markdown 文件，存放到 /example/node-upgrade-24.md
1. 请使用简体中文语言
2. 文档采用 Skill / Agent Instruction 结构，而非普通人类教程。面向 AI这样就能得到一份格式类似于 SKILL 的 Guideline 文件。为了让大家有更直观的感受，这份生成的 node-upgrade-24.md 大致长这样：
# Node.js 24 升级 Guideline
## Description
本指南用于指导 Agent 将 Node.js 项目升级至 v24，并处理相关的不兼容断点。
## Constraints
- 必须使用 pnpm 作为包管理器。
- 所有文件修改后，必须运行 `pnpm test` 确保无报错。
## Execution Steps
1. **基础配置更新**：修改 `.nvmrc` 和 CI 配置文件至 24 镜像。
2. **依赖重装与修复**：清理 `node_modules`，执行 `pnpm install` 和 `pnpm audit fix`。
3. **API 兼容处理**：
- 检查代码中是否引入了 `http_parser` 模块，若有，请替换为 `@http/parser` 方案。
- 检查 Buffer 的废弃用法并修正。
4. **验证**：运行单元测试。在使用上，它和 SKILL 一样简单，只要让 Agent 去读这个 Guideline 文件即可：
请参考 /example/node-upgrade-24.md 中的流程，对以下仓库升级 Node.js 24：
- Repo 1
- Repo 2
每个仓库都是独立的，因此可以开启多个 Subagent 并行处理。刚开始可以先挑选几个简单的仓库检查运行效果。如果有问题，及时微调 Guideline 文件。如此一来，借助 Guideline 配合多个 Subagent，一个人就可以轻松完成原来多人一周的工作量。简直是提效神器！
再思考一点
其实掰开了来看，所谓的 Guideline 就是一个需要时才指定的临时 SKILL。它既能让 Agent 按照标准流程去处理复杂逻辑，又不会像常驻 SKILL 那样在启动时占用不必要的 Token 上下文。
这与 Plan 模式出现前，我们将计划写在 Markdown 文件中让 AI 执行的思路如出一辙。这原本是为了规避模型上下文不足而使用的土办法，但在如今处理多仓库、单次高频的特定工作场景下，依然能发挥出奇效。
作为一个开发者，我们常常痴迷于寻找一劳永逸的“银弹”。但很多时候，面对庞杂的业务线，灵活变通的外置工作流（比如 Guideline），或许才是真正能帮我们早点下班的利器。希望这个小技巧对你有所启发！