规则文件（AGENTS 类）设计与维护

一句话定义

规则文件是放在仓库里、每次 AI 会话自动注入的常驻指令（AGENTS.md/CLAUDE.md/.cursorrules 等），它用极小的 token 成本把「项目事实」与「行为红线」变成 AI 的默认上下文。

为什么重要

没有规则文件，每个会话你都要重复解释「用 pnpm、测试命令是 pytest、src/generated 不要碰」；有了规则文件，这些事实一次落盘、处处生效，且团队共享同一份 AI 行为基线。它是投入产出比最高的 AI 编程基础设施：30 行成本，换掉无数次重复纠正。

前置知识

kp-001（版图）、kp-004（注意力预算——规则文件占用常驻层预算，必须精炼）。

核心概念

• 常驻注入：会话启动时自动读入，不占你手动上下文包的份额（但占用窗口预算）。
• 内容金字塔（按优先级）：

1. 必守命令：构建、测试、lint 的精确命令；
2. 结构地图：一句话模块职责 + 「不许动」的路径；
3. 行为红线：禁止事项（禁引入依赖、禁改生成代码、禁提交密钥）；
4. 常见坑：本仓库特有的历史教训。

• 可执行性标准：每条规则必须能被「照做」或「验证」，否则删掉。

原理与机制

规则文件生效于注意力预算的常驻层：内容少而稳，每次会话都在窗口开头，模型对它的遵循度远高于对话中途的口头要求。这解释了两条设计推论：一是规则要短——整份文件越长，单条规则获得的注意力越低；二是红线要具体——「保持简洁」无法被遵循，「新依赖必须先在规则中登记」可以被遵循。规则文件应进版本库：它随代码演化，且是团队 AI 行为的唯一事实源。

实例或案例

30 行起步模板（可直接复用）：

# AGENTS.md
## 命令
- 测试：pnpm test（全量） / pnpm test path（单文件）
- Lint：pnpm lint --fix；提交前必须通过
## 结构
- src/api：接口层，只做参数校验与编排
- src/core：业务核心，禁止 import src/api
- src/generated：自动生成，禁止手改
## 红线
- 禁止添加任何 npm 依赖，需要时先停下询问
- 禁止修改 .github/ 与部署脚本
- 禁止在代码或注释中出现真实密钥
## 坑
- orders 表有软删除字段 deleted_at，查询必须过滤
- 时间一律用 UTC 存储、本地时区仅展示

Before/After：200 行「大而全」文档（含项目愿景、贡献流程、营销话术）vs 30 行金字塔——后者遵循率显著更高，因为每条规则都分到了注意力。

操作步骤（维护节奏）：

1. 今天就从模板建一份，只填你确信的部分。
2. 每次 AI 犯同样的错两次 → 把纠正写成一条规则（教训落盘）。
3. 每季度清理一次：删掉不再适用或可从代码推断的条目。

排错清单：

• AI 不遵守规则 → 检查条目是否可执行；把关键红线移到文件更靠前位置。
• 文件越长遵循越差 → 拆出「常见坑」到独立文档，按需引用。
• 多人规则冲突 → 规则文件进 code review，像改代码一样讨论。

公式或模型

本节不适用：遵循度受产品实现影响，无可信公开量化公式，以「重复犯错次数下降」为经验指标。

图示

本节不适用：内容金字塔已用有序列表表达，图示无增量。

直观类比

规则文件是新员工的入职须知：一页纸写清「怎么跑起来、哪里不能碰、前任踩过什么坑」。写三十页没人读，一页纸人人记得住。

常见误区

• 把它当项目文档写：愿景、议程、营销不是 AI 需要的常驻指令。
• 写不可执行的态度条目（「代码要优雅」）：模型无法照做也无法验证。
• 只写不维护：过期规则比没有更糟——它会主动误导。

与其他知识点的关系

kp-007 的提示模板是会话层，与本文件的常驻层互补；kp-009 的会话恢复模板会把新教训回写到本文件。

自测题

要点：必守命令 → 结构地图 → 行为红线 → 常见坑。

要点：可执行（能照做/能验证）+ 非代码可推断 + 近期仍适用。

1. 内容金字塔四层从高到低是什么？
2. 判断一条规则「该留」的标准？

延伸阅读

本节不适用：规则文件是新兴实践，尚无公认经典著作，以本节模板为起点即可。