为 AI 协作建立项目规则的实践

结构整理完了，然后呢

前几轮花了不少时间把项目从一锅乱炖理成了层次分明的样子：代码归代码，数据归数据，测试归测试，实验归实验。目录结构看起来已经像那么回事了。

但真正开始频繁地让 AI 参与日常工作之后，发现了一个新的问题：结构清楚，不等于 AI 知道该怎么在这个结构里干活。

你让它帮忙改个模型，它可能把新代码放到了实验目录里。你让它跑个验证，它可能把结果直接输出到了根目录。你让它做代码审查，它可能检查了一堆代码风格问题，却完全没注意到一个关键的目录边界已经被悄悄打破了。

这不是 AI 不够聪明。这是因为项目里那些"这个目录只放这种东西""改了这里至少要跑一下那个测试""实验代码不等于正式实现"之类的规则，全都装在人脑子里，从来没有被写下来过。

用 AGENTS.md 把隐性规则写成显性约定

于是这一轮做的第一件事，就是在项目根目录放一份 AGENTS.md。

这个文件的定位很明确：它不是给人看的项目说明（那是 README.md 的事），而是给 AI agent 看的协作规则。里面写的是：各个顶层目录各自放什么、改了核心代码至少要做什么验证、输出产物该落到哪里、优先用哪个命令行入口。

写完根目录的 AGENTS.md，发现还不够。有些子目录有自己更严格的要求，但全塞在根目录的文件里会变得又长又杂。于是继续在几个关键位置加了局部的 AGENTS.md：

• 验证算例目录强调结构化报告、失败退出和输出目录归属
• 测试目录强调 fixture、baseline 和测试分层
• 核心装配模块强调内部分层边界和实验工作台与主线实现的区分
• 实验目录强调探索区不是正式实现入口，不要被误当主线引用

这些局部文件不重复根级规则，只补充本目录特有的约束。最终形成的是一个分层体系：根级 AGENTS.md 管全局协议，局部 AGENTS.md 管各自的细节。AI 在任何一个目录里工作时，两层规则都能看到。

代码审查：从临时 prompt 到可复用的 skill

AGENTS.md 解决了"在哪里干活"的问题，但还有一个高频场景没覆盖：代码审查。

以前的做法是每次需要审查时，临时给 AI 写一段 prompt，告诉它关注什么。问题是每次都要重新描述一遍，很容易漏掉某些该关注的维度。而且不同类型的改动，该审查的重点完全不同。

这次的做法是把审查流程做成 skill——一种可以反复调用的、带有明确规则和输出格式的工作流模板。而且拆成了两层：

通用层做了一个风险导向的 code review skill，负责所有项目都需要关注的基本风险：行为有没有被意外改变、有没有破坏性操作、失败了会不会留下脏状态、有没有不小心提交了敏感信息。它的定位是 commit 前手动触发、面向本轮 diff 做 findings-first 的输出。

项目专用层则根据这个项目最容易出问题的方向，拆成了三个独立的 review skill：

第一个审查结构边界。前面费了那么大力气把目录理清楚，最怕的就是一次不小心的改动又把边界搞模糊了——新代码放错了层级，共享逻辑又被复制到了某个算例里，搬了文件但忘了更新 README.md 和 AGENTS.md。

第二个审查模型与计算后端的关系。这个项目有一套比较精细的分层：子系统模型负责描述物理行为，系统级后端负责组装和求解。这几层的职责不能混淆，自由度顺序、矩阵约定、符号推导和数值实现的对照关系也不能发生静默漂移。

第三个审查验证链路和产物管理。测试和算例是不是又混到一起了？输出是不是落到了正确的位置？baseline 和 fixture 是否显式存放？有没有哪个验证其实偷偷依赖了上次手动跑出来的结果？

这种两层结构比把所有审查规则塞进一个 skill 更稳妥。通用层可以跨项目复用，项目专用层只关心当前项目特有的风险。需要审查时按改动类型选择性触发，不用每次都跑全套。

Skill 放哪里：从 skills/ 到 .skills/

做完这些 skill 之后，项目目录里突然多了不少文件。它们不是主线代码，不是面向用户的文档，也不是数据——更像是一种开发辅助资产。

一开始建在项目的 skills/ 目录下，但总觉得不太对。打开项目根目录映入眼帘的是一堆审查规则模板，会让人以为这些是项目的核心内容。后来统一迁到了 .skills/。点开头的隐藏目录，存在但不碍眼，跟 .git、.venv 是一个思路。

同时还做了一个区分：只服务于当前项目的 review skill 放在项目内部的 .skills/ 里；而像阶段总结这种跨项目通用的工作流，则放在工作区根目录的 .skills/ 下面。项目级和工作区级各管各的。

阶段总结也做成了 skill

这一轮还顺手解决了一个一直存在但没正式处理过的问题：每轮工作结束后的阶段总结。

之前每次做完一轮工作，都会手写一份总结文档放到 docs/work-notes/ 里，记录做了什么、为什么这么做、还有什么没做完。习惯本身很好，但写法和格式完全看当时的心情，更关键的是这个过程从来没有被标准化过——全靠人记得要写。

这次在工作区根目录的 .skills/ 下建了一个会话总结 skill，把总结的生成流程也标准化了：默认输出到固定目录，用编号式命名，只有明确要求时才转写叙事性更强的复盘文章。规则里还特别强调了几条底线：不虚构没做过的事情，不把总结写成聊天记录的转录，要显式记录"讨论过但没做完"的问题。

这样做的意义在于：三个月后想回头查"当时为什么做了那个决定"时，有格式稳定、内容可靠的文档可以翻，而不是在一堆风格各异的笔记里大海捞针。

回过头看

这一轮做的事情，和前几轮性质很不一样。前几轮是在整理代码和目录结构——动的是项目本身。这一轮没有改动任何核心逻辑或模型实现，加的全是 AGENTS.md 和 .skills/ 里的东西——动的是"怎么跟 AI 协作"这一层。

如果说前几轮解决的是"这个项目长什么样"，这一轮解决的是"在这个项目里干活应该遵守什么规则、用什么流程"。从每次临时写 prompt 交代注意事项，变成写在仓库里、可以被版本管理的显式规则；从每次审查现场发挥，变成可以按类型触发的标准化 skill。

这些东西的价值不会立刻体现。不会因为多了几个 AGENTS.md，代码就突然变好了。但它们解决的是一个更长远的问题：当 AI 越来越频繁地参与项目工作时，你不可能每次都从头解释一遍"这个目录不能乱放东西""改了这里要跑那个验证"。这些东西必须被写下来，变成项目的一部分，跟着项目一起演进。

当然，写下来只是起步。这些 AGENTS.md 和 skill 到底好不好用、哪些过于繁琐需要简化、哪些还缺失需要补充——只有在实际使用中才能回答。就像前几轮整理得出的结论一样：不用追求一步到位，只需要保证这一轮比上一轮更清楚，就够了。