Agent 交接上下文

当遇到一些情况不得不中断上下文时，可以采用下面的方式保存。

复制给 Codex / Claude Code / Cursor Agent / 其他 coding agent 使用：

text

请你为下一个接手本项目的 LLM/agent 写一份完整的交接文件，保存为 prompt.txt。

这个 prompt.txt 的目标是：让下一个 LLM/agent 即使没有当前对话历史，也能尽快理解项目背景、当前任务、已完成工作、关键决策、代码结构、问题状态和下一步行动。

请不要只写简短摘要。请写成一份可以直接交给下一个 agent 阅读并继续工作的详细上下文文档。

请在 prompt.txt 中包含以下内容：

1. 项目背景
- 这个项目/科研任务的总体目标是什么？
- 当前研究问题、实验目标或工程目标是什么？
- 用户最终想得到什么结果？
- 相关的领域背景、术语、假设或约束条件是什么？

2. 当前具体任务
- 本轮正在解决的具体问题是什么？
- 用户给你的最新要求是什么？
- 当前任务的输入、输出分别是什么？
- 如果任务有多个子任务，请列出优先级。

3. 已完成的工作
- 你已经做了哪些分析、设计、实验或代码修改？
- 哪些方案已经尝试过？
- 哪些方案被放弃了？为什么？
- 当前哪些结论是比较确定的，哪些只是猜测？

4. 当前文件和代码状态
- 列出重要文件路径，并说明每个文件的作用。
- 说明你修改过哪些文件、改了什么、为什么改。
- 如果有新增文件，也请说明用途。
- 如果项目里有关键函数、类、脚本、配置项，请解释它们的作用。
- 如果当前代码还没跑通，请明确指出卡在哪里。

5. 运行方式
- 如何安装依赖？
- 如何运行主要脚本？
- 如何复现实验或测试？
- 有哪些命令已经运行过？
- 运行结果是什么？
- 如果出现报错，请保留完整或关键报错信息，并解释你对报错原因的判断。

6. 数据、实验和结果
- 使用了哪些数据文件、数据集或输入样例？
- 数据格式是什么？
- 当前实验设置是什么？
- 已经得到哪些结果？
- 结果是否可靠？
- 还有哪些实验需要继续跑？

7. 设计决策和理由
- 当前采用的技术路线是什么？
- 为什么选择这个方案？
- 有哪些替代方案？
- 哪些地方需要下一个 agent 特别小心，不要轻易改动？

8. 未完成事项
- 明确列出下一步应该做什么。
- 每一步最好写成可执行的 TODO。
- 标注哪些是高优先级，哪些是可选优化。
- 如果需要用户确认，也请说明需要确认什么。

9. 风险、坑和注意事项
- 当前任务中有哪些容易误解的地方？
- 哪些代码、数据或实验结果可能有隐藏问题？
- 有哪些路径、环境变量、依赖版本、随机种子、硬编码参数需要注意？
- 有哪些事情你不确定，不能假装确定？

10. 给下一个 agent 的建议
- 请直接告诉下一个 agent 应该从哪里开始读代码。
- 应该先运行什么命令。
- 应该优先验证什么。
- 如果时间有限，最小可行推进步骤是什么？

写作要求：
- 使用中文。
- 结构清晰，使用标题和项目符号。
- 信息要具体，不要泛泛而谈。
- 文件路径、函数名、命令、参数、错误信息要尽量精确。
- 不要省略失败尝试，因为这些对下一个 agent 很重要。
- 不要夸大已完成工作。
- 不要写“我会继续做”之类的话；这是交接文件，不是计划承诺。
- 如果某些信息你不知道，请明确写“未知”或“尚未确认”。
- 最后附上一段“给下一个 agent 的启动提示词”，让下一个 agent 可以直接继续工作。

请现在检查当前项目目录、最近修改的文件、相关代码和命令历史，然后生成 prompt.txt。

version 2:

text

---
name: handoff
description: 为下一个 LLM/agent 生成可直接继续工作的项目交接文件。适用于用户要求 handoff、交接当前项目、保存上下文、切换到新会话或新 agent、保留当前项目状态、生成 prompt.txt 或交接说明等场景。执行时优先检查可访问的项目目录、Git 状态、最近修改、关键代码、日志与实验结果；区分已验证事实、用户提供信息、推断和未知；保留失败尝试、未完成工作和关键命令；最终输出可执行的中文 prompt.txt，帮助下一个 agent 在没有当前对话历史的情况下尽快恢复工作。
---

# Handoff

生成一份面向“下一个 LLM/agent”的项目交接文件，保存当前项目继续工作所需的**最小充分状态**。

目标不是写一篇项目总结，而是让下一个 agent 能够：

- 快速理解项目和当前任务；
- 知道代码现在处于什么状态；
- 避免重复已经失败的尝试；
- 找到关键文件、命令、实验和 blocker；
- 直接从最高优先级未完成事项继续工作。

## 核心规则

1. **禁止编造。** 不要虚构文件路径、函数名、命令、commit、实验结果、错误、版本号、已完成工作或用户决定。不知道时明确写 `未知` 或 `尚未确认`。
2. **优先相信项目现场。** 如果当前环境可以访问项目目录，先检查仓库、代码、日志和输出，再写交接；不要只依赖聊天记忆。
3. **必要时区分信息来源。** 对重要信息使用：
   - `[已验证]`：来自代码、文件、Git、日志或实际命令输出；
   - `[用户提供]`：用户明确说明，但未通过项目现场独立验证；
   - `[推断]`：根据现有证据得到的合理判断；
   - `[未知]`：目前无法确认。
4. **保留进行中的工作。** 对继续工作有价值时，尽量保留准确的文件路径、命令、参数、错误信息、实验设置、未完成配置和关键文本，不要只做抽象总结。
5. **保留失败尝试。** 记录已经尝试但失败、效果差或被放弃的方案，以及为什么停止，避免下一个 agent 无意义地重复。
6. **下一步必须可执行。** 不要只写“继续调试”“继续优化”。应说明先看什么、先运行什么、修改哪里、如何判断成功或失败。
7. **不要写成泛化项目报告。** 只保留对继续工作有帮助的信息；与当前项目无关的章节可以省略或压缩。

## 写交接前先检查现场

如果当前环境能访问项目，先做一次轻量取证。优先检查：

```bash
pwd
git status --short
git branch --show-current
git rev-parse HEAD
git log --oneline -10
git diff --stat
git diff
git diff --cached

然后只阅读与当前任务直接相关的内容，例如：

• README.md、AGENTS.md、CLAUDE.md 等项目说明；
• 当前入口脚本；
• 最近修改文件；
• 配置文件；
• 测试；
• 实验脚本；
• 日志；
• 输出结果。

不要无目的递归扫描大型数据集、checkpoint、虚拟环境、.git、node_modules 等无关目录。

如果 shell history、最近命令或实验日志可以访问，并且对当前任务有帮助，可以检查；如果访问不到，明确写“未能从当前环境确认”，不要猜。

输出要求

最终必须生成文件：

prompt.txt

优先保存到当前项目目录；如果当前项目目录不可访问，则保存到当前工作目录，并在交接文件中说明限制。

默认使用中文，除非用户明确要求其他语言。

以下结构是默认模板。根据项目实际情况裁剪，不需要机械填满每一项。

项目交接文档

0. TL;DR

用最短篇幅说明：

• 项目是什么；
• 当前正在做什么；
• 已经推进到哪里；
• 当前最大的 blocker；
• 下一步最重要动作。

让下一个 agent 在 1 分钟内理解当前状态。

1. 项目背景与目标

说明继续工作真正需要知道的背景：

• 项目总体目标；
• 当前研究 / 实验 / 工程目标；
• 用户最终想得到什么；
• 必要术语、假设和约束。

不要写与当前工作无关的领域科普。

2. 当前任务

说明：

• 用户最新要求；
• 当前具体问题；
• 输入和预期输出；
• 成功标准；
• 子任务及优先级。

需要时使用：

• P0：必须先完成；
• P1：重要；
• P2：可选优化。

3. 当前状态

尽量记录当前真实工作树状态，包括：

• 项目根目录；
• 当前 branch；
• HEAD commit；
• modified / staged / untracked 文件；
• 当前重要 diff；
• 哪些未提交修改不能丢失。

如果无法访问 Git，明确写未知，不要补全。

4. 关键文件与代码

只列出与当前任务直接相关的：

• 文件和目录；
• 脚本；
• 函数；
• 类；
• 配置；
• CLI 参数；
• 环境变量。

对每个关键项说明：

• 它做什么；
• 为什么与当前任务有关；
• 当前状态是什么。

不要罗列整个 repository。

5. 已完成工作与失败尝试

记录：

• 已完成分析、代码修改、实验、调试；
• 部分完成但尚未验证的工作；
• 关键设计决定；
• 已尝试但失败或放弃的方案；
• 为什么失败或停止。

如果很容易重复踩坑，增加：

DO NOT REPEAT

列出没有新证据时不应直接重复的实验、修改或命令。

6. 运行、数据、实验与结果

根据项目实际情况记录：

• 环境和关键依赖版本；
• 安装命令；
• 运行 / 复现命令；
• 数据路径、格式和划分；
• 实验配置；
• 已执行的重要命令；
• 关键输出；
• 错误信息；
• 哪些结果可靠，哪些只是 preliminary。

对继续工作有价值时，保留准确命令和关键报错原文。

7. 未完成事项、风险与未知

列出：

• TODO；
• blocker；
• 可能有问题的假设；
• 环境、路径、版本、随机种子、硬编码参数等风险；
• 需要用户确认的问题；
• 当前无法确认的重要信息。

TODO 应尽量可执行、可验证，不要写成泛泛的“继续优化”。

8. 下一步行动

给下一个 agent 一条明确恢复路径，例如：

1. 先读哪些文件；
2. 先检查什么状态；
3. 第一条应该运行的命令；
4. 先验证哪个 blocker；
5. 下一处应修改的文件 / 函数 / 配置；
6. 如何验证修改是否成功。

如果时间有限，再补充一个“最小可行推进步骤”。

给下一个 agent 的启动提示词

文件最后附上一段简短直接的提示，例如：

你现在接手这个项目。

先完整阅读本交接文档，然后检查当前 Git、文件和实验现场是否与记录一致。不要覆盖未提交修改。若交接内容与当前代码、Git 或日志冲突，以当前项目直接证据为准，并记录差异。

优先从最高优先级未完成任务继续，不要重新规划整个项目；没有新证据时，不要重复 DO NOT REPEAT 中已经失败的尝试。对未知或未经验证的信息继续保持明确标记，不要把推断当成事实。

完成前检查

生成 prompt.txt 前确认：

• 没有当前聊天历史的人能否理解项目？
• 当前任务和代码状态是否明确？
• 是否保留了关键未完成工作和失败尝试？
• 是否有编造内容？
• 是否保留了必要的路径、命令、参数和错误？
• 是否明确区分已验证事实与推断？
• 下一步是否足够具体，能让另一个 agent 直接执行？

如果可以创建文件，不要只在聊天中输出摘要；必须实际生成 prompt.txt。

更新 prompt.txt：


```plain text
请根据当前对话和项目状态，使用我之前给你的交接格式，生成或更新 prompt.txt。请把当前所有重要上下文都写进去，确保下一个 agent 可以无缝接手。

然后给下一个 Agent 发：

text

请先读取项目根目录下的 prompt.txt，完整理解其中的项目背景、当前任务、代码状态、已完成工作、未完成 TODO 和注意事项。然后不要急着改代码，先用中文简要复述你对当前任务的理解、下一步计划，以及你准备优先检查的文件/命令。