适用对象：需要为多个项目统一 Agent 文档写法的维护者用途：作为跨项目总规范，不直接替代具体项目里的 AGENTS.md / CLAUDE.md / SKILL.md

1. 目标

Agent 文档的作用不是展示完整背景，而是给 agent 一个稳定、可执行、可验证的运行控制面。

高价值 Agent 文档应优先解决 4 件事：

1. 去哪里看
2. 不能做什么
3. 需要跑什么
4. 什么算完成

2. 该写什么

常驻文档优先写：

• 项目地图或目录路由
• 高频且稳定的命令
• 项目特有约定
• 禁区与风险边界
• 完成定义与验证顺序
• 外部文档入口

不要优先写：

• 大段背景介绍
• 一次性任务说明
• 会快速过期的流程细节
• 大量泛化“最佳实践”
• 低频知识百科

3. 怎么分层

推荐分层：

• 根级文档：全局规则、路由、禁区、完成定义
• 目录级文档：局部工具链、局部架构、局部测试要求
• 外部文档：复杂流程、runbook、长参考资料、专门 workflow
• skills：按需加载的参考知识或工作流

原则：

• 根文档负责入口，不负责百科全书
• 长流程优先拆出去
• 只对局部生效的规则，不要塞进全局文档

4. 规则写法

好规则应满足：

• 短
• 具体
• 有条件
• 可验证

优先写成这种形式：

• “改 api/ 代码前先读 api/AGENTS.md”
• “改 runtime 代码后依次运行 lint -> typecheck -> tests”
• “不要直接修改生成文件”

避免这种形式：

• “请遵循最佳实践”
• “请理解架构后再改代码”
• “注意保证质量”

5. 长度预算

这不是跨生态硬标准，而是推荐预算：

超过警戒线时，优先考虑：

• 按子系统拆分
• 把长流程移到外部文档
• 把低频知识移到 skills 或 references

即使没超行数，只要出现这些情况也该拆：

• 同一文档覆盖多个子系统
• 分支条件很多
• 必须滚很久才能找到当前任务相关内容
• 文档已经像 reference manual，不像入口控制面

6. 最小结构

一个可用的根级 Agent 文档，至少应包含：

1. 项目一句话地图
2. 目录或任务路由
3. 常用命令
4. 禁区与关键约束
5. 完成定义
6. 外部文档入口

7. 评估清单

快速判断一份文档是否好用：

• 能否在 1 分钟内看出“先看哪里、先跑什么”
• 是否给出精确命令和路径
• 是否明确禁区
• 是否明确完成定义
• 是否区分常驻规则与外部文档
• 是否以项目特有信息为主
• 是否没有被低频长流程淹没

如果上面 7 条做不到 5 条以上，通常值得优化。

8. 维护原则

• 每次 agent 或 reviewer 重复犯同一种错，评估是否升级为常驻规则
• 规则新增时，优先删除过期或重复内容
• 文档不能替代 CI、脚本、权限和 hooks
• 真正危险的约束应同时有机制层保障

9. 使用方式

这份文档适合作为：

• 团队统一写法说明
• 文档评审标准
• 新项目初始化规范

这份文档不适合作为：

• 直接塞进某个具体项目当运行文档
• 直接替代具体项目的 AGENTS.md

具体项目应基于这份规范，再写自己的项目版短文档。