3M+ 行代码的 AI 项目，靠 skill 让 Agent 不瞎改

如果你正在用 AI 做正经项目，而且觉得自己还不够专业，我建议你读一读这篇。下面是我自己某个项目的 skill 结构截图。之前有人问过，我一直没腾出时间分享。

这篇会有点长，但如果你正在用 AI 做正经项目，会非常有用。

这个项目相当大。代码量超过 300 万行（不含依赖包）。是一个 monorepo，多语言，在不同服务器上跑着微服务，有大量 AI 处理流程，还有一个我自己微调过的小型 8B 模型。

项目规模不同，skill 数量会变，但 skill 的逻辑不变。

workflow skill 的数量不多。我更多是用 skill 而不是文档。因为 Codex 和 Claude 会自动把 skill 纳入上下文，把文档写成 skill 形式能带来很大好处。

软件的每个工作流和每个模块都有一个 skill。

agent 接到任务后，第一件事就是确定任务范围，然后读取与该范围相关的 skill。完成工作、通过测试后，如果需要，它会更新 skill；如果新增了模块或工作流，它会提醒我需要写新的 skill。这样一来，skill 也就是文档，始终保持最新。

因为 agent 在开始工作前会先读 skill，所以它知道自己要处理的代码的范围、功能、架构决策、当初为什么那样写、哪些东西不能改、哪些需要用户批准。

另一个重要的点是，在大型工作流和模块中，要把 skill 拆分。agent 读完 skill 后，应该能看到该领域下各子领域的文件引用，并且只读取与自己具体工作相关的子文件。这既节省 token，也有利于上下文管理。

图中是我的 audit skill 的文件夹内容。它会根据要审计的范围选择并读取子定义，然后据此分配任务。

全局 skill 里是我在每个项目中都会用到的工作流和规则，而像图中这种项目内 skill，则只包含该项目特有的内容。把两者分开非常重要，否则在不同项目中会造成大量混乱。

以后我会在 AGENTS.md / CLAUDE.md 里写。

注：图中涂黑的部分是因为写了我项目的名字，所以我把那些地方涂掉了。