分享我维护代码质量的 Skill，给大家的 Vibe Coding 作品延年益寿

Vibe coding 很火，越来越多没有编程背景的人，靠着 AI 写出了能跑的 MVP。但“能跑”和”能活下去”之间，差着十万八千里。能从 MVP 成长为真正的产品，更是难上加难。

写到第十个功能的时候，野蛮声场的代码库多半已经变成一锅粥：

1. 文档到处都是，过时冲突；

2. 文件越来越大，到处复制粘贴；

3. 测试？什么是测试？能吃么？

其实解决这些问题并不难，软件工程发展几十年，经验技术都很成熟，只是很多 vibe coder 并不知道它们的存在而已。

所以我做了一个 Skill，把代码维护经验编码成 AI 可执行的标准流程。跟 Claude Code / Codex 说一声“时间差不多了，帮我维护一下”，它就会帮你把代码库整理一遍。

先说说什么是 Skill

Skill 就是一个 Markdown 文件，里面写着一套结构化的指令。 放到项目的 skills/ 目录下，Claude Code 就能自动识别并在合适的时候触发。比如这个 skill，当你说“维护”、“重构”，甚至”这个文件太大了”，它都会自动激活。

本质上，skill 是一种把专家经验文档化的方式——把 senior developer 的经验写成指令，让 AI 来执行。你可以把它理解成公司的业务规范，按照这个规范，大部分人的产出都能达到相当的高度，而不再依赖他们的经验与态度。

所以，大家不要对它期望过高：原来 AI 做不到的，现在一样做不到。但是，用好 Skill，可以让你的 AI 帮你做出更好的作品。

六个维护任务，以及为什么是这六个

这个 skill 包含六个独立的维护任务，可以全部执行，也可以挑着来。下面我逐个聊聊设计思路。

1. 清理文档

文档膨胀是慢性病，AI 辅助开发尤其严重——AI 很喜欢动不动就创建新 Markdown 来”记录”点什么。这个任务会扫描所有文档，判断哪些该合并、删除或更新。

有一点特别注意：AI agent 的指令文件不能动。 AGENTS.md、GEMINI.md、.github/copilot-instructions.md 这些文件看着像重复文档，但各服务不同的 AI 工具，绝对不能合并。

2. 沉淀知识到长期文档

为什么选了这个缓存策略？框架有什么坑？这些 know-how 通常散落在 commit message 和聊天记录里，三个月后就只能对着代码猜。

这个任务会 review 最近 30 条 commit，把值得沉淀的架构决策整理到长期文档中。原则：写给三个月后加入的新队友看。

3. 补充测试覆盖

测试是 vibe coding 项目最容易缺失的东西——你可能根本不知道该测什么。但我也不想搞”盲目 100% 覆盖率”。这个任务按优先级分了四层：

1. 工具函数和纯逻辑 → 目标 100%，因为这些最容易测，回报也最高

2. API 路由 → 目标 100%，每个接口都该有请求/响应测试

3. UI 组件 → 覆盖主要组件就行，不用每个按钮都测

4. E2E 冒烟测试 → 只跑关键路径，保证核心流程不挂

同时明确规定了什么不该测：不要测框架内部行为，不要写类型系统已经保证的测试，不要 mock 到只剩壳子。

4. 拆分大文件

300 行值得看一眼，500 行应该拆。300 行大概是不怎么滚动就能理解全文件的上限，500 行基本意味着混了多个关注点。

反向约束：内容内聚的文件即使超标也不该强拆。 把 300 行的内聚模块拆成 5 个碎片文件，理解成本反而更高。

5. 提取共享代码

DRY（Don’t Repeat Yourself）原则大家都知道，但什么时候该提取，什么时候不该，是需要经验的。

我的规则是：同样的逻辑出现 3 次以上才提取。 两次重复可能只是巧合，硬要抽象反而可能造成不必要的耦合。

另外还有个常见陷阱：不要搞”万能工具箱”。把所有提取出来的函数都塞进一个 utils.ts，跟没提取差不多。按领域分文件，保持每个模块的职责清晰。

6. 替换手写轮子

AI 很乐于帮你从零实现任何东西。你说”我要一个日期格式化函数”，它真的会手写一个——但这些轮子往往只覆盖了当时的 case，遇到时区、国际化就翻车。

这个任务会扫描手写轮子模式，建议换成成熟的库。Skill 里列了推荐表：echarts、@phosphor-icons/react、lodash-es、dayjs、zustand、clsx + tailwind-merge。

约束：不要为了一个函数引入一个库，尤其是要控制 bundle size 的场景。

一些贯穿全局的设计原则

经验告诉我们，有几个原则需要遵守：

1. 任务独立，可挑选执行。 全跑或只跑你关心的都行。全跑时顺序是优化过的——先清理文档再沉淀知识。

2. 每个任务都有”什么不该做”。 这可能是整个 skill 最重要的部分。AI 容易过度热心，不设边界会把没问题的代码也”优化”一遍。明确的负面约束让 AI 知道什么时候该收手。

3. 改完必须验证。 每个任务执行完都跑测试和类型检查。维护是让代码更好，不是制造新 bug。

为什么让 AI 来做这件事

代码维护重复性高、需要经验但不需要创造力——恰好是 AI 最擅长的领域。人类做维护最大的障碍不是能力而是意愿，谁愿意花一下午整理文档补测试？AI 不存在这个问题，它不会觉得无聊，不会省掉”看起来不重要”的步骤。

对 vibe coding 新手来说，这相当于请了个有经验的老手定期帮你检查代码库。你不需要知道该维护什么——skill 替你想好了。

AI 判断不是百分百准确，所以 skill 设计了确认机制：每个任务执行前先展示发现和计划，等你确认后才动手。你始终有最终决定权。

试试看

如果你在 Vibe coding，推荐你试试这个 skill：Skill 文件在 我的 GitHub 上开源，把 skills/code-maintenance/ 目录复制到你的项目里就行。下次跟 Claude 说”帮我 clean up 一下代码”，它就会自动触发。

如果你是有经验的开发者，我更鼓励你创建自己的 maintenance skill。每个团队的代码规范不同，技术栈不同，维护的侧重点也不同。把你自己的经验编码成 skill，不仅能帮自己，还能帮到团队里每个用 AI 写代码的人。

欢迎参考和改进。欢迎提出你的意见和想法，我们共同进步。