第 3 章 Chapter Outline：仓库即 Agent 上下文

本文件是章节写作蓝图。“仓库即 Agent 上下文”是本书的工程模型，而非某一产品的官方标准。凡涉及 Codex 或 Claude Code 的具体加载行为，正文必须在写作当天重新核验 REF-005、REF-006，并限定在来源直接支持的范围内。

章节契约

读者完成后的能力： 能把项目目标、稳定规则、可变状态、历史决策、正式工件与校验结果放进职责清晰的仓库路径；能让新执行者以可检查的证据恢复一项中断任务；也能说明这种目录结构为什么不是权限控制或正确性保证。

前置知识： 已阅读第 1 章，理解 Harness 需要状态、工件和验证；已阅读第 2 章，理解模型提议、Harness 编排和运行环境的责任不同。

章节边界： 本章讨论仓库文件如何组织长期项目上下文和交接。它不定义不同 Agent 的完整指令优先级，不实现上下文窗口预算、记忆检索、状态机、权限系统或 Git 工作流；这些分别留给第 05、06、07、10、12、22、27 和 45 章。

小节蓝图

1. 聊天结束后，任务为什么会失去可恢复性

• 读者问题： 一个新 Agent 接手“继续第 3 章”时，为什么只看到一句任务描述还不够？
• 叙述任务： 用“Research Brief 已完成、Outline 尚未开始”的原创教学场景说明目标、已完成证据、风险和下一步若只存在对话中，就难以审查、恢复或交接。
• 证据边界： 场景是本书的设计演练，不是某个真实 Agent 的运行轨迹，也不推断模型是否记得先前会话。
• 计划工件： “只给任务句”与“给可读取项目工件”两列的信息缺口表。
• 验证： 读者能列出恢复工作至少需要的目标、当前状态、下一任务、相关工件和校验命令。
• 过渡： 要恢复任务，先要区分不同信息的稳定性和责任，不能把所有内容塞进一个说明文件。

2. 让每类信息回答一个问题：规则、状态、历史与正式工件

• 读者问题： 哪些信息应长期稳定，哪些应该频繁更新，哪些只能作为历史证据？
• 叙述任务： 建立五类仓库上下文：稳定规则、可变项目状态、历史决策与审查、正式书稿和可运行/可校验工件。对每类说明回答的问题、更新者、更新触发条件与不负责事项。
• 证据边界： 分类表是本书的工程建议，不是通用文件系统标准；不得把历史记录误写为当前真相。
• 计划工件： “问题—路径—更新时机—证据—非职责”责任表。
• 验证： 每一类均有明确的读者问题和更新边界；读者能解释为什么 CURRENT_STATE.md 不应替代测试输出，为什么审查记录不应替代现行规则。
• 过渡： 分类之后，需要一个最小可导航目录，让执行者知道从何处开始读。

3. 根入口不是知识库：设计可导航的最小项目上下文

• 读者问题： 为什么根入口文件应给出阅读顺序，而不复制整套书稿、状态和历史？
• 叙述任务： 以本书的 AGENTS.md、CLAUDE.md、AI_BOOTSTRAP.md、.context/、.memory/、.ai/、docs/、examples/ 和 scripts/ 为原创目录案例，解释每个路径的输入、输出与边界。
• 证据边界： REF-005 只支持 Codex 的 AGENTS.md 项目指令发现与组合机制；REF-006 只支持 Claude Code 的 CLAUDE.md 持久项目指令上下文。目录角色、阅读顺序和分层方式均为本书扩展，不外推为任意 Agent 的实现。
• 计划工件： 最小目录责任图与“入口 → 规则 → 当前状态 → 当前章节工件”的阅读清单。
• 验证： 每个目录都能回答一个问题，且入口文件只链接或指向权威位置，不制造第二份状态或规则副本。
• 过渡： 目录提供位置，下一步还要给出从读取到回写的恢复动作顺序。

4. 从读取到交接：把恢复过程写成可检查工作流

• 读者问题： 新执行者如何既不重复研究，也不把未核验计划当作完成内容？
• 叙述任务： 定义最小恢复流程：读取入口和规则；定位 CURRENT_STATE.md、NEXT_TASK.md、progress.md；读取当前任务的 Research Brief 与模板；领取一个可验收任务；完成工件和校验；同步状态并交接。
• 证据边界： 流程是本书的工作流建议，不保证任何 Agent 都会自动遵循；“读取到文件”不是完成、授权或事实正确的证明。
• 计划工件： Mermaid 图 chapter-03-repository-context-flow.mmd，区分稳定规则、动态状态、历史记录、正式工件和校验反馈；图中必须不存在“指令文件 → 自动授权”的箭头。
• 验证： 以本章的 Research → Outline 交接为例，读者能从输入工件定位下一项任务，并说明完成后至少更新哪些状态文件。
• 过渡： 即使流程完整，上下文仍可能相互矛盾或变得过期，需要规定证据优先级和升级方式。

5. 冲突、过期与敏感信息：文件并不会自动成为事实

• 读者问题： 当状态表、交接记录和实际校验结果不一致时，该相信哪一个？
• 叙述任务： 提出“可复现的直接证据优先于叙述性状态”的排查顺序：先运行或读取可复现校验，再更新状态文件；同时说明版本化文档仍可能陈旧、重复或错误。
• 证据边界： 这是本书的排查建议；不声称自动检查能证明全部事实，也不讨论具体 Git 冲突解决命令。
• 计划工件： 状态冲突决策表，涵盖“阶段表滞后”“链接失效”“来源过期”“私密数据不应入库”四种情形。
• 验证： 每一种情形都有一个可观察依据、一个应更新的工件和一个不能据此断定的边界。
• 过渡： 最后把目录、工作流和冲突处理组合为一次跨会话接手演练。

6. 原创案例：接手第 3 章的 Outline 任务

• 读者问题： 一套仓库上下文在真实的编辑任务中怎样减少重复和臆测？
• 叙述任务： 走读本书的教学场景：前一位执行者完成 Research Brief 与候选来源；下一位先验证状态和来源边界，再创建 Chapter Outline；不把研究计划扩写成未核验正文；完成后更新进度、下一任务和交接记录。
• 证据边界： 这是本项目的原创、可审查案例；它不证明 Codex、Claude Code 或任何 Agent 会自动执行这些步骤。
• 计划工件： 03-repository-as-agent-context.example-plan.md，列出输入路径、最小动作、无副作用边界、预期输出与验证命令。若后续实现自动检查，仅检查文件与状态一致性，不模拟权限控制或模型行为。
• 验证： 案例的每一步均能指向已有或计划创建的仓库工件；未核验事实保留为 TODO 或下一阶段任务。
• 过渡： 第 4 章将把这种可恢复性提升为更一般的可靠性原则；第 06、07、10 章再分别深化上下文筛选、记忆与状态机。

章节工件状态

1. 已完成：Research Brief 与候选参考资料，已将官方产品指令事实和本书目录模型分开。
2. 本阶段完成：Chapter Outline；为图示、示例、事实核验、正文和审查定义了可验收的输入输出边界。
3. 已完成：Fact Check、Diagram Plan、Example Plan 与 First Draft；正文将来源事实、工程模型、教学案例和未验证范围分层。当时图示与示例尚未进入实施审查。
4. 已完成：Technical Review，修正了 Draft 校验状态与 Fact Check 历史范围的状态漂移；记录位于 .memory/reviews/2026-07-15-chapter-03-technical-review.md。
5. 已完成：Example Implementation，建立纯内存 recoverTask 预检、5 项 Node 内置测试和演示入口；记录位于 .memory/reviews/2026-07-15-chapter-03-example-integration.md。
6. 已完成：Diagram Review；实际导出 SVG/PNG 并视觉检查节点、箭头、虚线反馈和文字，记录位于 .memory/reviews/2026-07-15-chapter-03-diagram-review.md。
7. 已完成：Language Editing；统一章节编号、交接术语与阶段性验证记录，且未改变来源归因、示例行为、图示接口或技术结论，记录位于 .memory/reviews/2026-07-15-chapter-03-language-edit.md。
8. 已完成：Final Review 与最终 Validation；示例、图源、来源边界、审查记录和项目状态已跨工件核对，记录位于 .memory/reviews/2026-07-15-chapter-03-final-review.md。

Outline 完成检查

• [x] 每个主要小节包含读者问题、证据边界、计划工件、验证和过渡。
• [x] 官方 Codex / Claude Code 行为与本书目录模型、案例和建议明确分开。
• [x] 明确了与第 04、05、06、07、10、12、22、27、45 章的边界，未提前展开其职责。
• [x] 图示和示例不把 Markdown 规则表述为权限控制、自动执行或正确性证明。
• [x] 状态冲突以可复现证据为优先，且不把计划写成已核验正文。