当 AI 编程助手越来越强大，一个关键问题浮出水面：它能接住别人（或昨天的自己）没干完的活吗？
问题的起源
真实开发不是一次会话就干完的。
你昨天写了一半，今天开新会话，agent 需要从仓库状态里搞清楚：
- 项目是干什么的？
- 怎么启动？
- 哪些功能已经做了？
- 哪些还没做？
- 下一个该做什么？
如果 agent 要靠"猜"来回答这些问题，那它本质上是在重新发现已经存在的信息。
这既浪费时间，又容易出错。
实验设计
我们在同一个 Electron 知识库应用上做了两组对照实验，任务完全一致——实现三个功能：
| 功能 |
描述 |
| kb-005 文档导入 |
从本地导入 .txt/.md 文件 |
| kb-006 文档详情视图 |
点击文档查看完整内容 |
| kb-007 文档持久化 |
重启后文档仍在 |
两组实验的区别只在于：仓库里有没有"可读的上下文"。
实验组 A：弱 Harness（Baseline）
1
2
3
4
5
6
7
8
9
10
11
12
13
|
仓库里有什么？
├── main.js # 代码
├── preload.js # 代码
├── index.html # 代码
├── renderer.js # 代码
├── package.json # 依赖
└── task-prompt.md # 任务描述
仓库里没有什么？
✗ ARCHITECTURE.md — 没有架构文档
✗ PRODUCT.md — 没有产品文档
✗ session-handoff.md — 没有交接文件
✗ feature_list.json — 有，但 agent 不知道要先读
|
会话 A：agent 完成了文档导入（kb-005），然后被中断。没有写任何交接文件。
会话 B：开全新会话，只说了一句：
发生了什么？
1
2
3
4
5
6
7
8
9
10
11
12
|
┌─────────────────────────────────────────────────────────┐
│ 会话 B 的探索过程 │
│ │
│ Step 1: 读 main.js → 哦，这是 Electron 应用 │
│ Step 2: 读 package.json → 启动命令是 npm start │
│ Step 3: 读 preload.js → 用 contextBridge 暴露 API │
│ Step 4: 读 index.html → 这是 UI 布局 │
│ Step 5: 读 renderer.js → 哦，已经有一个导入按钮了 │
│ Step 6: 读 feature_list.json → kb-001~004 已完成 │
│ Step 7: 对比代码差异 → 所以 kb-005 做完了？ │
│ Step 8: 终于开始写代码... → 但已经过去很久了 │
└─────────────────────────────────────────────────────────┘
|
核心问题：
agent 花了大量时间在重新发现——项目结构、启动方式、数据流、已完成的功能。
这些都是会话 A 已经知道的信息。
实验组 B：强 Harness（Improved）
1
2
3
4
5
6
7
8
9
10
11
|
仓库里有什么？
├── ARCHITECTURE.md # 项目架构、数据流、IPC 接口清单
├── PRODUCT.md # 产品功能范围和当前阶段目标
├── AGENTS.md # 启动命令、工作规则
├── feature_list.json # 功能状态（已更新）
├── session-handoff.md # 本轮做了什么、没做什么、下一步
├── main.js # 代码
├── preload.js # 代码
├── index.html # 代码
├── renderer.js # 代码
└── task-prompt.md # 任务描述
|
会话 A：
同样完成了文档导入（kb-005），中断前更新了 session-handoff.md 和 feature_list.json。
会话 B 的 session-handoff.md：
1
2
3
4
5
6
7
8
9
10
|
## 本轮会话做了什么
- kb-005 文档导入：已完成并验证通过
## 没做什么（遗留功能）
- kb-006 文档详情视图：未开始
- kb-007 文档持久化：未开始
## 下一步
1. 实现 kb-006：文档详情视图
2. 实现 kb-007：文档持久化
|
会话 B：开全新会话，发送：
1
2
|
请先阅读 session-handoff.md、feature_list.json、ARCHITECTURE.md、PRODUCT.md，
然后继续开发未完成的功能。
|
发生了什么？
1
2
3
4
5
6
7
8
9
|
┌─────────────────────────────────────────────────────────┐
│ 会话 B 的探索过程 │
│ │
│ Step 1: 读 session-handoff.md → 知道了！kb-005 已完成 │
│ 下一步是 kb-006 │
│ Step 2: 读 feature_list.json → 确认功能状态 │
│ Step 3: 读 ARCHITECTURE.md → 确认项目结构 │
│ Step 4: 直接开始写代码！ → 零浪费 │
└─────────────────────────────────────────────────────────┘
|
数据对比
1
2
3
4
5
6
|
弱 Harness 强 Harness
───────── ─────────
接手所需文件数 ████████ 6-8 ██ 2-3
重新发现次数 ██████ 6+ ░ 0~1
重复工作比例 ██████ ~30% ░ ~5%
上下文理解准确度 可能有偏差 准确无误
|
关键洞察
1. 代码不是文档
代码能告诉你"怎么做"，但很难告诉你"做了什么、为什么没做、下一步做什么"。
一个 500 行的 main.js 不会告诉你 kb-006 还没开始——agent 必须自己推断，而推断经常出错。
2. 交接文件是"会话的 checkpoint"
session-handoff.md 就像一个游戏存档。
没有它，每次新会话都相当于从第一关重打。
有了它，agent 可以直接从上次中断的地方继续。
3. 最重要的三行信息
1
2
3
|
做了什么：kb-005 文档导入 ✓
没做什么：kb-006 文档详情、kb-007 文档持久化
下一步：从 kb-006 开始
|
就这三行，节省了 agent 6+ 步探索。
4. 一份大指令文件不够
如果把所有规则塞进一个巨大的 system prompt，agent 会"迷失在细节里"。
仓库中的多个小文件（ARCHITECTURE.md、PRODUCT.md、session-handoff.md）各司其职，按需读取，效果更好。
结论
仓库必须是唯一的事实来源。
不是某个 agent 的记忆，不是聊天记录，不是某个巨大的指令文件——而是仓库里的结构化文档。
当你的 agent 能在一分钟内搞清"这是哪、到哪了、下一步去哪"，你就有了一个真正可交接的 AI 工作流。