handoff

交接

记录新 Agent 继续工作所需的上下文，避免重新提问、重新摸索或重复犯错。

核心原则

1. 描述状态。 写“认证已实现；尚未开始实现登出”，而不是“下一步实现登出”。下一位 Agent 会根据上下文选择行动。
2. 链接现有资料。 按路径或 URL 引用 PRD、计划、ADR、问题、提交、差异和设计文档，而不是复制其内容。
3. 保留原因。 记录代码本身无法说明的决策、被否决的方法和失败经历。
4. 要求验证。 将陈述作为需要对照实际代码核查的上下文，而非盲目信任的事实。
5. 隐去机密和个人身份信息。 切勿包含密钥、令牌、密码或个人数据。说明凭据所在位置（例如“.env.local，未提交”），切勿写出其值。
6. 只保留有用的上下文。 省略可从代码或项目配置中获取的显而易见、重复或说明性内容。

流程

1. 阅读现有项目说明（AGENTS.md 或同等文件）。交接内容应针对本次会话；不要重复这些说明。
2. 阅读并更新之前的交接内容，而不是从头开始。
3. 将用户提供的参数视为下一次会话的关注重点。
4. 填写模板中的每个部分；空白部分标记为 None。
5. 将交接内容放在一个围栏代码块中输出，并按 文件输出 中的说明保存相同内容。

输出格式

在单个围栏代码块中使用此模板：

# HANDOFF: <short title of the work>
Generated: <timestamp> · Session focus: <one line>

## 1. Goal
<The overall objective in 1–3 sentences.>

## 2. Why This Matters / Background
<Motivation, intended users, timing, constraints, and hard requirements not already in project configuration.>

## 3. Current State
<What is DONE, PARTIAL, and NOT STARTED. Describe status, not actions:
- DONE: OAuth login flow, tests passing locally
- PARTIAL: Session storage wired up; refresh logic missing
- NOT STARTED: Logout endpoint>

## 4. Key Decisions (and why)
<Choices and reasoning, especially what cannot be recovered from code.
- Chose passport.js over custom OAuth — community support and less surface area
- Stored tokens in httpOnly cookies — XSS mitigation>

## 5. Traps & Dead Ends
<Failed approaches and pitfalls the next agent might repeat, with reasons.
- DB mocks made integration tests flaky; replaced with a test container
- SDK v3 breaks the streaming API this project relies on>

## 6. Relevant Files & Pointers
<Paths with line ranges and specific contents; link external artifacts instead of copying them.
- src/auth/oauth.ts:L40-L88 — provider config + token exchange
- docs/adr/0007-auth.md — full rationale
- PR #142 — in-progress session work
- Issue #150 — logout requirements>

## 7. Open Work (status, with dependencies)
<Remaining work and dependencies, stated as status rather than commands.
- Logout endpoint is not implemented
- Session persistence depends on the logout endpoint
- E2E auth tests are blocked until both are complete>

---
## Prompt for the Fresh Agent
<A short prompt with background context. Use declarative statements such as "X is complete" or "Y has not started." Preserve this exact closing instruction:>

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.

文件输出

将相同的交接内容保存在工作树之外，最好放在操作系统的临时目录中：macOS/Linux 使用 $TMPDIR/handoff-<random-8-chars>.md，或在其他系统中使用对应位置。如果用户希望将记录保存在项目内，则在项目根目录使用 HANDOFF.md。

报告绝对路径。用户可以通过以下内容开始新会话：

Read the file <absolute-path> to get the context, then wait for instructions.