AI Coding 不是失忆问题，而是真理源失控问题

从产品定义到本地开发控制的资产归属、职责边界与真理源分层

类型：研究系列成稿，不构成当前项目工程入口、执行基线或共享真理源。

前言

这大半年我业余一直在做一个 AI Coding 项目。项目推进过程中，我前后换过不少工具：VS Code、Cursor、Windsurf、Antigravity、Claude Code CLI、Codex App / CLI。一路做下来，我越来越确定，很多问题不是某个工具单独带来的，也不是谁“不会用”这么简单，而是 AI Coding 这种开发方式本身就会不断暴露出来的。和朋友交流、看 X 上的讨论，再加上自己反复踩坑之后，我觉得这里面有不少已经不是个人体验，而是共性问题。所以想把这些零散判断整理出来，写成一个系列，这篇算第一篇。

在 AI Coding 的实践里，很多人会把文档失配、任务漂移、上下文断裂，甚至项目逐步失控，简单归因为“AI 没有记忆”。这个说法不能算错，但太省事了，也容易把问题说偏。更常见的真实情况是：项目内部根本没有形成清晰的文档结构、状态更新机制和控制面边界，结果正式约束、实现现实和临时现场长期混写，AI 不是单纯“忘了”，而是在一个真相源漂移的环境里被迫猜测。

我越来越确定的一点是：UNIX 式的可组合工作流在 AI Coding 里没有过时，传统软件工程里的分层、约束、验证与回写，也不会因为 vibe coding 流行起来就失效。反过来说，AI 的“记忆”也不能只被理解成一个容量问题，它更像一个工程组织问题。甚至可以“武断”地说，作为软件开发过程范式的软件工程方法仍然有效，但需要调整。模型当前能看到的上下文，更接近工作内存；仓库里的文档、规范、skills、任务板、历史记录和各类控制文件，更接近外部存储。这里天然就会遇到信息装载、索引检索、上下文调度、阶段摘要、状态回写与归档这些问题。这个类比不是为了硬套计算机体系结构，而是想说明一个经常被忽视的事实：很多所谓的“AI 失忆”，本质上并不是模型没记住，而是项目根本没有建立起足够清晰的文档结构、控制面更新机制和上下文治理能力。

真正让人机协作失控的，往往是另外几件事：文档没有随着实现持续更新，产品定义、实现现实与任务控制之间缺少清晰的晋升和回写机制，项目内部也没有形成一套真正适合 AI 阅读、理解和执行的文档架构与书写方式。结果就是，AI 并不是单纯“忘了”，而是在一个真相源漂移、正式约束和临时材料混写、控制面失效的环境里被迫猜测，并最终放大了原本就存在的工程失序。这篇文章提出“五层划分”，不是为了再加一套抽象分类，而是想把这些长期混在一起的问题重新拆开，区分产品定义、产品实现、项目落地、仓库治理与本地开发控制各自的职责边界。只有先把这些边界讲清，后面的文档更新、任务推进、阶段总结、晋升和回写，才有可能落到稳定位置。

AI Coding重度爱好者可以先跳到第一部分的“（五）为什么这对 agent 工作有直接价值”

一、目的与适用范围

（一）本文试图回答的问题

1. 本文关注的不是“要不要写文档”，而是 AI Coding 项目中的不同事实应当由哪一类文档和哪一层控制面来承载。

2. 本文要解决的核心问题不是“文档太多”，而是职责混写、真相源漂移和控制面失效。

3. 这些问题一旦长期存在，常见后果至少有三类：

（1）把仓库规则误写成产品能力。

（2）把当前实现状态误写成产品定义。

（3）为了公开、收口或追求表面整洁，误删当前本地开发现场。

1. 因此，讨论 AI Coding 里的文档问题，不能只停留在“AI 有没有记忆”，而必须进一步回答：

（1）哪些内容属于产品定义。

（2）哪些内容属于实现现实。

（3）哪些内容属于项目默认落地。

（4）哪些内容属于共享治理规则。

（5）哪些内容只应留在当前本地开发控制面。

（二）本文范围

1. 本文定义一套五层结构，用来区分产品定义、产品实现、项目落地、仓库治理和本地开发控制。

2. 本文给出的首先是一套职责划分标准，而不是某个工具、某个 IDE 或某个 agent 框架的使用手册。

3. 本文的直接目标，是为 AI Coding 项目建立一个更清晰的分层框架，使文档更新、任务推进、阶段总结、晋升与回写能够落到明确位置。

（三）本文不解决什么问题

1. 不逐项穷举所有典型资产的归属。

2. 不展开第五层内部的保留期限、可迁移性和运行习惯。

3. 不展开第五层向第三层、第四层的晋升机制。

4. 不展开个人本地半自动到团队全自动的治理强度分级。

（四）配套文稿

1. 本文只负责给出主框架。

2. 更细的归属示例、晋升与回写规则、第五层补充说明、治理强度分级，在配套文稿中单独展开。

（五）为什么这对 agent 工作有直接价值

1. 五层划分不是只给人看的概念图，它首先解决的是 agent 读取真理源时的顺序问题。

2. 分层一旦明确，agent 至少能少犯四类典型错误：

（1）把 handoff、任务卡或讨论草稿误当成正式产品约束；

（2）把当前实现现实误抬成长期产品定义；

（3）把仓库治理规则误写成产品能力；

（4）把本地开发现场误删成“准备公开”的清理动作。

1. 对 agent 来说，五层划分最直接的意义有三点：

（1）知道先读什么。面对不同任务，至少能先区分产品定义、实现现实、治理规则和本地现场，不再把所有材料混成同一优先级。

（2）知道信什么。出现冲突时，agent 不必继续凭感觉猜，而是能按层级判断哪一层提供上位约束，哪一层只描述当前现场。

（3）知道写回哪里。阶段总结、状态回写、规则更新和本地 handoff 不再混写到同一个地方，减少后续恢复和审查时的二次混乱。

4. 也正因为如此，五层划分的价值并不止于文档整理。它实际上是在给 agent 提供一套更稳定的读取路径、判断边界和回写位置。

二、结构概览

（一）产品域

1. 第一层：产品定义层。

2. 第二层：产品实现层。

（二）项目桥接域

1. 第三层：项目落地层。

（三）工程复用域

1. 第四层：仓库治理层。

2. 第五层：本地开发控制层。

（四）结构原则

1. 第一层和第二层共同构成产品主线：

（1）第一层定义产品。

（2）第二层实现产品。

1. 第三层不定义产品本体，只定义本项目怎样承载、组织和默认运行这个产品。

2. 第四层和第五层不属于产品本体：

（1）第四层解决共享协作、验证和收口。

（2）第五层解决本地开发现场的连续性。

三、五层的正式定义

（一）第一层：产品定义层

1. 这一层回答：产品是什么。

2. 它负责定义：

（1）产品目标。

（2）核心对象。

（3）核心运行模型。

（4）核心职责边界。

（5）长期稳定语义。

1. 默认规则：

（1）默认属于共享仓库内容。

（2）是否进入 public 仓库由发布策略决定。

（3）变更门槛最高。

（4）不允许被其他层反向改写。

（二）第二层：产品实现层

1. 这一层回答：产品目前被实现成什么样。

2. 承载内容：

（1）源代码。

（2）测试。

（3）运行脚本。

（4）当前技术债和未完成迁移。

1. 它是产品的直接交付层。

2. 默认规则：

（1）默认属于共享仓库内容。

（2）是否进入 public 仓库由发布策略决定。

（3）必须服从第一层的产品定义。

（三）第三层：项目落地层

1. 这一层回答：本项目怎样承载、组织并默认运行这个产品。

2. 承载内容：

（1）默认工作区映射。

（2）默认入口。

（3）默认工件落点。

（4）默认目录组织和打包方式。

（5）本项目特有的落地约定。

1. 它是桥接层。

2. 默认规则：

（1）默认属于共享仓库内容。

（2）是否进入 public 仓库由发布策略决定。

（3）不得重写第一层。

（4）不得伪装成第四层的协作规则。

（四）第四层：仓库治理层

1. 这一层回答：这个仓库怎样被协作、验证、保护和收口。

2. 承载内容：

（1）分支纪律。

（2）worktree 纪律。

（3）session 纪律。

（4）Task Packet 模板。

（5）preflight、check、PR ready、merge gate。

（6）CI、issue / PR 模板、回滚规则。

1. 它是共享工程规则层。

2. 默认规则：

（1）默认属于共享仓库内容。

（2）若目标仓库为 public，公开前应脱敏。

（3）不得被误写成产品定义或项目落地内容。

1. 允许写入的内容：

（1）任务协议。

（2）白名单与验收标准。

（3）分支、worktree、session 与收口规则。

（4）检查脚本、CI 规则、Issue / PR 模板。

（5）可跨项目复用的协作模板与门禁。

1. 禁止写入的内容：

（1）产品语义和产品对象定义。

（2）当前一次会话的临时讨论结论。

（3）某个单一工具专属的临时操作步骤。

（4）把 Codex、Claude、某个 IDE 或某个 swarm 命令写成仓库治理本体。

（五）第五层：本地开发控制层

1. 这一层回答：为了让当前本地开发现场继续运转，工作目录里必须保留什么。

2. 承载内容：

（1）任务板。

（2）lessons。

（3）运行中的 Task Packet 实例。

（4）讨论草稿。

（5）本地日志和临时运行态工件。

（6）本地 Agent 记忆和会话态。

1. 它的结构可复用，但实例内容通常不复用。

2. 默认规则：

（1）应保留在当前开发目录。

（2）默认不进入共享提交范围。

（3）若目标仓库为 public，则默认不进入 git 历史。

（4）不得因为准备公开或准备收口而被物理清空。

1. 允许写入的内容：

（1）当前 todo、lessons、阶段结论。

（2）运行中的任务实例、session bundle、临时日志。

（3）当前本机的本地 settings、会话记忆、恢复索引。

（4）只服务当前开发现场的讨论草稿和验证产物。

1. 禁止写入的内容：

（1）正式产品定义。

（2）正式共享治理规则。

（3）需要长期共享和稳定引用的公共协议。

（4）任何默认应进入 public 仓库的内容。

四、为什么需要第五层

（一）只分产品、项目和治理不够

1. 这样会把产品代码和测试现实挤到一个尴尬位置。

2. 结果通常只有两种：

（1）把代码现实直接当成产品定义。

（2）把代码实现错误地排除出产品主线。

（二）即使分到四层也不够

1. 即使已经把产品定义、产品实现、项目落地和仓库治理分开，AI Coding 项目里仍然会长期存在一组只服务当前开发现场的材料。

2. 这些材料包括：

（1）tasks/

（2）tmp/coordination/

（3）tmp/discussion/

（4）docs/logs/

（5）本地 settings。

（6）本地 Agent 记忆。

1. 这些材料不能并入产品，也不能并入正式共享治理规则。

第五层的意义就在这里。它不是“垃圾层”，也不是“临时层”，而是本地开发连续性层。很多项目真正出问题，不是因为这层不存在，而是因为它一直存在，却没有被正名，于是要么被误当成正式文档，要么在准备公开时被顺手清掉。

五、判定方法

（一）总原则

1. 不能只靠目录名判层。

2. 必须按职责判层。

3. 一个目录若天然混层，应按“默认归属 + 例外说明”处理。

（二）判定顺序

1. 它是否在定义产品本体。

2. 它是否在承载产品代码、测试和运行现实。

3. 它是否在定义本项目如何承载和默认运行这个产品。

4. 它是否在规定仓库怎样协作、怎样验证、怎样收口。

5. 它是否只是在维持当前本地开发现场继续运转。

（三）判定不是价值判断

1. 判入第五层，不等于“低价值”。

2. 判入第四层，也不等于“比第二层更重要”。

3. 五层判定只回答职责归属，不回答价值高低。

六、层间关系与冲突处理

（一）主线关系

1. 第一层定义产品。

2. 第二层实现产品。

3. 第三层组织本项目怎样承载并默认运行这个产品。

（二）控制关系

1. 第四层约束前三层在仓库里的协作方式。

2. 第五层保证当前本地开发现场能够持续运转。

（三）复用关系

1. 第一层和第二层默认属于产品专属层。

2. 第三层是桥接层：

（1）方法和模板可以复用。

（2）具体内容通常项目专属。

1. 第四层和第五层属于工程复用层：

（1）第四层的规则、模板、脚本、门禁可以复用。

（2）第五层的目录结构、记录机制、恢复路径可以复用。

（四）冲突优先级

1. 当产品定义和产品实现冲突时，第一层提供上位约束。

2. 当项目落地方式与产品定义冲突时，以第一层为准。

3. 当项目落地描述与当前代码现实冲突时，第二层优先回答“当前到底实现成了什么”，第三层应修正或标注仍在迁移中。

4. 第四层可以约束协作方式，但不能重写产品语义。

5. 第五层可以影响当前现场恢复顺序，但不能冒充正式权威来源。

（五）共享仓库与 public 仓库的区分

1. “共享仓库内容”指默认可以进入团队共享 git 历史的内容。

2. “进入 public 仓库”是更严格的条件。

3. 在 public 仓库语境下，进入 git 历史通常就意味着对外公开。

4. 因此，涉及第五层时，默认规则必须优先写成：

（1）是否进入共享提交范围。

（2）若仓库为 public，是否允许进入 git 历史。

（六）工具适配器边界

1. Codex App swarm、Codex CLI、Claude Code、Cursor agent 等都属于执行适配器，不属于五层定义本体。

2. 五层结构定义“资产是什么”；工具适配器只回答“当前用什么执行器去操作这些资产”。

3. 第四层和第五层必须保持工具无关。

4. 如果仓库中必须保存某个工具的适配脚本或接线命令，它们只能作为“适配器实现”，不能充当第四层规则本体，更不能进入第一层到第三层。

七、一个真实误判案例

（一）误判动作

1. 在准备 public 仓库时，把第五层内容视为“既然不该公开，就可以从当前工作目录拿掉”。

（二）错误后果

1. tasks/

2. tmp/coordination/

3. tmp/discussion/

4. docs/logs/

5. .claude/

这些内容一旦从当前开发目录物理移除，会直接伤害持续开发能力。任务状态断了，接力断了，局部结论丢了，恢复路径也跟着丢了。表面上看仓库更“干净”了，实际上只是把开发现场抹掉了。

（三）修正规则

1. 第五层默认不进入共享提交范围。

2. 若目标仓库为 public，第五层默认不进入 git 历史。

3. 但第五层必须保留在当前开发目录。

4. 公开动作默认是限制可见性，不是物理删除。

八、最小实施要求

1. 不把五层写成五个完全同轴并列层。

2. 文稿和实践里都应明确三大域：

（1）产品域。

（2）项目桥接域。

（3）工程复用域。

1. 第一层和第二层属于产品主线，不得被第三层、第四层或第五层反向改写。

2. 第三层是桥接层，可复用的是方法和模板，不是项目内容本身。

3. 第四层和第五层应被优先设计成可跨项目复用的工程资产。

结语

五层划分解决的，不是“文档要不要写”，而是“不同事实应当由哪一类资产承载、由哪一层控制面负责”。这一步的意义，在于先把职责边界收住，避免产品定义、实现现实、治理规则和本地现场继续混成一团。边界分清以后，下一步要处理的，才是这些不同类型的资产最终由什么仓库结构来承载，以及产品仓和控制仓如何分离。

如果这一篇是“先把问题拆开”，那么下一步就该讨论“拆开以后，仓库和真理源该怎么落”。这也是后续文章真正要继续回答的问题。