1. 概览
AI Coding 的关键是让模型在正确时间拿到正确上下文。
把散在文档、聊天记录、邮件和成员脑子里的细节归拢到一处，让模型按需使用。
这样才能早日实现 one-shot 开发( 许愿式开发 / 一句话需求 )。
这份指南覆盖四个阶段：
- 新项目：搭上下文底座。
- 老项目：补齐代码读不出的约束。
- 日常需求：沉淀和复用上下文。
- 团队：把方法变成可维护的工程约束。
适合正在用 Coding Agent 的工程师和技术负责人。全文偏操作。
新项目从第 2 节读起，老项目从第 3 节读起，日常需求看第 4 节，团队推广看第 5 节，长期维护看第 6 节。
先从 Agent 的入口文件开始。
AGENTS.md ( Agent 主流入口，cc 也支持了 )是 Agent 的地图，只回答「去哪里找」和「什么时候看」：
1 | # 项目指南 |
1.1 上下文怎么分
上下文包括聊天窗口、文档、代码、环境和当前任务状态。它有五个来源：
- 代码与索引：仓库、grep、语义索引和目录结构，回答「代码现在是什么样」。
- 环境与权限：环境清单、配置派生链、沙箱和审批规则，回答「在哪个环境跑，能做什么」。
- 会话状态：任务说明、计划文件、失败记录和会话摘要，回答「这次做到哪一步」。
- 项目文档：AGENTS.md、架构、工作流和术语表，回答「怎么读、怎么跑」。
- 长期知识：ADR、踩坑记录、recipe 和 skill，回答「哪些方案被否决，哪些坑不能踩」。
代码和环境是事实源。文档解释代码读不出的因果，但不能覆盖代码。文档和环境配置冲突时，先停止自动化改动，由知识 owner 确认后修正。修正前不要让 Agent 继续执行。
治理时记两个判断：内容类型决定文件放哪，加载时机决定常驻还是按需。
1.1.1 内容类型与唯一归属
不确定知识放哪，按内容类型选唯一归属：
| 想写的内容 | 放哪里 |
|---|---|
| 服务做什么、不做什么 | AGENTS.md |
| 模块边界和全局禁止事项 | architecture.md |
| 分支、提交、评审和发布 | workflow.md |
| 业务词和数据含义 | domain.md |
| 静默失败和不可回滚动作 | safety.md |
| 为什么选它、否决了什么 | ADR |
| 为什么常规检查拦不住 | mistakes.md |
| 第二次还会做的修改序列 | recipes |
| 排查、验证和发布怎么查 | skill 或脚本 |
| 标准写法抄哪里 | reference-implementations.md |
README 面向人，AGENTS.md 面向 Agent。两者可以互相引用，但不要让一个文件同时承担两套读者。
同一内容只允许一个事实源。入口文件只写路径和阅读时机，不复制内容。
1.1.2 加载时机
常驻内容写进 AGENTS.md：项目定位、核心命令、全局禁止事项。
按需内容由入口路由，用时读：模块细节、领域术语、决策、recipe 和 skill。
会话内内容放计划文件和任务笔记：当前计划、失败记录、下一步。
语义索引和 grep 是 Agent 的默认检索通道。文档只在满足任一条件时才写：
- 代码读不出因果、约束或顺序；
- Agent 在真实任务里重复犯同一个错；
- 人工确认需要跨需求复用。
三条贯穿全文的规则：
- 能落文件的先落文件。聊天记录会被压缩，文件还能检索、评审和恢复。
- 能引用的不复制。同一知识只放一处，入口只写路径和阅读时机。
- 能按需加载的不常驻。入口保持短，细节拆成单独文档。
2. 新项目：分阶段搭底座
新项目分两个阶段。第一天只写当天能确认的内容，第一个真实需求完成后再补架构和入口表。
2.1 第一天
- 初始化 Git。这是 Agent 判断改动、恢复状态和做 diff 的基础。
- 写最小 AGENTS.md：项目定位一句话、技术栈、启动、测试、格式化命令。
- 约定计划目录 .plan/。
- 初始化基础校验：编译、测试、格式化至少有一项能跑。
- 明确权限边界：可写目录、网络、审批规则。
- 记录环境事实：目标环境、配置来源、部署方式、验证命令。先写已知项，未知项标「未知」。
不要第一天写完整架构、禁止事项和入口表。这些内容通常还不可知，硬写会让 Agent 编故事。
2.2 第一个真实需求后
- 根据实际调用链补架构说明。
- 根据实际风险补禁止事项。
- 根据实际改动补关键入口文件表。
- 把这次踩坑、验证方式和放弃方案写进对应文档。
这些都是维护者确认后的结论。不要把 Agent 从代码反推出的「完整规范」直接当成事实源。
不要一开始建全套目录。单人项目或改动集中在单文件的工具，有一份 AGENTS.md、一个计划目录和基础校验就够。满足下面任意两条，再拆文档：
- 一次改动要碰三个以上分散文件；
- 存在配置、部署、运行时之间的隐藏因果；
- 团队有三个人以上，或有新人轮换；
- Agent 反复犯同类错误。
3. 老项目：先梳理，再让 Agent 动手
老项目的上下文散在四类载体：代码、配置、老成员的记忆、历史沟通记录。直接让 Agent 阅读仓库不够，因为代码能说明现状，说明不了约束、放弃过的方案和事故原因。
老项目改造分四步。问题后面都标了取数来源，因为答案不能靠一次会议凭记忆得出。
- 先问六个问题：
- 这个系统解决什么问题，不解决什么问题？README、需求文档、入口代码、产品负责人。
- 请求从哪里进，经过哪些模块，从哪里出？路由、trace、日志、调用图。
- 修改一个核心对象通常要碰哪些文件？Git 历史、参考实现、重复改动统计。
- 哪些动作会造成静默失败或不可回滚？错误处理代码、迁移脚本、删除操作、告警、事故记录。
- 哪些方案被否决过，为什么？ADR、PR 讨论、Git revert、老同事访谈。
- 改动怎么验证？测试、CI、本地复现步骤、监控指标。
- 把答案分类落盘。现状和约束写进工作文档，业务词写进术语表，被否决的方案写进决策记录，重复操作写成 recipe。
- 对查不到的答案标「未知」，再标风险等级。用事故记录、发布记录、监控告警或小任务实验补证据，不要让 Agent 补故事。
- 做一次小任务验证。挑一个边界清楚的小需求，先让 Agent 说出要读哪些文件、按什么顺序改、怎么验证。对得上再动手。
老项目最忌讳让 Agent 从代码反推出一份「完整规范」，再把它当成事实源。代码梳理可以产出入口和假设，约束必须由维护者确认。维护者不在时，用历史事故单、发布记录和监控告警做替代证据，并把不确定约束标成高风险。
3.1 入口文件：只做路由
AGENTS.md 是 Agent 的地图。它只回答两个问题：
- 去哪里找？
- 什么时候看？
开头示例是推荐结构。三条硬约束：
- 内容只写一份。其他工具入口只引用 AGENTS.md。
- 单条规则必须可执行。「注意质量」没用，「公共函数必须有单测」有用。
- 定期删。判断标准是删掉这条后，模型会不会犯真实见过的错。
这三条适用于入口文件本身，也适用于目录里的长期文档。
入口只做路由，不追求固定行数。工具上限用当前官方文档确认。例如 Codex 当前把所有项目指令合计限制在 32 KiB，这是根目录和嵌套入口的总预算。单文件可以更小，上限要看当前工具文档。如果入口里大量内容只在特定模块有用，就该拆出去。
3.2 长期知识：按用途分仓
长期知识不要全塞进入口文件。按用途拆成六类：
- 架构约束：影响模块边界或全局行为，放 architecture.md。
- 决策记录：有替代方案的技术选择，放 ADR。
- 踩坑记录：编译、测试和评审都难拦住，放 mistakes.md。
- 操作流程：同一序列做到第二次，放 recipes。
- 工具流程：排查、验证和发布需要固定步骤，放 skill 或脚本。
- 参考实现：不知道标准写法时抄哪里，放 reference-implementations.md。
3.2.1 架构文档
记录三件事：
- 模块分层和数据流；
- 每层允许和禁止的依赖；
- 反直觉规则的原因。
例如「渲染上看属于 A 卡，决策权在 B 资源号」这类规则，不看原因的人很容易改错。写清楚因果，比只写「不要动」有价值。
3.2.2 决策记录
只有存在替代方案时才写决策记录。最小模板：
1 | # ADR-001 选择队列方案 |
被否决的方案必须留理由。否则半年后会有人提出同一个方案。
三条硬规则：
- 编号只增不复用，缺号不补。
- 被推翻时改状态、保留原文，不删文件，不原地覆盖结论。
- 有影响范围和验证要点。没有验证要点的决策无法确认生效。
3.2.3 踩坑记录
踩坑记录分两层。第一层是快速对照表：
1 | | 你可能想做的 | 应该做的 | 原因 | |
第一层只做快速扫读。满足任一条件才写第二层深度解析：出过线上事故、常规检查兜不住、失败是静默的。深度解析必须回答「为什么没人发现」，并给出一条可以直接执行的验证命令。第一层里的每条原因也应能解释复发场景。暂时给不出命令的，把它移入候选清单，不要伪装成已验证结论。
只写「别用 X」不够。下次遇到变体，模型还是会踩。
3.2.4 Recipe
同一个操作做到第二次，就写成 recipe。它是一份修改清单加验证清单：
1 | # 新增导出任务 |
超过三个文件的改动，先写计划文件。每个目标文件写预期改动，做完后和 diff 对账。计划是任务文件，做完可以删。
文件移动、删除或接口变更时，同步检查引用这些路径的 recipe。过期 recipe 比没有 recipe 更危险。
3.2.5 Skill 和脚本
Skill 适合「遇到什么现象，按什么步骤查」。脚本适合确定性步骤：解析日志、批量检查、汇总多个查询。
写 skill 时记录负面知识。工具返回空，可能是没有数据，也可能是查询通道不支持。要写清怎么对照验证，以及空结果能推出什么结论。
Skill 数量少时不用优化。超过二十个，或者描述互相抢触发，就要做二级检索：常驻几个入口型 skill，其余按需查找。
引入第三方 skill、rules 或插件前必须审查：
- 脚本是否访问网络；
- 是否读取 .env、SSH 私钥目录、凭据文件或私有目录；
- 描述是否写得过宽，导致误触发；
- 声明的工具权限是否超过用途；
- 不通过就只借鉴思路，自己重写。
4. 需求里的六个动作
一次任务不要直接说「帮我实现」。按六个动作推进。
明确目标
写清用户要什么、边界是什么、不能改什么。歧义项先问维护者。让 Agent 建立计划
超过三个文件的改动，先建计划文件 .plan/任务名.md。目标文件用仓库根相对路径，一列只写一个路径，路径不含空格。格式如下：1
2
3
4| 序号 | 目标文件 | 预期改动 | 状态 |
|---|---|---|---|
| 1 | api/export.go | 新增请求和返回结构 | todo |
| 2 | service/export.go | 新建任务并写状态 | done |验证方式和风险写在计划文件末尾。先审计划，再审代码。
给最小上下文
引用入口文档和相关 recipe，不要粘贴整个目录。与任务无关的历史另开会话。执行中保持状态
长输出写入 .plan/ 或任务指定的临时目录，上下文里留路径和结论。失败、放弃的方案和关键决定写进 .plan/notes/。Agent 可以起草，人确认后才能进入长期文档。验证后评审
跑测试和关键检查。人审时重点看边界、并发、失败路径和计划外文件。收尾沉淀
问三个问题：这次踩了什么坑？这套步骤会不会再做一次？有没有推翻旧决定？有答案就按内容类型表更新对应文档。
收尾沉淀最容易省掉。省掉一次看不出代价，省掉十次，项目又会退回老状态。
收尾沉淀进入需求的完成定义。提交者在 PR 或需求卡里勾选：
- 没有新坑，或已更新 mistakes.md；
- 步骤不会重复，或已更新 recipe；
- 没有推翻决策，或已新建 ADR 并保留旧决策；
- AI 起草的沉淀已由人确认。
知识 owner 在评审时确认这四项。没有确认，需求不算完成。
4.1 上下文太多怎么办
上下文过多会稀释注意力。装得下不等于找得到。
先做减法：
- 入口文件只放路由和全局规则；
- 临时状态不进长期文档；
- 能从代码读出的签名和目录清单不重复写；
- 密钥、内网地址和凭据不进任何上下文文件。
再按时机加载：
- 常驻：项目定位、核心命令、全局禁止事项；
- 按需：模块细节、领域术语、历史决策；
- 会话内：当前计划、失败记录、下一步。
长对话压缩时保留四类内容：目标、约束、已验证事实、失败路径。普通工具输出可以压成结论，来源引用要留下。压缩放在任务断点，不要每轮都做。
4.2 预算与隔离
上下文预算要有可观测信号，至少要能回答三个问题：
| 问题 | 可观测信号 | 动作 |
|---|---|---|
| 常驻上下文占多少预算 | 入口文件字节数、系统提示和工具定义占窗口的比例 | 拆文档、删重复规则、工具定义延迟加载 |
| 前缀缓存是否稳定 | 缓存命中率、缓存读和未缓存输入的比例 | 固定系统提示和工具顺序，把易变信息移到末尾 |
| 噪声要不要隔离 | 单个任务读了多少文件、产生多少原始输出 | 用子 Agent 读文件、跑搜索或做排查，只回传结论 |
没有工具日志时，先手动记录：入口字节数、任务读取文件数、失败重试次数。有工具日志后，再把这些指标接入日常观测。子 Agent 会增加总量，只在「主上下文被高噪声淹没」或「任务可以并行探索」时使用。
4.3 安全边界
上下文会离开本机，进入模型服务或第三方工具。核心判断是：能不能发给模型。
| 数据类型 | 处理方式 |
|---|---|
| 密钥、token、生产凭据 | 禁止进入上下文文件、聊天、命令输出和日志 |
| 患者数据、客户数据、个人身份信息 | 禁止直接进入模型。调试样本先假名化或合成 |
| 生产日志、数据库导出、请求体 | 先过滤和采样，确认没有敏感字段再使用 |
| 内网地址、内部域名、部署细节 | 只进有访问控制的内部上下文，不进公开文档 |
企业有合规要求时，先叠加公司审批、数据分级和模型使用规范。本节是工程底线，不能替代合规方案。
5. 团队治理
个人可以先用这套方法，团队推广必须补三件硬约束。
5.1 角色与审批
| 角色 | 职责 |
|---|---|
| 需求提交者 | 写目标、计划、验证结果和收尾沉淀。可让 Agent 起草 |
| 仓库知识 owner | 审批入口文件和长期文档。确认 AI 起草内容。维护固定问题集 |
| 架构 owner 或技术负责人 | 裁决跨仓库归属冲突。批准共享规则 |
知识变更尽量和代码变更同一个 PR。AI 起草的内容必须有人确认，PR 里注明来源。
5.2 CI 闸口
把机械检查放进提交或合并流程，失败阻断：
- 入口引用的文档存在；
- 计划和 diff 对账没有未解释差异；
- 关键测试、格式化、安全扫描通过；
- 第三方 skill 或插件变更经过审批。
人工只复核语义、归属和过期知识。
5.3 成本与收益
满足新项目一节的任意两条再拆文档。冷启动通常半天到两天，日常收尾控制在十分钟内，这是经验估计。先用三个朴素指标判断收益：
| 指标 | 采集方式 |
|---|---|
| 新手首个需求完成时间 | 需求卡从领取到合并的时间 |
| 因缺少上下文返工的需求数 | PR 或需求卡打标签 |
| 季度问题集命中率 | 固定问题集中命中正确文档的数量除以问题总数 |
试点前两周先记录基线。没有基线，就不要声称提升。
6. 维护闭环
知识库会腐烂。没有维护规则，文档会变成准确度未知的旧纸。
| 时机 | 动作 | 责任人 |
|---|---|---|
| 每次提交 | 检查入口引用的文件是否存在，跑关键校验脚本 | CI 和提交者 |
| 每个需求 | 更新踩坑、recipe 或决策记录 | 需求提交者和知识 owner |
| 文件移动、删除或接口变更 | 同步检查 recipe 和参考实现里的路径 | 变更作者 |
| 每两周 | 删除失效坑，合并重复规则 | 仓库知识 owner |
| 每季度 | 重读架构、安全和工作流文档，跑回归问题集 | 仓库知识 owner |
多仓库和 monorepo 按归属拆分：
- 跨仓库知识归最了解变更的仓库所有，通常是被调用方或发起方中拥有变更决定权的一方。
- 下游仓库只写单向引用，说明仓库、路径和用途，不复制内容。
- 跨仓库工具放用户级或团队级共享目录，不塞进单个仓库。
- monorepo 明确根入口和目录级入口的加载方式。不同工具的加载规则不同，用前核对当前工具文档。
共享知识的变更必须有唯一 owner。找不到 owner 的共享文档先标记过时，再决定删除或移交。
入口引用可以用脚本兜底。路由表约定只写仓库根相对路径：
1 | missing=0 |
脚本返回非零表示有缺失引用，可以直接挂 CI。
计划和 diff 是另一个检查，不要和引用检查混用：
1 | comm -3 \ |
这个命令覆盖已暂存和未暂存改动。计划表的目标文件列必须是第三列，只写一个仓库根相对路径，且路径不含空格。第一列是改了但计划没写，第二列是计划写了但没改。每一项都要么修正计划，要么补实现，要么写清为什么不需要。
再准备十到十五个已知答案的问题。每季度清空会话重问，记录 Agent 有没有命中正确文档：
1 | 新增导出任务要改哪些文件？ |
看三个信号，每个都有采集口径：
- 文件命中率：命中正确文档的问题数除以问题总数。工具日志能看到文件读取。
- 触发准确性：固定问题集里应该触发的流程或 skill 中实际触发的比例。期望触发项由问题集作者预先标注。
- 返工率：因缺少上下文返工的需求数除以总需求数。需求卡打标签。
文件命中率看日常任务，季度问题集命中率看固定回归。两者都是命中率，采集来源不同，不要混用。
三个信号退化，先查文档过期，不要先怪模型。
6.1 常见反模式
| 反模式 | 结果 | 改法 |
|---|---|---|
| 入口文件写满细节 | Agent 还没干活就耗掉上下文 | 入口只留路由，细节拆文件 |
| AGENTS.md 和 CLAUDE.md 各写一半 | 内容漂移，没人知道哪份新 | 一份写内容，另一份转发 |
| 同一规则多处重复 | 改了一处，另一处变成谣言 | 选唯一归属，其他地方引用 |
| 只加规则不清理 | 真约束被噪声盖住 | 删掉失效规则 |
| 只写结论不写原因 | 换个场景就复发 | 写因果和验证命令 |
| 决策没有替代方案 | 同一个坏方案反复被提 | ADR 里保留被否决项 |
| 计划只留在聊天里 | 会话中断后无法续接 | 计划落文件，做完和 diff 对账 |
| 把 AI 产出直接当事实 | 文档越写越像小说 | 维护者确认后才能入长期上下文 |
| 工具描述只写功能简介 | 模型在不该用时误触发 | description 写使用和不使用条件 |
| 用「节省 token」当提示 | 模型不敢做事或过度简短 | 精简输入，明确要求完成任务 |
| 跨仓库知识各复制一份 | 几份内容漂移，没人知道哪份新 | 知识归变更源所有，下游单向引用 |
| recipe 指向已删除路径 | Agent 改不存在的文件 | 记录最近验证日期，文件变更时复查 |
6.2 成熟度
按五档判断下一步：
- 有索引：AGENTS.md 存在且准确，Agent 能找到文档。
- 有规范：让一个未参与项目的新人照文档完成编译、测试、提交和发布。
- 有沉淀：踩坑写了失败机制，重复操作有 recipe，决策记录保留替代方案。
- 有工具：验证和检查脚本可执行，skill 有使用边界和负面知识。
- 有闭环：收尾沉淀真实执行，入口引用由脚本检查，季度问题集能验证效果。
不要追求一步到第五档。先让文档被用起来，再让检查自动化。
6.3 与其他实践的关系
上下文治理和质量工程分工不同。上下文治理让 Agent 知道边界，质量工程守住边界。
- 测试验证行为，文档解释为什么不能改。
- CI 拦住可判定错误，踩坑文档解释为什么 CI 拦不住某些错误。
- 权限和沙箱限制动作，安全文档标注不可回滚动作。
- Code review 看单次 diff，知识库保留跨需求的约束。
- 代码和索引给现状，文档给因果、约束和顺序。
Agent 能自动执行验证时，人最大的责任变成三件事：确认问题值得做，确认设计边界，确认结果可解释。代码可以由模型写，判断不能外包。
6.4 复核方法
- 检查入口和项目指令总大小：find . -name AGENTS.md -exec wc -c {} +，并按当前工具文档确认合计预算。
- 检查入口引用：用上文脚本找出缺失文件。
- 检查重复规则：同一关键词跨文件搜索，确认只有一个正式定义。
- 做任务映射测试：新任务开始前让 Agent 列出要读的文档，对照是否命中。
- 做季度回归：用固定问题集重测命中率、触发准确性和返工率，并和基线比较。
- 套分类表：拿一个真实需求检查每个知识点是否能唯一归入内容类型表。出现「不知道放哪」就先修分类，不急着写文档。
如果一个规则不能被这些方法观察到，它暂时只是愿望，不要写成约束。
7. 参考
- Anthropic：Effective context engineering · 注意力预算、按需加载、压缩和子 Agent 隔离
- Anthropic：Claude Code best practices · 入口指令只放普适内容，逐条判断能否删除
- Anthropic：Advanced tool use · 工具定义按需加载，工具描述影响选择准确率
- OpenAI：Prompt caching · 稳定前缀、缓存断点和最小缓存长度
- OpenAI：Compaction · 服务端压缩和保留关键状态
- Cursor：Rules · 规则拆分，按 glob 或描述加载
- Manus：Context Engineering · 文件系统当外部记忆，保留错误证据，稳定前缀
本文项目案例已脱敏，技术因果保留，不能反推出具体系统。带日期、数字和组织行为的二手说法，尽量回到一手来源。回不到就只当线索。