handoff

会话交接技能

创建结构化文档，确保不同 Claude 会话之间无缝衔接。

适用场景

• 当天结束工作会话时
• 任务进行到一半需要休息时
• 暂时切换到其他项目时
• 想为后续会话记录当前状态时
• 在已知即将重置上下文前

交接流程

第 1 步：评估会话状态

快速评估：

1. 我们处于哪个阶段？（探索、规划、实现、调试、审查）
2. 当前任务是什么？（我们要完成什么）
3. 进展如何？（刚开始、进行到一半、即将完成）

第 2 步：询问重要事项

询问用户：

“我将创建一份交接文档。有什么特别需要我记录的吗？（关键决策、代码片段、问题背景、你可能会忘记的事项等）”

第 3 步：生成交接文档

创建一份结构化文档：

# Session Handoff: [Brief Description]

**Date:** [YYYY-MM-DD] **Project:** [project name/path] **Session Duration:**
[approximate]

## Current State

**Task:** [What we're working on] **Phase:**
[exploration/planning/implementation/debugging/review] **Progress:** [where we
are - percentage or milestone]

## What We Did

[2-3 sentence summary of the session's work]

## Decisions Made

- **[Decision]** — [Rationale]
- **[Decision]** — [Rationale]

## Code Changes

**Files modified:**

- `path/to/file.ts` — [what and why]
- `path/to/other.ts` — [what and why]

**Key code context:** [Critical snippets or patterns to remember]

## Open Questions

- [ ] [Question needing resolution]
- [ ] [Question needing resolution]

## Blockers / Issues

- [Issue] — [current status]

## Context to Remember

[Important background, constraints, user preferences, domain knowledge - things
that would take time to re-establish]

## Next Steps

1. [ ] [First thing to do next session]
2. [ ] [Second thing]
3. [ ] [Third thing]

## Files to Review on Resume

- `path/to/key/file.ts` — [why it matters]

第 4 步：写入文件

写入路径：.claude/handoffs/[YYYY-MM-DD]-[brief-description].md

向用户确认位置：

“我会将文件保存到 .claude/handoffs/[filename].md。要换个位置吗？”

需要记录的内容

始终包含

1. 决策及其理由——“为什么”往往比“是什么”更有价值
2. 代码更改——文件路径、更改内容及其意图
3. 当前进度——任务进行到哪里时暂停
4. 后续步骤——清晰、可执行的恢复任务事项
5. 用户背景信息——用户分享的限制条件、偏好和领域知识

相关时包含

• 遇到的错误——以及错误是否已解决、如何解决
• 行不通的尝试——试过但未奏效的方法（避免重复探索）
• 关键文件——需要阅读以快速了解情况的文件
• 外部依赖项——涉及的 API、服务和工具

跳过

• 冗长的工具输出（文件列表、grep 结果）
• 已得出结论的中间推理过程
• 重复的类似操作
• 从代码中显而易见的信息

格式指南

• 项目符号——便于快速浏览，而非叙述
• 文件路径——使用 src/foo.ts:42，而不是“那个函数”
• 操作使用复选框——后续步骤和未解决问题使用 - [ ]
• 具体明确——写“在 fetchUser() 中添加重试逻辑”，而不是“做了改进”

质量检查

保存前，请确认：

1. 新的 Claude 能否接手？——是否有足够的上下文继续工作？
2. 决策是否有据可查？——是否清楚说明了决策原因？
3. 后续步骤是否可执行？——是否明确知道首先要做什么？
4. 代码工作是否清晰？——是否知道哪些文件很重要？

使用交接文档

开始新会话时，用户可以：

1. 在会话开始时分享交接文件
2. 说“从这份交接继续：[粘贴内容或提供路径]”
3. 如果支持，可通过 @ 提及来引用

交接文档应让你迅速进入工作状态，无需冗长地重新解释。

交接示例

# Session Handoff: Auth System Implementation

**Date:** 2025-01-15 **Project:** /Users/robert/projects/my-api **Session
Duration:** ~2 hours

## Current State

**Task:** Implementing user authentication for the API **Phase:** Implementation
**Progress:** ~60% - basic flow works, need refresh tokens

## What We Did

Built the core JWT authentication flow including token generation, validation
middleware, and login/logout endpoints. Hit an issue with key rotation that we
resolved by moving to config-based key paths.

## Decisions Made

- **JWT with RS256** — Stateless auth, works with distributed setup
- **Redis for refresh tokens** — Need revocation capability
- **15-min access token expiry** — Balance security/UX for mobile app

## Code Changes

**Files modified:**

- `src/auth/jwt.ts` — Token generation and validation logic
- `src/middleware/auth.ts` — Request authentication middleware
- `src/routes/auth.ts` — Login/logout endpoints
- `config/keys/` — RSA key pair storage

**Key code context:** Token validation uses RS256. Keys loaded from
`config/keys/` based on NODE_ENV.

## Open Questions

- [ ] Automatic vs opt-in refresh token rotation?
- [ ] Rate limit for login attempts? (User mentioned 10k DAU)

## Context to Remember

- Client is a mobile app - tokens need offline capability
- User has 10k daily active users - scale matters
- Using PostgreSQL for user storage
- User prefers explicit error messages over generic ones

## Next Steps

1. [ ] Implement `/auth/refresh` endpoint
2. [ ] Add rate limiting to `/auth/login`
3. [ ] Write tests for token expiry edge cases
4. [ ] Update API docs with auth flow

## Files to Review on Resume

- `src/auth/jwt.ts` — Core token logic
- `src/routes/auth.ts` — Current endpoint implementation

重要提醒

• 生成文档前，先询问用户关心什么
• 决策需要说明理由——记录“为什么”
• 文件路径是工作的锚点——务必包含
• 后续步骤应能立即执行
• 宁可稍长且有用，也不要简短含糊