面对 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 结对编程：

markdown 复制代码

我现在需要对仓库进行 Node.js 版本升级。你需要进行以下步骤：
1. 更新 .nvmrc 文件，将版本号设为 24
2. 更新 bitbucket-pipelines.yml 文件，将 Node.js 镜像的版本设为 24
3. 更新完成后，重新安装依赖。并使用 pnpm audit 修复 high 以上的漏洞
4. 运行单元测试，确保所有测试用例通过

使用 Plan 模式让 Agent 先整理出一份计划，之后再让 Agent 执行。经过多轮的对话调整，直到这个仓库的升级彻底完成并符合期望。

此时，我们就得到了一个成功的"打样"模板。接下来，我们可以让 Agent 总结刚才的整个升级流程：

markdown 复制代码

我需要你把升级 Node.js 24 的步骤和解决方案整理成一份 guideline markdown 文件，存放到 /example/node-upgrade-24.md

1. 请使用简体中文语言
2. 文档采用 Skill / Agent Instruction 结构，而非普通人类教程。面向 AI

这样就能得到一份格式类似于 SKILL 的 Guideline 文件。为了让大家有更直观的感受，这份生成的 node-upgrade-24.md 大致长这样：

markdown 复制代码

# 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 文件即可：

markdown 复制代码

请参考 /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），或许才是真正能帮我们早点下班的利器。希望这个小技巧对你有所启发！

欢迎关注同名公众号：此方的手账

不止技术。科技新闻解析、编程语言史、大厂史、世界简史正在连载中。

希望成为让你了解一些奇怪知识的电子榨菜和厕所读物。