面向所有 AI Agent 的项目上下文协作原则
本文件解释本项目为何采用 README First，以及它如何与 AGENTS.md 协同。README First.md 回答“为什么”，AGENTS.md 规定“怎么做”——任何 Agent 执行任务前应先读 AGENTS.md 中的可执行规则。
先读上下文，再执行操作；先收敛不确定性，再修改文件；先验证影响，再记录变化。
README First 适用于本项目中协作的所有 AI Agent，包括但不限于 Claude Code、Cursor、Codex、GitHub Copilot、Devin，以及任何能读写仓库的自动化工具。它不绑定任何特定厂商。
当 AI Agent 进入真实工程流程，瓶颈已从“代码生成能力”转向“上下文治理能力”。缺少上下文时，即使语法正确的代码也可能破坏项目整体质量。常见风险包括：
- 上下文缺失：Agent 不知道某目录为何存在、哪些是核心入口、哪些约定不能破坏。
- 隐性知识不可见：架构选择、命名规范、模块边界、历史妥协藏在开发者脑中或零散聊天里。
- 重复造轮子：没先理解现有结构，新建重复模块、工具函数、抽象层。
- 局部修改破坏整体：只看目标文件，不理解上游调用方与下游依赖。
- 文档与代码漂移：文档过时，Agent 读到过时信息反而放大错误。
- 多 Agent 协作不可控：不同会话之间没有统一项目记忆，每次从零开始。
- 变更不可追踪：改完只留 diff，没记录原因、影响范围和后续注意事项。
README First 把这些问题转化为工程制度：让每次工作都沿稳定的上下文路径理解项目，并把新的长期知识沉淀回项目。
推荐的最小系统：
project/
├── AGENTS.md # AI 全局行为规则（Agent 每次执行前必读）
├── README First.md # 本文件：协作原则说明
├── README.md # 项目总览与入口
├── .ai/
│ ├── changes/ # AI 变更记录
│ │ └── YYYY-MM-DD.md
│ └── decisions/ # 架构决策记录
│ └── 0001-example.md
├── src/
│ └── README.md # 目录级上下文说明
└── tests/
└── README.md # 测试目录上下文说明成熟项目可扩展 .ai/plans/（复杂任务计划）、.ai/prompts/（可复用 Prompt）、.ai/reviews/（Review 记录）、.ai/audits/（文档漂移检查）。
各层职责：
AGENTS.md：行为协议层。规定读取顺序、不确定性压缩、增删改查检查项、记录规则、禁止行为、验收标准。- 根
README.md：项目地图层。项目是什么、技术栈、安装/启动/测试/构建、顶层目录职责、应从哪里读起。 - 目录级
README.md：局部上下文契约层。每个关键目录的职责、核心文件、维护约定、依赖边界、验证方式。 .ai/changes/：修改记录层。补足 git diff 不表达的内容——为什么改、如何验证、对未来维护的影响。.ai/decisions/：架构决策层。为什么选某方案、为什么废弃旧结构、哪些边界需长期遵守。
执行任何查询、新增、修改、删除前，先按 AGENTS.md 规定的顺序读取相关 README 与上下文。某级目录缺 README 时，向上读取上级 README 并谨慎推断，关键目录则先补建。
规则具有层级：AGENTS.md（全局）→ 根 README（整体）→ 上级目录 README（通用）→ 当前目录 README（局部）→ 代码与测试（事实来源）。目录级冲突时，以更靠近目标文件的 README 为准；README 与代码冲突时，必须指出并判断是文档过时还是代码偏离，不得静默选择。
README 记录：目录职责、模块边界、公共接口、文件组织方式、命名与依赖规则、测试与验证方式、未来维护者需知道的长期约定。README 不记录：普通 bug 修复、临时调试信息、无长期价值的改动、可从 git diff 看出的细节、与目录职责无关的备忘。具体修改记入 .ai/changes/，架构决策记入 .ai/decisions/。
diff 只说明“改了什么”，不稳定说明“为什么”。因此每次变更应记录目标、涉及目录、内容、原因、影响范围、验证方式、是否更新 README、后续注意事项，让后续 Agent 或人类理解修改意图。
不必一开始全目录覆盖。优先覆盖：业务核心目录、高频修改目录、公共组件目录、API/service/store/types/hooks 等共享能力目录、tests/scripts/config 等影响全局的目录。不为 node_modules/、dist/、build/、coverage/、.cache/、tmp/、logs/ 等构建产物或缓存目录创建 README。
只给真正承担长期职责的目录建立上下文契约。
每次执行项目任务，Agent 应遵循（详见 AGENTS.md）：
1. 识别任务类型，把 prompt 转换为任务契约
2. 定位影响范围
3. 阅读 AGENTS.md → 根 README.md → 目标路径上各级目录 README.md
4. 先消除偶然不确定性，再压缩本质不确定性（按风险等级处理）
5. 检查 README 与实际代码是否一致
6. 执行查询、新增、修改或删除（最小、保守、可回滚）
7. 运行或说明验证方式
8. 按触发条件更新 README
9. 在 .ai/changes/ 中记录本次变更
10. 输出最终实施报告（含关键假设、剩余不确定性、验证结果）- 准确：基于当前代码，而非凭空设计。
- 简短：只记录长期有用信息（建议 50–150 行）。
- 可操作：能指导 Agent 做正确的增删改查。
- 有边界：明确本目录负责什么、不负责什么。
- 有入口：标出核心文件与对外接口。
- 有验证：说明修改后应运行哪些测试或检查。
- 可维护：不依赖个人记忆，不写难以长期维护的细节。
应避免：内容空泛（“这里放组件”）、与代码不一致、只写流水账、把每个文件解释成百科全书、不写依赖边界、不写验证方式、堆砌“应保持良好代码质量”这类不可执行句子。
- 与传统 README：不否定，而是扩展——传统 README 服务人类理解项目，README First 同时服务人类与 AI 的上下文获取、行为约束与后续维护。
- 与 ADR：
.ai/decisions/类似轻量 ADR，更偏向 AI 协作语境，关注哪些决策会影响 Agent 后续操作、哪些边界需长期遵守。 - 与 Git：
.ai/changes/不替代 commit；diff 记录改了什么，.ai/changes/记录原因、范围、验证和后续注意事项。 - 与测试：README First 解决“Agent 是否理解上下文”，测试解决“修改是否破坏行为”。README 告诉 Agent 该运行哪些测试，测试验证修改是否正确，
.ai/changes/记录验证结果。
- 扫描与识别：扫描目录，排除构建产物/依赖/缓存目录，识别关键目录与已有文档。
- 建立全局规则：创建或合并
AGENTS.md。 - 建立项目总览：补全根
README.md，加入 README First 说明并指向关键目录 README。 - 建立目录级上下文：按 P0（src/app/server/api/db/config/tests…）→ P1（hooks/utils/types/store/routes/scripts/docs）→ P2（examples/fixtures/mocks/tools）优先级补全目录 README。
- 建立记录机制：创建
.ai/changes/与.ai/decisions/，写入模板并记录本次初始化。 - 验证与修正：检查 README 是否引用不存在的文件、目录职责是否与代码一致、是否误覆盖已有 README，输出实施报告与风险清单。
已有 README 或
AGENTS.md时，必须合并补充，不得直接覆盖；所有内容必须基于当前代码和目录结构，不得凭空编造。
本仓库包含 skills/readme-first-builder/，用于在其他项目中初始化或升级 README First 完整架构。该 skill 只负责引导创建或合并 AGENTS.md、根 README.md、.ai/changes/、.ai/decisions/ 与关键目录 README；初始化完成后，后续日常任务应直接遵循目标项目自己的 AGENTS.md。
README First 的本质不是“多写 README”，而是建立一套适合 AI 协作开发的项目上下文协议。它把分散在开发者脑中、聊天记录、PR 讨论和历史 commit 中的隐性知识，沉淀为项目内部可读取、可执行、可维护的上下文系统。
让 AI 先理解项目，再改变项目；让每一次改变，都反过来增强项目的可理解性。