AI Rules 配置实战

.cursorrules、CLAUDE.md、Skills 是三种互补不是替代的配置格式。混用前必须搞清楚每种擅长什么、不擅长什么，否则就是把同一份规则写三遍——团队里没人维护得动。

如果还没动手写过，先看 Cursor Rules 入门 和 Claude Code Skills 实战 跑通基础。本章讲三种格式怎么分工、怎么在团队里同步。

三种格式的真实定位

关键区别：

• .cursorrules / CLAUDE.md 是默认 always-on context，写多了 token 就爆
• Skills 是懒加载，只在 AI 判断需要时才读，可以放很多 SOP 不污染 context
• .cursor/rules/*.mdc 介于两者之间，按 glob 匹配

内容怎么分

最常见的错误是把所有规则塞进 CLAUDE.md，导致它涨到 2000 行、每次会话烧 5K token。正确分法：

团队同步策略

规则只有 commit 进 git 才有意义。三个层级，三种处理：

# 1) 项目级 — 全部 commit
git add .cursorrules .cursor/rules/ CLAUDE.md
git commit -m "chore: update AI rules for new auth pattern"

# 2) 项目级 Skills — commit 进 .claude/skills/
git add .claude/skills/deploy-prod/
git commit -m "skill: add prod deploy SOP"

# 3) 用户级 — 不进 repo
# ~/.claude/CLAUDE.md 和 ~/.claude/skills/ 是个人偏好，不要 commit

.gitignore 通常加这两行：

# AI cache + 个人 settings 不进 repo
.claude/settings.local.json
.cursor/settings.local.json

# 但项目级规则必须 commit
# !.cursorrules
# !.cursor/rules/
# !CLAUDE.md
# !.claude/skills/

强制 review：CLAUDE.md / .cursorrules 的修改必须走 PR，不允许直接 push。这些文件影响每个工程师的 AI 行为，等同于改 lint config，需要团队达成共识。

真实例子：JR Academy 的分层

~/.claude/CLAUDE.md                         # 个人偏好 (50 行)
└─ "用 bun 不用 npm"
└─ "commit 后自动 push"
└─ Projects Registry

jr-academy-ai/CLAUDE.md                     # 项目铁律 (~600 行)
└─ ABSOLUTE RULES (rm 政策、git 安全)
└─ Service 架构 (600 行上限、单一职责)
└─ ID-First Principle (生产事故复盘)
└─ Anti-Template Content Rule
└─ MongoDB / Auth / Testing 约束

.cursor/rules/frontend.mdc                  # glob: *.tsx
└─ styled-components 规则
└─ z-index 约定

.claude/skills/bootcamp-sync/               # 复杂 SOP (~400 行)
└─ SKILL.md：从 curriculum/ 同步到 prod
└─ scripts/diff-check.ts
└─ templates/

.claude/skills/lesson-design/               # 复杂 SOP
└─ SKILL.md

效果：日常会话 context 大约 8K（CLAUDE.md），需要部署或同步时 AI 自动 trigger 对应 skill 加载额外 5-10K。比把所有内容塞 CLAUDE.md 节省 60% token。

常见踩坑

• 规则写得太抽象 - "代码要清晰可维护" 是废话，AI 用不上。要写成 "service 文件超过 600 行必须拆"
• 规则之间矛盾 - .cursorrules 写 "用 tab"，CLAUDE.md 写 "用 4 空格"，AI 行为不可预测。定期 audit
• Skills 触发条件不写清楚 - SKILL.md 的 description 写"帮助代码审查"，AI 永远不会主动用。要写"审查 PR 时自动触发，输入 PR diff，输出 5 类问题清单"
• 不更新规则 - 团队 6 个月前定的"用 React 17"，现在已经升 React 19，AI 还在按老规则写。每季度 audit 一次

下一步

• MCP 开发最佳实践 — 把 AI 工具能力扩展到外部系统
• AI 规则持续改进 — 规则的版本化和迭代
• Claude Code Context Management — 控制规则加载的 token 成本