Back to Details

handoff

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Handoff

会话交接

Write a complete handoff that lets a fresh agent — with zero memory of this session — continue the work without re-asking, re-discovering, or repeating mistakes.
Output the entire handoff as a single fenced code block in the chat so the user can copy it in one click. Also save a copy to a file (see "File Output").
撰写一份完整的交接文档，让完全不了解当前会话的新Agent能够继续工作，无需重复询问、重新探索或重蹈覆辙。
将整个交接内容以单个围栏代码块的形式输出到聊天中，方便用户一键复制。同时将副本保存到文件中（参见“文件输出”部分）。

Core Principles

核心原则

  1. State, not instructions. Describe what is true, not what the next agent should do. Write "Auth endpoint is implemented; logout is not yet started" — never "Implement logout next." The fresh agent decides actions; you give it ground truth.
  2. Reference, don't duplicate. Do not paste content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs, design docs). Point to them by path or URL. Handoffs that re-embed everything become bloated and stale.
  3. Capture the "why". Decisions and rejected approaches are the most valuable and least recoverable information. Code shows what; only you remember why and what failed.
  4. Trust nothing blindly. Frame all claims as context to verify against the actual code, not facts to accept.
  5. Redact secrets. Strip API keys, tokens, passwords, and PII. Reference where credentials live (e.g. ".env.local, not committed") — never their values.
  6. Be ruthless. Every line must be something the next agent cannot trivially get by reading the code or project config. Cut anything obvious, redundant, or explanatory.
  1. 陈述状态，而非指令。描述实际情况，而非下一个Agent“应该做什么”。例如写“认证端点已实现；登出功能尚未启动”——绝对不要写“接下来实现登出功能”。新Agent决定行动方案；你只需提供真实背景信息。
  2. 引用而非复制。不要粘贴已在其他工件（PRDs、计划、ADRs、问题、提交记录、差异文件、设计文档）中记录的内容。通过路径或URL指向它们。重复嵌入所有内容的交接文档会变得臃肿且过时。
  3. 记录“原因”。决策过程和被否决的方案是最有价值且最难恢复的信息。代码展示“是什么”；只有你记得“为什么”以及“哪些方案失败了”。
  4. 不盲目信任任何内容。将所有声明视为需要对照实际代码验证的上下文，而非可直接接受的事实。
  5. 脱敏机密信息。移除API密钥、令牌、密码和个人身份信息（PII）。注明凭证存储位置（例如“.env.local，未提交到仓库”）——绝对不要泄露其具体值。
  6. 精简内容。每一行内容都必须是新Agent无法通过阅读代码或项目配置轻易获取的信息。删除所有显而易见、冗余或解释性的内容。

Procedure

操作流程

  1. If a project config file exists (CLAUDE.md / AGENTS.md / equivalent), read it first. Do not restate anything already covered there — the handoff is session-specific only.
  2. If a prior handoff file already exists, read it and update rather than starting from scratch.
  3. If the user passed arguments, treat them as the focus for the next session and tailor the handoff toward that goal.
  4. Fill in every section of the template below. Omit a section only if it is genuinely empty (e.g. no blockers) — mark it 
    None
    .
  5. Output the filled template inside one fenced code block in the chat.
  6. Save the same content to the file path described below and tell the user that path.
  1. 如果存在项目配置文件（CLAUDE.md / AGENTS.md / 等效文件），先读取该文件。不要重复其中已涵盖的任何内容——交接文档仅针对当前会话。
  2. 如果已有之前的交接文件，读取并更新它，而非从头开始撰写。
  3. 如果用户传递了参数，将其视为下一会话的重点，并据此调整交接文档的内容。
  4. 填写以下模板的每个部分。仅当某部分确实为空时（例如没有阻塞问题）才省略——标记为
    None
    。
  5. 将填写好的模板放在单个围栏代码块中输出到聊天中。
  6. 将相同内容保存到以下描述的文件路径，并告知用户该路径。

Output Format

输出格式

Output exactly this, inside a single fenced code block:
undefined
严格按照以下内容，放在单个围栏代码块中输出：
undefined

HANDOFF: <short title of the work>

HANDOFF: <工作简短标题>

Generated: <timestamp> · Session focus: <one line>
Generated: <时间戳> · Session focus: <一行内容>

1. Goal

1. 目标

<What we are ultimately trying to accomplish. 1–3 sentences. The "north star" so the next agent never loses the plot.>
<我们最终要达成的目标。1–3句话。作为“北极星”，确保新Agent不会偏离方向。>

2. Why This Matters / Background

2. 重要性/背景

<The motivation and constraints driving this work. Why it's being done now, who it's for, any hard requirements. Skip anything already in the project config.>
<推动这项工作的动机和约束条件。为什么现在开展这项工作，面向谁，有哪些硬性要求。跳过项目配置中已有的内容。>

3. Current State

3. 当前状态

<Factual status of the work. What is DONE, what is PARTIAL, what is NOT STARTED. Phrase as status, not actions:
  • DONE: OAuth login flow (Google provider), tests passing locally
  • PARTIAL: Session persistence — store wired up, refresh logic missing
  • NOT STARTED: Logout endpoint>
<工作的实际状态。已完成、部分完成、尚未启动的内容。 以状态表述，而非行动指令：
  • DONE: OAuth登录流程（Google提供商），本地测试通过
  • PARTIAL: 会话持久化——存储已连接，缺少刷新逻辑
  • NOT STARTED: 登出端点>

4. Key Decisions (and why)

4. 关键决策（及原因）

<The choices made and the reasoning. This is the highest-value section.
  • Chose passport.js over custom OAuth — more community support, less surface area
  • Stored tokens in httpOnly cookies, not localStorage — XSS mitigation>
<已做出的选择及其理由。这是价值最高的部分。
  • 选择passport.js而非自定义OAuth——社区支持更广泛，攻击面更小
  • 将令牌存储在httpOnly cookie中，而非localStorage——缓解XSS攻击风险>

5. Traps & Dead Ends

5. 陷阱与死胡同

<Approaches already tried that FAILED, and things the next agent will be tempted to do wrong. Saves the next agent from repeating expensive mistakes.
  • Tried mocking the DB in integration tests — flaky, abandoned for a test container
  • Do NOT bump the SDK to v3 — it breaks the streaming API we rely on>
<已尝试但失败的方案，以及新Agent可能会犯的错误。避免新Agent重复代价高昂的错误。
  • 尝试在集成测试中模拟数据库——不稳定，改用测试容器
  • 请勿将SDK升级到v3——会破坏我们依赖的流式API>

6. Relevant Files & Pointers

6. 相关文件与指针

<Files that matter, with line ranges and WHAT specifically is there — not just what the file is. Reference external artifacts instead of pasting them.
  • src/auth/oauth.ts:L40-L88 — provider config + token exchange
  • docs/adr/0007-auth.md — full rationale (do not duplicate here)
  • PR #142 — in-progress session work
  • Issue #150 — logout requirements>
<重要文件，包含行号范围及具体内容——不只是文件说明。引用外部工件而非粘贴内容。
  • src/auth/oauth.ts:L40-L88 ——提供商配置 + 令牌交换逻辑
  • docs/adr/0007-auth.md ——完整决策依据（请勿在此处重复）
  • PR #142 ——进行中的会话工作
  • Issue #150 ——登出功能需求>

7. Open Work (status, with dependencies)

7. 未完成工作（状态及依赖关系）

<What remains, described as state and ordering — NOT as a command list.
  • Logout endpoint is not yet implemented
  • Session persistence depends on the logout endpoint existing first
  • E2E auth tests are blocked until both above are complete>
<剩余工作，以状态和顺序描述——而非指令列表。
  • 登出端点尚未实现
  • 会话持久化依赖于登出端点的完成
  • E2E认证测试需等待上述两项完成后才能进行>

Prompt for the Fresh Agent

给新Agent的提示语

<A short ready-to-paste prompt giving background context. Use declarative statements ("X is complete", "Y has not been started"), never imperatives. End with exactly:>
Before responding, read every file listed under "Relevant Files & Pointers" above. Do not summarize, paraphrase, or claim you already have context — actually read each file. Treat every claim in this handoff as context to verify against the code, not facts to trust blindly. Then wait for my instructions before taking any action.
undefined
<一段简短的可直接粘贴的提示语，提供背景信息。使用陈述性语句 （“X已完成”，“Y尚未启动”），绝对不要使用祈使句。结尾必须为：>
在回复前，请阅读“相关文件与指针”下列出的所有文件。 不要总结、改写或声称已了解上下文——请实际阅读每个文件。将本交接文档中的所有声明视为需要对照代码验证的上下文，而非盲目信任的事实。然后等待我的指令再采取任何行动。
undefined

File Output

文件输出

Save the handoff to a temporary location outside the working tree so it does not pollute the repo:
  • Preferred: the OS temp directory, e.g. 
    $TMPDIR/handoff-<random-8-chars>.md
    (macOS/Linux) or the system temp dir equivalent.
  • If the user prefers an in-repo record, save to 
    HANDOFF.md
    in the project root instead.
After saving, tell the user the absolute path. The user can then start a fresh session with just:
Read the file <absolute-path> to get the context, then wait for instructions.
将交接文档保存到工作目录之外的临时位置，避免污染仓库：
  • 首选：操作系统临时目录，例如
    $TMPDIR/handoff-<8位随机字符>.md
    （macOS/Linux）或等效的系统临时目录。
  • 如果用户偏好仓库内记录，则保存到项目根目录的
    HANDOFF.md
    中。
保存后，告知用户绝对路径。用户只需使用以下命令即可启动新会话：
Read the file <absolute-path> to get the context, then wait for instructions.