把项目约束写给 AI 读

当 AI 辅助开发成为日常，一个隐性问题开始浮现：每次新开一个会话，AI 对项目的认知就归零了。

你要么花十分钟重新解释架构，要么任由 AI 按照它「猜」的通用最佳实践出牌——结果往往是和项目实际规范南辕北辙的代码。

我踩过的弯路是：把所有约束写在 CLAUDE.md 里，然后越写越长，变成一份没人（没有 AI）认真读完的文档。

真正有用的做法是：写一份专门给 AI 读的结构化 Skill 文件，把项目的架构图、代码模式、测试规范、部署流程、关键约束打包成一个可复用的上下文单元。

一份 Guidelines Skill 应该包含什么

不是项目 README 的复制粘贴。README 是给人读的，逻辑是「介绍」；Guidelines Skill 是给 AI 在执行任务时实时参考的，逻辑是「约束」。

我认为一份 Guidelines Skill 应该包含五个部分：

1. 架构概览——服务拓扑图（ASCII 够用）+ 技术栈版本。目的是让 AI 在生成代码时选对 API，不要用 Next.js 14 的写法对付 Next.js 15 App Router。

2. 文件结构——重点目录的职责说明。AI 需要知道「新建一个 API 路由应该放在哪里」，而不是每次都要先 find 一遍目录树。

3. 代码模式——项目约定的响应格式、通用 Hook、服务层调用方式的代码片段。一份带注释的示例远比一段文字描述有效。

4. 测试规范——测试命令、覆盖率要求、fixture 结构。这部分经常被省略，结果 AI 写的测试用了错误的 mock 方式或测试运行器。

5. 关键约束——简短的硬规则列表，比如「不得在生产代码里使用 console.log」「不可变性原则，禁止 mutate 数组/对象」「输入校验必须用 Pydantic/Zod」。这些约束如果不明确写出来，AI 完全有可能出于「帮你优化」的好意绕过它们。

为什么结构化比长文档更有效

结构化的好处不只是「看起来整洁」。当 AI 需要参考「代码模式」时，它可以直接定位到对应章节，而不需要通读全文建立索引。这在长会话里对 token 消耗的影响是可观的。

另一个好处是可维护性。代码模式变了，只需要更新对应的代码片段。架构调整了，改一处架构图。每个部分职责单一，不会牵一发动全身。

落地时的几个取舍

粒度问题：一个大型项目可能有多个子系统，不建议把所有子系统塞进一个 Skill 文件。按服务拆分，每个服务一个 Skill，AI 在处理前端任务时加载前端 Skill，处理后端任务时加载后端 Skill。

代码示例的时效性：Skill 里的代码片段会过时。我的做法是只放「模式」级别的示例——展示调用方式和约定，而不是贴生产代码。模式的变化频率远低于具体实现。

关键约束的数量：超过 10 条就会开始失效，因为 AI（和人一样）对过长的约束列表会产生「扫描跳过」的行为。我的经验是 6-8 条，只放真正会被违反的约束。

谁来写 Skill：最好由真正在项目里跑通过一个完整功能的人来写第一版，然后在踩坑后更新。由不了解项目的人根据文档生成的 Skill 文件，往往缺少那些「不写也没人知道但写了就能少踩坑」的隐性约束。

一句话心法

给 AI 的上下文不是越全越好，而是越「可定位」越好——让它在需要某条约束时能直接找到，而不是在 2000 行文档里猜测它在哪里。