当 AI 编程助手越来越强大，一个关键问题浮出水面：它能接住别人（或昨天的自己）没干完的活吗？

---

问题的起源

真实开发不是一次会话就干完的。
你昨天写了一半，今天开新会话，agent 需要从仓库状态里搞清楚：

• 项目是干什么的？
• 怎么启动？
• 哪些功能已经做了？
• 哪些还没做？
• 下一个该做什么？

如果 agent 要靠"猜"来回答这些问题，那它本质上是在重新发现已经存在的信息。
这既浪费时间，又容易出错。

---

实验设计

我们在同一个 Electron 知识库应用上做了两组对照实验，任务完全一致——实现三个功能：

功能	描述
kb-005 文档导入	从本地导入 .txt/.md 文件
kb-006 文档详情视图	点击文档查看完整内容
kb-007 文档持久化	重启后文档仍在

两组实验的区别只在于：仓库里有没有"可读的上下文"。

---

实验组 A：弱 Harness（Baseline）

仓库里有什么？
├── 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：开全新会话，只说了一句：

继续开发。

发生了什么？

┌─────────────────────────────────────────────────────────┐
│  会话 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）

仓库里有什么？
├── 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：

## 本轮会话做了什么
- kb-005 文档导入：已完成并验证通过

## 没做什么（遗留功能）
- kb-006 文档详情视图：未开始
- kb-007 文档持久化：未开始

## 下一步
1. 实现 kb-006：文档详情视图
2. 实现 kb-007：文档持久化

会话 B：开全新会话，发送：

请先阅读 session-handoff.md、feature_list.json、ARCHITECTURE.md、PRODUCT.md，
然后继续开发未完成的功能。

发生了什么？

┌─────────────────────────────────────────────────────────┐
│  会话 B 的探索过程                                       │
│                                                         │
│  Step 1: 读 session-handoff.md  → 知道了！kb-005 已完成  │
│                                   下一步是 kb-006        │
│  Step 2: 读 feature_list.json   → 确认功能状态           │
│  Step 3: 读 ARCHITECTURE.md     → 确认项目结构           │
│  Step 4: 直接开始写代码！        → 零浪费                  │
└─────────────────────────────────────────────────────────┘

---

数据对比

                    弱 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. 最重要的三行信息

做了什么：kb-005 文档导入 ✓
没做什么：kb-006 文档详情、kb-007 文档持久化
下一步：从 kb-006 开始

就这三行，节省了 agent 6+ 步探索。

4. 一份大指令文件不够

如果把所有规则塞进一个巨大的 system prompt，agent 会"迷失在细节里"。
仓库中的多个小文件（ARCHITECTURE.md、PRODUCT.md、session-handoff.md）各司其职，按需读取，效果更好。

---

结论

仓库必须是唯一的事实来源。

不是某个 agent 的记忆，不是聊天记录，不是某个巨大的指令文件——而是仓库里的结构化文档。

当你的 agent 能在一分钟内搞清"这是哪、到哪了、下一步去哪"，你就有了一个真正可交接的 AI 工作流。