面向所有 AI Agent 的项目上下文协作原则(v2.1 · 分级执行版)
本文件回答"为什么"和"从哪里读起";AGENTS.md 规定"怎么做"。任何 Agent 执行任务前,只需读 AGENTS.md 第 0 节的最小闭环即可开始工作,其余章节按需查阅。
先读上下文,再执行操作;先收敛不确定性,再修改文件;协议重量与任务风险成正比。
README First 适用于本项目中协作的所有 AI Agent(Claude Code、Cursor、Codex、Copilot、Devin 及任何能读写仓库的自动化工具),不绑定任何特定厂商。
v2 相对 v1 的核心变化只有一个:把"每次任务执行完整协议"改为"按风险分级执行"(L0/L1/L2),并把因此从日常任务中剥离的系统性维护工作——文档漂移巡检、变更记录压缩、长期知识沉淀——交给一个独立的维护技能定期完成。 最小不确定性的原则没有变,变的是达成它的成本分布:低风险任务的不确定性本来就低,不需要支付高风险任务的流程成本。
当 AI Agent 进入真实工程流程,瓶颈已从"代码生成能力"转向"上下文治理能力"。缺少上下文时,语法正确的代码也可能破坏项目质量:Agent 不知道目录为何存在、隐性知识藏在开发者脑中、重复造轮子、局部修改破坏整体、文档漂移放大错误、多会话之间没有共同记忆、变更只留 diff 不留原因。
README First 把这些问题转化为工程制度:让每次工作沿稳定的上下文路径理解项目,并把新的长期知识沉淀回项目。
推荐的最小系统:
project/
├── AGENTS.md # 分级执行协议(第 0 节为每次必读的最小闭环)
├── README.md # 项目地图:是什么、怎么跑、从哪读起
├── VERSION # README First 协议版本(按需同步)
├── .ai/
│ ├── architecture/ # 当前稳定架构知识层(从单个 README.md 起步)
│ ├── changes/ # 分级变更记录(L0 不记,L1 短记,L2 全记)
│ │ └── YYYY-MM-DD.md
│ ├── decisions/ # 长期架构决策
│ │ └── 0001-example.md
│ ├── glossary.md # 术语表(按需启用)
│ ├── handoff.md # 会话交接(按需启用)
│ └── plans/ # 复杂任务计划(按需启用)
│ └── done/
└── src/
└── README.md # 仅为关键目录建立(P0 优先,渐进覆盖)各层职责:
| 层 | 职责 |
|---|---|
AGENTS.md |
行为协议层:任务分级、读取规则、不确定性协议、记录规则、禁止行为 |
根 README.md |
项目地图层:项目是什么、技术栈、安装/测试/构建、顶层目录职责 |
目录级 README.md |
局部契约层:目录职责、核心文件、依赖边界、验证方式 |
.ai/architecture/ |
当前架构层:跨目录边界、文档契约、当前状态(只记当前事实) |
.ai/changes/ |
修改记录层:为什么改、基于什么假设、如何验证 |
.ai/decisions/ |
决策层:为什么长期这样选、哪些边界需长期遵守 |
.ai/glossary.md |
术语层(按需启用):共享语言、别名与易混淆项 |
.ai/handoff.md |
会话交接层(按需启用):跨会话任务连续性 |
.ai/plans/ |
计划层(按需启用):L2 多阶段任务的零上下文执行计划 |
成熟项目可扩展 .ai/plans/、.ai/prompts/、.ai/reviews/。.ai/changes/ 中被压缩归档的记录进入 .ai/changes/archive/。
执行任何操作前,先按 AGENTS.md 第 2 节的路由读取相关上下文。但阅读有停止条件:当影响本次任务的偶然不确定性已被消除,就停止扩大阅读。README First 要求的是"读到够用",不是"读完全部"。
改错别字和改公共 API 不应支付同样的流程成本。任务分为 L0(轻量)、L1(标准)、L2(高影响)三级,读取范围、任务契约、记录深度、输出要求全部随级别缩放。定级拿不准就升级,执行中命中高影响特征就升级——分级本身就是一次风险评估,它保证协议的注意力集中在不确定性真正危险的地方。
规则有层级:AGENTS.md(全局)→ 根 README → 上级目录 README → 当前目录 README → 代码与测试(事实来源)。冲突时以更靠近目标文件的 README 为准;README 与代码冲突时必须显式指出,不得静默选边。
README 与 .ai/architecture/ 只记录职责、边界、接口、约定和验证方式,不记录流水账、临时调试和可从 diff 看出的细节。判断标准:六个月后的维护者是否需要知道?
diff 只说明"改了什么"。变更记录按级别缩放:L0 靠 commit message,L1 记五个字段,L2 记完整契约——原因、假设、影响范围、验证证据,让后续 Agent 理解修改意图并复核。
日常任务只做追加式的轻量记录,不承担系统性维护。文档漂移巡检、记录压缩归档、重复经验沉淀为长期知识、协议阈值校准,由 readme-first-maintainer 技能定期批量完成。这类似记忆的巩固:工作时快速留痕,休整时整理归档。
定级(L0 / L1 / L2)→ 按级读取与执行 → 按级记录与报告细则见 AGENTS.md。日常任务的完整心智负担应控制在:L0 几乎无感,L1 一次短记录,L2 才展开完整协议。
README First 的生命周期分三段,对应两个技能加一份协议:
- 初始化 ——
skills/readme-first-builder/:在新项目或存量项目中建立(或合并)AGENTS.md、根 README、.ai/结构和 P0 关键目录 README。一次性使用,初始化完成后交还项目自己的AGENTS.md。 - 日常执行 —— 目标项目的
AGENTS.md:所有常规任务按分级协议执行,不再触发任何技能。 - 定期维护 ——
skills/readme-first-maintainer/:每 2–4 周、或变更记录累积到阈值、或大重构后运行。负责健康巡检(漂移、失效引用、覆盖缺口)、记忆压缩(归档旧 changes)、知识沉淀(重复经验写入长期文档)、协议校准(分级阈值是否符合项目实际)。
本仓库协议版本见根 VERSION。下游项目的 AGENTS.md 首行以 <!-- README First protocol vX.Y.Z --> 印记当前版本;skills/readme-first-builder/ 支持检测印记并按序应用 migrations/ 中的升级清单,不覆盖本地规则。
准确(基于当前代码)、简短(50–150 行,只记长期有用信息)、可操作(能指导正确的增删改查)、有边界(负责什么、不负责什么)、有入口(核心文件与对外接口)、有验证(修改后运行什么)。
应避免:内容空泛、与代码不一致、流水账、百科全书式逐文件解释、缺依赖边界、缺验证方式、堆砌不可执行的口号。
不为 node_modules/、dist/、build/、coverage/、.cache/、tmp/、logs/ 等构建产物或缓存目录创建 README。只给真正承担长期职责的目录建立上下文契约,且优先覆盖高频修改的核心目录,其余渐进补齐。
- 与传统 README:扩展而非否定——同时服务人类与 AI 的上下文获取、行为约束与维护。
- 与 ADR:
.ai/decisions/是轻量 ADR,更关注哪些决策影响 Agent 后续操作。 - 与 Git:
.ai/changes/不替代 commit;diff 记录改了什么,changes 记录原因、假设与验证。 - 与测试:README First 解决"Agent 是否理解上下文",测试解决"修改是否破坏行为"。
README First 的本质不是"多写 README",而是建立一套适合 AI 协作开发的项目上下文协议——并让协议本身保持可负担:重量随风险缩放,维护定期批量完成。
让 AI 先理解项目,再改变项目;让每一次改变,都反过来增强项目的可理解性;让协议本身,不成为新的负担。