05 - 一份好 AGENTS.md 的结构与原则
一句话结论
好 AGENTS.md 像一份好的委托书——内容完整但不冗长、措辞明确但不模糊、层级清晰但不教条。本节讲结构、详略、风格三条原则。
结构原则：模块顺序固定
8 个模块在 AGENTS.md 里按固定顺序排列（用户级 M1→M5 → 项目级 M6→M8 + M5 细化）。原因：
- agent 按顺序读取，便于定位
- 用户复盘时按顺序对照，不会遗漏
- 与本 skill 的引导问答顺序一致
# {M1 角色摘要}
## 工作流与产出
{M2 内容}
## 协作偏好
{M3 内容}
## 法律安全基线
{M4 内容}
## 回溯契约
{M5 内容}
---
# 项目：{M6 项目代号}
## 上下文
{M6 内容}
## 受控事实入口
{M7 入口与读取条件}
## 文件结构
{M8 内容}
## 项目级回溯补充
{M5 项目级细化内容}详略原则：用户级短、项目级长
| 模块 | 建议长度 |
|---|---|
| M1 角色身份 | 1-3 行 |
| M2 工作流与产出 | 3-8 行（列举而非长描述） |
| M3 协作偏好 | 3-5 行 |
| M4 工具链与禁区 | 3-10 行（分点列举） |
| M5 回溯契约（用户级基础） | 5-10 行（触发场景 + 写入位置） |
| M6 项目上下文 | 3-5 行 |
| M7 受控事实入口 | 2-5 行（不复制案件材料） |
| M8 文件结构约定 | 3-8 行 |
| M5 项目级细化 | 3-8 行（补充项目特有触发） |
整体 AGENTS.md 控制在 30-80 行。超过 100 行通常意味着：写得太啰嗦、复制了事实正文，或没区分用户级/项目级。
风格原则：指令式而非描述式
指令式（好）：
✅ 不要替我向法院提交任何文书。
✅ 合同金额、费率、责任限制条款变更必须人工复核。
✅ 决策写入项目既有决策载体；证据、期限和交付分别写入各自权威来源。描述式（差）：
❌ 我是一名律师，平时主要做合同审查。我希望 AI 在协助我时谨慎行事。
（这种写法 agent 不会严格执行——它更倾向按指令执行）三条铁律
1. 不用"我希望" / "我建议"
agent 对祈使句（"不要 X"、"必须 Y"）的执行力远高于"我希望" / "建议"。
2. 红线用"不要"开头
✅ 不要替我对外发送任何文件。
✅ 不要替我对案件做实质性结论。
✅ 不要伪造证据材料、不要删除已有记录。3. 触发场景用“什么变化、写到哪里”
回溯契约的措辞范本：
✅ 证据新增或来源变化 → 更新项目既有证据索引
✅ 期限变化 → 更新期限台账/任务源，并记录起算事实与复核状态
✅ 对外发送文书前 → 取得明确授权；版本和发送状态写入既有交付记录避免：
❌ 重要的事情要记录一下。
（什么叫"重要"？agent 判断会偏）好 vs 坏 对比
好的 M1（角色身份）
# 律师 · 上海执业 · 主营合同审查与公司诉讼
（3 行，身份、地域、业务方向清楚）
### 坏的 M1
关于我
我是 XX 律师，毕业于某大学法学院，已经执业 10 年了。我平时主要做合同审查，偶尔也做一些诉讼。我对工作要求比较高，希望 AI 能认真对待每一份材料。
（10 行还在讲履历，agent 读完不知道你是谁）好的 M5（回溯契约）
## 回溯契约
关键动作必须留痕：
- 决策与取舍 → 项目既有决策载体
- 证据新增/来源/核验状态变化 → 项目既有证据索引
- 期限变化 → 期限台账或任务源，并记录起算事实与复核状态
- 交付版本/审批/发送状态 → 项目既有交付记录
写入原则：日期 + 上下文 + 动作 + 影响；不删除已有记录。坏的 M5
## 回溯
我希望 AI 在做重要事情的时候记录一下。重要的事情包括案号变化、新材料、决策这些。具体写到哪里可以参考项目里的 docs 文件夹。
（“重要的事情”agent 判断会偏；“项目里的 docs 文件夹”没说哪个权威载体）
## 不要做的事
- **不要复制别人 AGENTS.md**：每个人工作流不同，复制粘贴会失真
- **不要写得太长**：AGENTS.md 是给 agent 读的指令，不是简历
- **不要写得太抽象**："认真对待工作" agent 不会执行
- **不要写得太具体**："所有包含'管辖'字样的段落都要改" 缺乏泛化
- **不要重复**：用户级和项目级里同样的内容只写一份
- **不要复制真实案件事实**：长期指令只保留项目代号、阶段、关键时点和受控入口
## 维护原则
| 频率 | 动作 |
|---|---|
| 每会话 | 看一眼是否有新禁区要加 |
| 每月 | 检查 M5 触发场景是否需要更新 |
| 每季度 | 检查 M4 工具链是否有变化（装了新工具？某工具下线？） |
| 每年 | 全量复盘用户级 AGENTS.md（角色、业务方向可能变了） |
## 接下来读什么
- ⭐ 法律人专属回溯契约 → [references/06-audit-trail-contract.md](06-audit-trail-contract.md)
- M1-M8 任一模块深度讲解 → 详见 [references/04-modules.md](04-modules.md)