AI Coding 长期项目的上下文治理：别把所有东西都塞进一个会话
大家好，我是 Eleven，8 年 Java 后端开发工程师，正在系统学习 Python 大模型开发与 AI Coding 工程化。
最近我在用 Codex 推进个人项目 ContextPilot，也会持续记录AI Coding 工程化、多会话协作、上下文治理、API 契约和工程初始化这些真实实践。
这篇文章想聊一个长期 AI Coding 项目很容易遇到的问题：
会话越来越长以后，怎么让 AI 继续稳定工作？
更多关于 Java 后端转向 AI 应用开发、Python 大模型开发和 AI Coding 工程化的学习笔记，我会同步整理在公众号：转行AI的Java工程师。
上一篇掘金文章，我用一个 VibeTodoDemo 讲了怎么用 3 个 Codex 会话跑通一个最小 AI Coding 闭环：
总控台 -> 产品/需求台 -> 前端开发台 -> 总控验收
这套流程解决的是“项目怎么开始跑起来”。
但项目真正跑起来以后，会出现另一个问题：
所有上下文都放进聊天记录里，后面反而越来越难推进。
这篇文章不讲模型测评，也不讲提示词技巧，而是记录我在 ContextPilot 里做的一套上下文治理方法：
- 对话是工作区，文档是长期记忆；
- 总控台只保留决策，不承接全文；
- 阶段结束时生成接力包；
- 新阶段优先开新会话；
- 旧口径必须显式清理；
- Subagent、记忆、自动化不能替代项目事实文档。
为什么长上下文会变成问题？
AI Coding 项目刚开始时，长上下文看起来很有安全感。
需求在对话里，设计在对话里，修改过程在对话里，报错信息也在对话里。
你会觉得：
太好了，AI 什么都知道。
但项目做久以后，情况会变得不一样。
在 ContextPilot 里，我曾经同时维护过这些长期会话：
- 总指挥台；
- 产品设计；
- API 契约；
- 前端；
- 后端；
- 阶段复盘和资料整理。
每个会话都有自己的角色，这本身没问题。
真正的问题是：如果所有过程材料都塞回主会话，主会话会越来越像一个没有整理过的垃圾桶。
典型表现有 5 个：
- 响应变慢；
- 旧口径被重新引用；
- 中间稿和最终稿混在一起；
- 关键决策被大量过程文本淹没；
- 新阶段启动时，不知道该读哪些、不该读哪些。
这里最危险的不是 AI “不知道”，而是它“记得一个已经过期的版本”。
比如：
- 早期说某个字段必填，后来已经改成选填；
- 早期计划做完整功能，后来 MVP 收窄了；
- 某个原型入口后来被删掉，但旧对话里还存在；
- 某个方案只是讨论过，并没有确认落地；
- 某篇内容还是草稿，后来已经有最终发布版。
如果不做上下文治理，新会话很容易把这些过期信息重新捡起来。
我的核心原则：对话是工作区，文档是长期记忆
我现在越来越明确一个原则：
Codex 会话适合讨论、执行、检查和验收，但不适合作为项目唯一事实来源。
长期项目里，真正需要保留的内容应该回到项目文件。
在 ContextPilot 里，我大概这样分层：
| 信息类型 | 放在哪里 |
|---|---|
| 产品范围 | docs/product/ |
| API 契约 | docs/api/ |
| AI Coding 工作流 | docs/vibe-coding/ |
| 阶段接力包 | docs/**/checkpoints/ |
| 工程规则 | AGENTS.md / .ai/ |
| 内容素材 | docs/content/ |
| 临时讨论和执行过程 | 当前会话 |
这不是为了把项目文档搞复杂。
恰恰相反，这是为了让新会话少读一点，但读到正确的东西。
总控台不要承接全文
多会话协作里，很容易犯一个错误：
什么都往总控台同步。
前端完成了，贴一大段。
后端完成了，贴一大段。
验收发现问题，贴一大段。
资料整理完，也想把完整过程贴回总控台。
短期看，这样很有安全感。
长期看，总控台会被拖垮。
我现在给总控台定的规则是：
总控台保留：
- 阶段判断
- 关键决策
- 产物路径
- 待确认问题
- 风险点
- 下一步动作
总控台不长期承接：
- 完整文章正文
- 完整代码 diff
- 大段命令输出
- 图片素材多轮尝试
- 子会话完整执行日志
- 已废弃方案
- 没有形成决策的闲聊
子会话汇报时，使用短摘要即可：
任务已完成。
产物：
- 文件路径：...
需要总控确认：
- ...
风险点：
- ...
不需要同步的内部过程已保留在本会话。
这个格式很朴素，但很有效。
因为总控台真正需要的是决策信息，不是所有过程噪音。
阶段结束后，生成接力包
当一个阶段完成，或者某个会话明显变长，我会生成一份接力包。
接力包不是流水账，也不是完整聊天记录。
它的作用是：让下一个会话能以最小上下文接手。
我现在使用的模板是：
# 标题
记录日期：
维护者：
## 1. 当前阶段结论
## 2. 已完成事实
## 3. 当前有效口径
## 4. 未完成事项
## 5. 下一阶段建议
## 6. 新会话必须读取的文件
## 7. 已废弃或不可继续引用的旧口径
## 8. 需要用户确认的问题
这个模板里，我最看重第 7 项：
已废弃或不可继续引用的旧口径。
很多接力文档只会写“现在是什么”，但长期项目更需要写清楚“什么不能再用”。
比如：
已废弃口径：
- 不再使用旧的 docs/01_* 编号文件作为新任务入口。
- 不再把归档会话理解为压缩上下文。
- 不再把某个字段当作必填，因为产品文档已经改为非必填。
- 不再把某个实现方案当成最终方案，因为它只是早期讨论稿。
如果不写这一节，新会话可能会从旧材料里捞出已经过期的内容。
新阶段优先开新会话
会话变长以后，我不建议继续在旧会话里硬撑。
更稳的流程是：
旧会话
-> 生成阶段接力包
-> 旧会话作为历史参考
-> 新建下一阶段会话
-> 新会话只读取接力包和必要 docs
注意，这里有一个很容易误解的点：
归档旧会话，不等于压缩旧会话的上下文。
归档更多是管理会话列表。
真正降低上下文负担的是：
接力包 + 新会话 + 只读取必要文件。
新会话不是从零开始。
如果你有清晰的文档地图和接力包，它是从一个更干净的入口开始。
新会话应该读什么？
我现在不建议新会话一上来就扫描整个 docs/。
更推荐按角色和任务读取。
例如一个新的总控会话，可以先读：
1. AGENTS.md
2. .ai/README.md
3. docs/README.md
4. docs/vibe-coding/context-governance.md
5. docs/vibe-coding/thread-registry.md
6. 最新阶段接力包
7. 与当前任务直接相关的产品、API、前端或后端文档
如果是前端会话，就读取前端接力包和相关产品/API 文档。
如果是后端会话，就读取后端接力包、API 契约和相关后端规则。
如果是内容相关会话，就读取内容规划、阶段日志和对应文章文件。
原则是：
让 AI 少读一点，但读到当前任务真正需要的事实。
信息也要分层：事实、摘要、可丢弃
我现在会把信息分成三类。
1. 必须保留为事实
这类信息必须写进项目文件：
- 已确认产品范围；
- 已确认 API 字段、错误码、权限规则；
- 已确认技术栈和工程结构；
- 已完成验收的阶段结论；
- Git 分支、提交和发布前检查规则；
- 会影响产品、前端、后端、API 多方的变更。
2. 只需要摘要
这类信息不要原文塞进总控台：
- 子会话执行过程；
- 验证命令完整输出；
- 非关键失败尝试；
- 多轮图片素材尝试；
- 长篇过程汇报。
摘要格式可以是：
状态：
产物路径：
已确认结论：
待确认问题：
风险点：
建议下一步：
3. 可以丢弃或留在专项会话
这类信息不应该进入长期项目记忆：
- 被否决的标题；
- 被否决的图片版本；
- 中间提示词草稿；
- 已修复的临时页面表现；
- 没有形成决策的闲聊和重复说明。
Subagent、记忆、自动化不能替代事实文档
现在 AI Coding 工具里有很多能力，比如 Subagent、记忆、自动化、项目指令。
这些能力都有价值，但它们解决的不是同一个问题。
我目前的理解是：
| 能力 | 更适合解决什么 |
|---|---|
| Subagent | 把探索、测试、日志分析、代码审查等专项任务拆出去，减少主会话噪音 |
| 记忆 | 记录稳定偏好、常用工作方式、技术栈和已知坑点 |
| 自动化 | 做周期检查、任务完成提醒、后台扫描 |
AGENTS.md | 放项目级规则，让 Codex 进入仓库时先知道基本约束 |
docs/ | 存放产品事实、API 契约、阶段结论和可审查的长期项目记忆 |
这里的关键是：
这些能力可以辅助上下文治理，但不能替代项目事实文档。
尤其是产品范围、API 字段、验收结论、上线边界这类信息，必须能被人检查、被 Git 管理、被不同会话共同读取。
不要把“AI 记得”当成“项目已经确认”。
什么时候应该生成新的接力包？
我现在会在这些场景生成接力包：
- 一个阶段完成，比如 MVP 开发验收收口；
- 总控台明显变慢或上下文过长；
- 即将启动 V0.1、V1.0、上线、测试、部署等新阶段；
- 多个子会话状态已经发生变化；
- 关键事实散落在多个会话里；
- 用户准备归档旧会话或新开总控台。
接力包不要写成流水账。
不要放：
- 完整聊天记录；
- 完整代码 diff；
- 大段命令输出；
- 未确认猜测；
- 已废弃但没有标记的方案。
它应该只聚焦：
- 当前阶段判断；
- 已完成事实；
- 未完成风险；
- 下一阶段入口；
- 新会话启动提示；
- 不能继续引用的旧口径。
一个最小可复制方案
如果你也在做长期 AI Coding 项目，可以从这个最小结构开始。
目录上，先准备：
your-project/
AGENTS.md
.ai/
README.md
context.md
module-map.md
done-checklist.md
docs/
README.md
product/
api/
vibe-coding/
context-governance.md
thread-registry.md
checkpoints/
流程上，先做到：
1. 项目事实写入 docs
2. 项目规则写入 AGENTS.md 和 .ai
3. 阶段结束生成 handoff
4. 新阶段开新会话
5. 新会话只读取必要文件
6. 子会话只向总控台同步短摘要
7. 废弃口径必须显式写出来
这套结构不一定适合所有小项目。
如果只是一次性脚本，一个会话足够。
但如果你要做的是长期项目，它会让 AI Coding 从“聊天记录驱动”逐步变成“文档事实驱动”。
小结
长期 AI Coding 项目的问题，不是让 AI 永远记住所有东西。
真正要解决的是：
在每个阶段，让 AI 只读取当前任务真正需要的事实。
我的当前结论：
- 长上下文不等于长期记忆；
- 归档会话不等于压缩上下文；
- 总控台不要承接所有过程材料；
- 接力包要写“已完成”，更要写“不能再用”；
- 新会话不是从零开始，而是从更干净的文档入口开始；
- Subagent、记忆、自动化都不能替代可审查的项目事实文档。
如果上一篇 Todo Demo 解决的是“AI Coding 怎么跑起来”，那这篇解决的是：
跑起来以后，怎么不被自己的上下文拖住。
