外观
第 3 章 Research Brief：仓库即 Agent 上下文
任务与读者问题
一次 Agent 对话会结束，模型的短期上下文也会被压缩或丢失；长期工程项目却需要持续保留目标、约束、决策、当前状态和下一步。第 3 章要回答：如何把这些信息组织为可读、可 diff、可审查的仓库工件，让新的 Agent 或人类维护者能在没有聊天记录的情况下继续工作？
读者完成本章后应能：
- 区分稳定规则、可变状态、历史决策、正式内容与临时对话信息。
- 为一个项目设计最小的上下文目录、读取顺序和状态更新责任。
- 解释为什么仓库上下文能辅助恢复任务，但不能替代权限控制、验证或人类判断。
- 为跨会话交接设计可检查的输入、输出和验收条件。
范围与非范围
范围： 讨论版本控制仓库中的指令文件、项目状态、决策记录、交接记录、正式工件和校验命令如何共同构成可审查上下文；使用本书自身目录作为原创教学案例。
非范围： 不承诺任何 Agent 能自动正确理解全部仓库；不比较具体产品的价格、模型能力或私有实现；不把 Markdown 指令描述为安全边界；不讲解 Git 的全部命令或把项目文档替代为外部知识库。
研究问题
| 问题 | 需要的证据 | 当前结论 |
|---|---|---|
| 仓库级指令文件如何帮助 Codex 建立任务上下文？ | Codex 对 AGENTS.md 发现和合并顺序的官方说明。 | 官方手册说明 Codex 在工作前读取 AGENTS.md，并按全局与项目目录层级组成指令链；本书只使用这一项目指令机制的限定范围。 |
CLAUDE.md 应承担什么责任？ | Claude Code 的项目记忆官方文档。 | 官方文档将 CLAUDE.md 定位为项目的持久指令上下文，同时明确它不是强制执行配置；本书据此保留独立校验和权限边界。 |
| “仓库即 Agent 上下文”是否是外部标准？ | 来源范围与本书设计决定。 | 不是。这是本书的工程模型：将稳定规则、当前状态、历史决策和正式工件放在可审查的仓库路径中。 |
| 什么信息不应只依赖仓库上下文？ | 安全与验证规则、失败模式。 | 权限、密钥、真实外部状态和结果验证仍需由运行环境、工具契约、测试或人工审批负责。 |
已核验来源与可用陈述
| ID | 可在本章使用的陈述 | 证据边界 | 核验状态 |
|---|---|---|---|
| REF-005 | Codex 官方手册说明：AGENTS.md 用于持久化项目指令；Codex 从全局和项目目录层级发现并组合指令，靠近当前工作目录的项目指令在组合文本中更靠后。 | 仅用于 Codex 的项目指令发现与作用范围；不外推为所有 Agent 的加载算法。 | 2026-07-15 通过当日更新的 Codex 官方手册复核。 |
| REF-006 | Claude Code 官方文档说明：CLAUDE.md 提供项目持久指令并在会话开始时作为上下文加载；该类指令不是强制执行配置。 | 仅用于 Claude Code 的项目记忆与指令边界；不外推为安全保证。 | 2026-07-15 复核官方文档。 |
| REF-001 | 来源作者将 Harness 描述为围绕基础模型组织执行、上下文、工件与评估的系统。 | 仅作 Harness 背景；“仓库即上下文”的目录模型由本书自行提出。 | 2026-07-15 已复核原文。 |
本书的工程扩展
以下内容是本书的设计建议，不是来源的逐句转述或产品统一标准：
- 使用根入口文件给出阅读顺序，再把稳定原则放入规则文件，避免将所有内容堆进一个超长指令。
- 将“项目是什么、为什么这样设计、当前完成什么、下一步做什么”分别落在项目上下文、决策、状态和任务文件中。
- 将正式书稿、可运行示例、图示源和验证脚本视为上下文中的可检查证据，而非仅供人类阅读的附件。
- 将交接视为一个有输入和验收条件的工作流：下一位执行者要能定位已完成工件、真实校验命令、风险与下一项独立任务。
- 将指令文本与强制机制分开：Markdown 规则约束行为预期，权限、Sandbox、测试和审批负责阻止或发现不合格行动。
术语与章节边界
| 术语 | 本章的最小用法 | 交由后续章节处理 |
|---|---|---|
| 项目上下文（Project Context） | 使新执行者理解项目目标、边界与当前任务的仓库内信息集合。 | 第 06 章讨论 Context Engineering 的筛选与预算。 |
| 工作记忆（Working Memory） | 当前任务内的临时观察和中间状态。 | 第 07 章讨论短期与长期记忆的读写策略。 |
| 长期记忆（Long-term Memory） | 跨任务保存的决策、经验和可复用知识。 | 第 07、16、33、45 章讨论沉淀、反思与跨工具接力。 |
| 状态（State） | 可被更新、检查与恢复的当前阶段和下一步。 | 第 10 章讨论状态机、检查点与恢复。 |
| 项目规则 | Agent 读取的行为约定，不等同于强制权限策略。 | 第 12、14、41 章讨论权限、审批与审计。 |
计划叙述与工件
章节结构
- 从“新 Agent 接手中断任务却没有聊天记录”的场景引入上下文丢失问题。
- 区分稳定规则、可变状态、决策历史、正式内容、示例和校验结果的不同职责与更新频率。
- 用本书目录解释
AGENTS.md、CLAUDE.md、.context/、.memory/、.ai/与docs/的协作方式。 - 设计从读取入口到领取任务、运行校验、更新状态、交接的恢复工作流。
- 讨论冲突、过期、冗余、敏感信息和“文档规则不是强制执行”的边界。
计划图示
图示应展示一位新执行者从入口文件开始，依次读取规则、项目上下文、当前状态、下一任务、进度和当前章节工件，并在完成后回写状态与交接。图中必须区分：稳定规则、可变状态、历史记录、正式内容和校验反馈；不得暗示任何文件会自动强制权限。
计划案例
使用“第 3 章准备任务在会话中断后由另一位 Agent 接手”的原创教学场景：前一位执行者已经完成 Research Brief 但尚未写 Outline；下一位如何根据 NEXT_TASK.md、progress.md、Research Brief 和候选参考资料继续，而不重复研究或把未核验计划写成正文。
计划验证
- 检查入口文件的阅读顺序能定位到当前任务与相关工件。
- 模拟状态不一致：
CURRENT_STATE.md与progress.md冲突时，读者应能说明先以何种真实验证证据为基线。 - 用链接检查和状态检查证明工件路径存在、章节阶段表可解析。
- 不将“规则文件被读取”作为“工具一定受限”或“结果已经正确”的证据。
事实核验与版权计划
- 正文若提及 Codex 或 Claude Code 的具体加载、优先级、文件位置或限制，必须在写作当天重新读取 REF-005、REF-006 对应官方页面，并将陈述限制在页面直接支持的范围。
- 不复制官方文档的长段落、示例配置或表格；本书使用原创目录、案例、图示和检查表。
- 不在本章记录真实用户路径、私有仓库内容、密钥、访问令牌或内部聊天记录。
- 本书的目录模式、状态同步和交接流程标为工程扩展；若无法用自动检查证明，就写明人工审查条件。
风险与下一阶段输入
| 风险 | 预防措施 | 交给的阶段 |
|---|---|---|
| 将当前产品加载行为写成永久事实 | 在 Draft 与 Fact Check 当天重新读取官方文档，并记录 URL、访问日期与限定用途。 | Fact Check |
| 将仓库文档误当作权限控制 | 正文明确“指令是上下文，不是强制机制”，并链接权限章节。 | Chapter Outline、Technical Review |
| 把项目目录复述成无边界清单 | 为每个目录说明问题、更新者、输入输出与不负责的事项。 | Chapter Outline、First Draft |
| 交接记录与实际进度脱节 | 案例包含状态冲突和验证证据优先级。 | Example Plan、Evaluation |
| 上下文文件过长或相互矛盾 | 设计读取顺序、最小字段和定期清理点；不声称自动解决冲突。 | Chapter Outline、Language Editing |
Research 完成检查
- [x] 读者问题、范围、非范围与章节出口明确。
- [x] Codex 与 Claude Code 的公开项目指令事实已使用当日官方文档限定范围。
- [x] 来源观点、产品行为与本书目录模型分开记录。
- [x] 已规划图示、交接案例、验证方式、风险和后续阶段输入。
- [x] 未引入未经写作当天官方资料核验的动态产品能力、价格、版本或权限承诺。