session-handoff

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Handoff

交接文档

Creates comprehensive handoff documents that enable fresh AI agents to seamlessly continue work with zero ambiguity. Solves the long-running agent context exhaustion problem.

创建全面的交接文档，让新的AI Agent能够毫无歧义地无缝继续工作，解决长期运行的Agent上下文耗尽问题。

Mode Selection

模式选择

Determine which mode applies:

Creating a handoff? User wants to save current state, pause work, or context is getting full.

Follow: CREATE Workflow below

Resuming from a handoff? User wants to continue previous work, load context, or mentions an existing handoff.

Follow: RESUME Workflow below

Proactive suggestion? After substantial work (5+ file edits, complex debugging, major decisions), suggest:

"We've made significant progress. Consider creating a handoff document to preserve this context for future sessions. Say 'create handoff' when ready."

确定适用的模式：

是否要创建交接文档？ 用户希望保存当前状态、暂停工作，或者上下文即将达到容量上限。

遵循下方的CREATE工作流

是否要从交接文档恢复工作？ 用户希望继续之前的工作、加载上下文，或者提及已有的交接文档。

遵循下方的RESUME工作流

主动建议？ 在完成大量工作（5次以上文件编辑、复杂调试、重大决策）后，建议：

"我们已经取得了显著进展。建议创建一份交接文档来保存当前上下文，以便后续会话使用。准备好后请说“创建交接文档”。"

CREATE Workflow

CREATE工作流

Step 1: Generate Scaffold

步骤1：生成框架

Run the smart scaffold script to create a pre-filled handoff document:

bash

python scripts/create_handoff.py [task-slug]

Example:

python scripts/create_handoff.py implementing-user-auth

For continuation handoffs (linking to previous work):

bash

python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md

The script will:

Create
```
.claude/handoffs/
```
directory if needed
Generate timestamped filename
Pre-fill: timestamp, project path, git branch, recent commits, modified files
Add handoff chain links if continuing from previous
Output file path for editing

运行智能框架脚本创建预填充的交接文档：

bash

python scripts/create_handoff.py [task-slug]

Example:

python scripts/create_handoff.py implementing-user-auth

对于续接式交接文档（关联之前的工作）：

bash

python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md

该脚本将：

若需要则创建
```
.claude/handoffs/
```
目录
生成带时间戳的文件名
预填充内容：时间戳、项目路径、Git分支、最近提交记录、修改的文件
若续接之前的交接文档，添加交接链链接
输出用于编辑的文件路径

Step 2: Complete the Handoff Document

步骤2：完善交接文档

Open the generated file and fill in all

[TODO: ...]

sections. Prioritize these sections:

Current State Summary - What's happening right now
Important Context - Critical info the next agent MUST know
Immediate Next Steps - Clear, actionable first steps
Decisions Made - Choices with rationale (not just outcomes)

Use the template structure in references/handoff-template.md for guidance.

打开生成的文件，填写所有

[TODO: ...]

部分。优先完成以下章节：

当前状态总结 - 当前的工作进展情况
重要上下文 - 下一个Agent必须知晓的关键信息
紧急下一步任务 - 清晰、可执行的首要任务
已做出的决策 - 包含决策依据的选择（而非仅结果）

可参考references/handoff-template.md中的模板结构。

Step 3: Validate the Handoff

步骤3：验证交接文档

Run the validation script to check completeness and security:

bash

python scripts/validate_handoff.py <handoff-file>

The validator checks:

No
```
[TODO: ...]
```
placeholders remaining
Required sections present and populated
No potential secrets detected (API keys, passwords, tokens)
Referenced files exist
Quality score (0-100)

Do not finalize a handoff with secrets detected or score below 70.

运行验证脚本检查文档的完整性和安全性：

bash

python scripts/validate_handoff.py <handoff-file>

验证器会检查：

不存在剩余的
```
[TODO: ...]
```
占位符
所有必填章节已存在且已填充内容
未检测到潜在机密信息（如API密钥、密码、令牌）
引用的文件存在
质量评分（0-100分）

如果检测到机密信息或评分低于70分，请勿完成交接文档的创建。

Step 4: Confirm Handoff

步骤4：确认交接文档创建完成

Report to user:

Handoff file location
Validation score and any warnings
Summary of captured context
First action item for next session

向用户汇报：

交接文档的存储位置
验证评分及任何警告信息
已捕获的上下文摘要
下一次会话的首要任务

RESUME Workflow

RESUME工作流

Step 1: Find Available Handoffs

步骤1：查找可用的交接文档

List handoffs in the current project:

bash

python scripts/list_handoffs.py

This shows all handoffs with dates, titles, and completion status.

列出当前项目中的所有交接文档：

bash

python scripts/list_handoffs.py

该命令会显示所有交接文档的日期、标题和完成状态。

Step 2: Check Staleness

步骤2：检查时效性

Before loading, check how current the handoff is:

bash

python scripts/check_staleness.py <handoff-file>

Staleness levels:

FRESH: Safe to resume - minimal changes since handoff
SLIGHTLY_STALE: Review changes, then resume
STALE: Verify context carefully before resuming
VERY_STALE: Consider creating a fresh handoff

The script checks:

Time since handoff was created
Git commits since handoff
Files changed since handoff
Branch divergence
Missing referenced files

在加载之前，检查交接文档的时效性：

bash

python scripts/check_staleness.py <handoff-file>

时效性等级：

FRESH（最新）：可以安全恢复工作 - 自创建交接文档以来仅发生少量变更
SLIGHTLY_STALE（略有过时）：查看变更记录后再恢复工作
STALE（过时）：恢复工作前仔细验证上下文
VERY_STALE（严重过时）：考虑创建新的交接文档

该脚本会检查：

交接文档创建至今的时间
自创建交接文档以来的Git提交记录
自创建交接文档以来修改的文件
分支差异
缺失的引用文件

Step 3: Load the Handoff

步骤3：加载交接文档

Read the relevant handoff document completely before taking any action.

If handoff is part of a chain (has "Continues from" link), also read the linked previous handoff for full context.

在采取任何行动之前，完整阅读相关的交接文档。

如果交接文档属于一个交接链（包含“续接自”链接），还需阅读链接的上一份交接文档以获取完整上下文。

Step 4: Verify Context

步骤4：验证上下文

Follow the checklist in references/resume-checklist.md:

Verify project directory and git branch match
Check if blockers have been resolved
Validate assumptions still hold
Review modified files for conflicts
Check environment state

遵循references/resume-checklist.md中的检查清单：

验证项目目录和Git分支是否匹配
检查是否有阻碍工作的问题已解决
验证之前的假设是否仍然成立
检查修改的文件是否存在冲突
检查环境状态

Step 5: Begin Work

步骤5：开始工作

Start with "Immediate Next Steps" item #1 from the handoff document.

Reference these sections as you work:

"Critical Files" for important locations
"Key Patterns Discovered" for conventions to follow
"Potential Gotchas" to avoid known issues

从交接文档中的“紧急下一步任务”第1项开始工作。

工作过程中可参考以下章节：

“关键文件”部分了解重要文件位置
“已发现的关键模式”部分了解需要遵循的约定
“潜在陷阱”部分避免已知问题

Step 6: Update or Chain Handoffs

步骤6：更新或链接交接文档

As you work:

Mark completed items in "Pending Work"
Add new discoveries to relevant sections
For long sessions: create a new handoff with
```
--continues-from
```
to chain them

工作过程中：

在“待完成工作”部分标记已完成的任务
将新发现的内容添加到相关章节
对于长时间的会话：使用
```
--continues-from
```
参数创建新的交接文档，形成交接链

Handoff Chaining

交接文档链

For long-running projects, chain handoffs together to maintain context lineage:

handoff-1.md (initial work)
    ↓
handoff-2.md --continues-from handoff-1.md
    ↓
handoff-3.md --continues-from handoff-2.md

Each handoff in the chain:

Links to its predecessor
Can mark older handoffs as superseded
Provides context breadcrumbs for new agents

When resuming from a chain, read the most recent handoff first, then reference predecessors as needed.

对于长期运行的项目，可将交接文档链接起来以维护上下文的连续性：

handoff-1.md（初始工作）
    ↓
handoff-2.md --continues-from handoff-1.md
    ↓
handoff-3.md --continues-from handoff-2.md

链中的每一份交接文档：

链接到前一份交接文档
可标记旧的交接文档为已被取代
为新Agent提供上下文线索

从交接链恢复工作时，先阅读最新的交接文档，再根据需要参考之前的交接文档。

Storage Location

存储位置

Handoffs are stored in:

.claude/handoffs/

Naming convention:

YYYY-MM-DD-HHMMSS-[slug].md

Example:

2024-01-15-143022-implementing-auth.md

交接文档存储在：

.claude/handoffs/

命名规则：

YYYY-MM-DD-HHMMSS-[slug].md

示例：

2024-01-15-143022-implementing-auth.md

Resources

资源

scripts/

Script	Purpose
`create_handoff.py [slug] [--continues-from <file>]`	Generate new handoff with smart scaffolding
`list_handoffs.py [path]`	List available handoffs in a project
`validate_handoff.py <file>`	Check completeness, quality, and security
`check_staleness.py <file>`	Assess if handoff context is still current

脚本	用途
`create_handoff.py [slug] [--continues-from <file>]`	生成带有智能框架的新交接文档
`list_handoffs.py [path]`	列出项目中的所有可用交接文档
`validate_handoff.py <file>`	检查交接文档的完整性、质量和安全性
`check_staleness.py <file>`	评估交接文档的上下文是否仍然有效

references/

handoff-template.md - Complete template structure with guidance
resume-checklist.md - Verification checklist for resuming agents

handoff-template.md - 包含指导内容的完整模板结构
resume-checklist.md - 供恢复工作的Agent使用的验证检查清单