1.2 项目指令文件膨胀——什么时候该拆分
引言
小王的项目指令文件从 50 行涨到了 300 行。
里面有项目技术栈、代码风格约定——这些确实每次都需要。但也有 API 规范文档、部署流程、代码审查清单——这些只有特定场景才用得上。
问题不是"要不要写"，而是"写在哪里"。
💡 本课程用 CLAUDE.md 作为代表
Claude Code 的 Skill 系统是最完整的，所以我们用它作为教学示例。但你学到的概念完全适用于其他工具——只需要把 CLAUDE.md 替换成你所用工具的等价物（.cursorrules、.windsurfrules 等）。
判断标准：事实 vs 流程
一条简单的分界线：
事实
**是什么**——永远成立的陈述
- 项目使用 Vue 3 + TypeScript - 测试框架是 Vitest - 金额用整数（分），禁止浮点数 - 所有 API 调用走 src/api/ 层
→ 写在 **项目指令文件**
流程
**怎么做**——特定场景的操作步骤
- 部署流程：测试 → 构建 → 部署 → 验证 - 修复 Issue：查看 → 定位 → 修分支 → 修代码 → 测试 → PR - 代码审查检查清单（8 个维度） - API 设计规范（REST + GraphQL 完整规则）
→ 写在 **技能包**
三个信号：你的项目指令文件该减肥了
信号一：你开始反复粘贴同样的话
小王发现，每次做代码审查，他都要粘贴一段 30 行的审查清单到聊天中。
这意味着：这段内容应该是技能包，而不是手动复制。
信号二：项目指令文件里出现了"步骤"
小王的项目指令文件里有这么一段：
## 部署步骤 1. 运行 npm run test 2. 运行 npm run build 3. 运行 npm run deploy:prod 4. 检查部署状态
这意味着：步骤是流程，不是事实。应该提取为 /deploy 技能包。
信号三：项目指令文件超过 100 行
经验表明，项目指令文件超过 100 行后就该警惕，超过 200 行后 AI 对其遵从度明显下降。就像一份 200 条规则的员工手册——没人能全记住。
项目指令文件行数标准：
- 推荐：50-100 行（最佳状态）
- 警告线：200 行（超过就该拆分）
- 理想目标：核心事实为主
注意：技能包主文件的标准不同，参见 2.2 结构与配置。
这意味着：把"偶尔需要"的内容移到技能包，项目指令文件只保留"始终需要"的核心。
小王的项目指令文件重构
重构前（300 行）：
项目指令文件（300 行）
├── 技术栈和约定（50 行）✓ 始终需要
├── 代码风格（30 行）✓ 始终需要
├── API 规范（120 行）✗ 偶尔需要
├── 部署流程（40 行）✗ 偶尔需要
└── 代码审查清单（60 行）✗ 偶尔需要重构后（80 行）：
项目指令文件（80 行）
├── 技术栈和约定（50 行）✓
├── 代码风格（30 行）✓
└── 指向技能包的链接：
- API 规范 → /api-guide
- 部署 → /deploy
- 审查 → /review
技能包/
├── api-guide/ ← 120 行，按需加载
├── deploy/ ← 40 行，按需加载
└── review/ ← 60 行，按需加载Token 节省：每次会话从 ~6000 token 降到 ~1600 token，节省 73%。
更多的"什么时候用技能包"
| 场景 | 用项目指令文件 | 用技能包 |
|---|---|---|
| 项目技术栈 | ✅ | |
| 代码风格约定 | ✅ | |
| 禁止操作列表 | ✅ | |
| 部署工作流 | ✅ | |
| API 设计规范 | ✅ | |
| 代码审查清单 | ✅ | |
| Issue 修复流程 | ✅ | |
| 测试运行约定 | ✅ | |
| 框架特定知识 | ✅ | |
| 项目状态仪表盘 | ✅ |
💡 一个简单的记忆法
每次都要 AI 知道的 → 项目指令文件（像工位上的便签贴） 特定场景才需要的 → 技能包（像抽屉里的参考手册）
本节小结
📌 本节核心要点
- 判断标准：事实（是什么）→ 项目指令文件，流程（怎么做）→ 技能包
- 三个信号：反复粘贴、出现步骤、超过 200 行
- 重构效果：小王的项目指令文件从 300 行降到 80 行，token 节省 73%
- 记忆法：项目指令文件 = 工位便签，技能包 = 抽屉里的参考手册
思考题
- 检查你当前的项目指令文件，其中有多少内容是"流程"而非"事实"？挑出一处，如果改成技能包你会怎么设计？
- 有没有一种内容，既不是纯"事实"也不是纯"流程"，而是介于两者之间？你会怎么处理？
- 如果你的项目指令文件只有 20 行，你觉得最不能省略的 3 条是什么？
下一节预告
知道了"什么时候用技能包"，下一节我们深入技能包的设计哲学——渐进式披露。这个来自人机交互的概念，为什么是技能包系统的哲学基础？