适用读者：把规则塞进一个文件越写越长的人；要为一个团队定"AI 配置规范"的人。
前置：S24-J04、B03（提示词规则与配置）、J02（上下文与记忆）、S21-J02（Skills）。
覆盖旧文：3692（AGENTS.md 与配置）、3686（CLAUDE.md 配置与记忆）、3704（Cursor Rules）、3683（Slash Commands）、3689（Skills 技能封装）、3684（Hooks 自动化）、3687（Plugins 打包分发）、3697（沙箱审批与模型选择）、3698（Skills 可复用工作流）→ 9 篇 / 约 9 万字符。
扩展点：E-S24-018（七类资产的分层与生命周期表）、E-S24-019（一份跨工具可复用的规则骨架）、E-S24-020（写错的三种典型后果与判定方法）。
上一篇：S24-J04 · 三工具对照与 Vibe Coding 的正确起点
下一篇：S24-X02 · 教程章节登记。
1. 一句话结论
配置资产要按"变更频率 × 生效范围"分层：常变的（任务指令）别写进静态文件；全局的（安全红线）别塞进单个 Skills。写错层的后果是——要么规则永远不生效，要么一处改动波及所有任务。
出处：
A-3692（AGENTS.md）、A-3686（CLAUDE.md）、A-3704（Rules）、A-3689（Skills）、A-3684（Hooks）。
2. 七类资产的分层表（E-S24-018）
| 资产 | 作用域 | 生效方式 | 变更频率 | 类比 |
|---|---|---|---|---|
AGENTS.md / CLAUDE.md / .cursor/rules |
仓库/项目/用户 | 自动注入每轮上下文 | 低（月级） | 项目 README + 团队公约 |
| Skills | 任务族（可跨项目） | 按需加载（描述匹配时） | 中（周级） | 可复用的"操作手册" |
| Slash Commands | 用户手动触发 | 显式调用 | 中 | 快捷指令/脚本入口 |
| Hooks | 生命周期事件 | 事件触发（提交前/工具调用后等） | 低 | CI 钩子 / pre-commit |
| Plugins | 打包分发单元 | 安装即生效 | 低 | npm 包 |
| MCP Server | 外部能力 | 工具注册进上下文 | 中 | 驱动/适配器 |
| 任务提示词 | 单次会话 | 每次手写 | 高 | 一次性指令 |
判据："自动注入的东西必须短，按需加载的东西可以长"——静态文件每轮都占上下文，写 500 行等于每轮烧掉几千 token 且稀释指令（见 S19-J03 §2 的 KV Cache 前缀规则）。
3. 一份跨工具可复用的规则骨架（E-S24-019）
# 项目约定（约 60~80 行，超过就该拆到 Skills）
## 技术栈与版本
Java 17 / Spring Boot 3.3 / MyBatis 3.5 / MySQL 8.0 / Vue 3 + Vite 5
构建：Maven；测试：JUnit 5 + Testcontainers
## 目录与分层
src/main/java/<pkg>/{api,application,domain,infrastructure}
- api：只做协议转换与校验，禁止写业务规则
- domain：零框架依赖，不 import Spring 注解
- infrastructure：仓储实现、外部适配
## 命令（必须用这些，不要自创）
构建：mvn -q -DskipTests package
单测：mvn -q test
集成测：mvn -q verify -Pit（需 Docker）
格式化：mvn -q spotless:apply
## 硬约束（违反即回退）
- 不改数据库 schema；迁移只允许新增 V__*.sql
- 不改公共接口签名（api 包下的 DTO 字段只增不改）
- 不新增依赖，除非在 PR 描述里说明理由与体积影响
- 不打印任何密钥/令牌；.env 只读不写
- 破坏性命令（rm -rf / drop table）必须先征询
## 完成的标准
- 新增/修改的逻辑有对应测试，且全量测试通过
- 错误处理不吞异常：要么抛，要么记日志并给出可操作的提示
- 提交信息遵循 Conventional Commits
## 失败处理
信息不足时列出缺口并停止；不要猜字段名、不要编造 API。
三工具落地差异：
| 工具 | 落地文件 | 加载方式 |
|---|---|---|
| Codex | AGENTS.md（根目录，可嵌套子目录覆盖） |
自动，向上查找 |
| Claude Code | CLAUDE.md（项目根 / ~/.claude/CLAUDE.md 用户级） |
自动 |
| Cursor | .cursor/rules/*.mdc（含 globs 与 alwaysApply 元信息） |
按匹配或常驻 |
判据：同一份内容、三处软链或生成——手工维护三份必然漂移；用脚本从一份源生成（或放 docs/ai-conventions.md 再软链）。
4. Skills：把"长手册"从静态文件里搬出来（3689/3698）
触发：模型看到任务匹配 skill 描述 → 加载全文 → 按其中步骤执行
适合：多步骤、有判定树、有反例的专业流程（如"发布流程""数据库迁移评审"）
不适合：一句话规则（放静态文件）、一次性任务（直接写提示词）
| Skills 写法要点 | 说明 |
|---|---|
| 描述要"可匹配" | 写清触发场景关键词，否则永远不被加载 |
| 正文给判据而非清单 | "什么情况下用 A、什么情况下用 B" |
| 带反例 | 反例比正例更能约束行为（见 S19-J03 §7） |
| 引用而非复制 | 大段代码放 references/，正文给路径 |
| 可验证 | 每步给"怎么判断做对了" |
判据：Skills 的敌人是"过长导致的后半段被忽略"——把最关键的判据放最前，细节放 references/。
5. Hooks / Slash Commands / Plugins
| 资产 | 典型用法 | 边界 |
|---|---|---|
| Hooks | 提交前跑格式化与测试；工具调用后写审计日志；会话结束导出记录 | 不要在 hook 里做长任务（阻塞交互）；失败要能快速降级 |
| Slash Commands | /review（按团队清单审 diff）、/migrate（走迁移 SOP）、/release |
命令正文别写死路径与环境名 |
| Plugins | 把 Skills + Commands + Hooks 打成一包分发 | 需版本管理；升级要有兼容说明 |
| MCP Server | 接数据库/浏览器/内部系统 | 权限最小化：只读账号、白名单方法 |
沙箱与审批档位（3697 的重写）：
最严：每次工具调用人工确认（默认安全，但打断心流）
中：按操作类型分档（读文件/搜索放行；写文件确认；执行命令确认；网络访问确认）
最松：全放行（只应在隔离容器/一次性环境使用）
判据：审批档位应随「环境」而非「心情」切换——本地开发可中档，生产/共享环境必须最严。
6. 写错的三种典型后果（E-S24-020）
| 后果 | 表现 | 判定方法 |
|---|---|---|
| 不生效 | 规则写了但模型照旧违反 | 让模型复述"本项目的硬约束有哪些"——复述不出说明没加载 |
| 过度生效 | 一句针对某模块的规则污染所有任务 | 在无关任务里看它是否仍提及该模块 |
| 互相冲突 | 两个文件给出相反要求，模型随机选 | 搜关键词（如"禁止新增依赖"）看是否出现在多处 |
判定脚本（自查用）：
# 冲突检查：同一约束是否被多处定义
grep -rn "不新增依赖\|禁止新增依赖" AGENTS.md CLAUDE.md .cursor/rules/ .claude/skills/ 2>/dev/null
# 体积检查：静态文件行数（超过 120 行考虑拆分）
wc -l AGENTS.md CLAUDE.md .cursor/rules/*.mdc 2>/dev/null
判据："规则能不能被模型复述"是检验是否生效的最快办法；不能复述 = 没进上下文 = 等于没写。
7. 反例：六种"配置写了等于没写"
| 写法 | 问题 |
|---|---|
把 300 行规范全塞 AGENTS.md |
每轮烧 token，后半段被忽略 |
只在 CLAUDE.md 写规则，换工具就失效 |
未生成三份或未软链 |
| Skills 描述写成"帮助处理代码" | 描述不具体 → 永不匹配 |
| Hook 里跑全量集成测试 | 每次操作阻塞数分钟 |
Slash Command 写死 /home/alice/project |
换人即废 |
| 规则与 CI 配置不一致 | 模型按规则做、CI 按另一套拦，反复返工 |
8. 自测
- 七类资产的分层判据？为什么自动注入的必须短？
- Skills 适合与不适合什么？写法五要点？
- 沙箱三档与切换判据？
- 三种写错后果与各自判定方法？
- 怎么验证规则真的生效？
答案
- 变更频率×生效范围；自动注入每轮占上下文并稀释指令。
- 适合多步骤有判据的专业流程，不适合一句话规则；描述可匹配、给判据、带反例、引用大文件、可验证。
- 最严/分档/全放行；按环境而非心情。
- 不生效（复述法）、过度生效（无关任务观察）、冲突（关键词搜索）。
- 让模型复述硬约束，复述不出即未加载。
9. 下一篇
S24-X02 · 教程章节登记 —— MCP 集成、子代理、云端任务、四大模式等章节与现有 J01–J03/A01–A03 的对照结论，以及为什么这些章节不再单独成篇。
本篇属于系列《S24 · AI 编程工具》。旧文来源：A-3683–3698（9 篇章节）；扩展点 E-S24-018/019/020。工具版本按 2026-11 时点，具体命令以官方文档为准（待核）。