⚡

会话管理 session-management

会话管理技能用于在长时间开发过程中保持上下文连续性，确保在休息或中断后能够快速恢复工作状态。关键词包括：上下文保存、分层总结、可恢复性。

DevOps 0 次安装 0 次浏览 更新于 3/5/2026

会话管理技能

加载于：base.md

为了在长时间的开发会话中保持上下文，并在休息后无缝恢复。

核心原则

在自然断点处检查点，立即恢复。

长时间的开发会话有失去上下文的风险。主动记录状态、决策和进展，以便任何会话都可以在离开的地方精确恢复——无论是休息后返回还是达到上下文限制。

分层总结规则

第1层：快速更新（仅current-state.md）

触发器：完成任何小任务或待办事项后 动作：更新“活动任务”、“进展”和“下一步”部分 时间：~30秒

第2层：完整检查点（current-state.md + decisions.md）

触发器：

  • 完成功能或重大更改后
  • 做出任何架构/库决策后
  • 在积极工作中大约20个工具调用后
  • 当切换到代码库的不同区域时

动作：

  1. 更新完整的current-state.md
  2. 将任何决策记录到decisions.md
  3. 更新正在修改的文件表

第3层：会话归档（archive/ + 完整检查点）

触发器：

  • 工作会话结束时
  • 完成主要功能/里程碑时
  • 在重大上下文转变之前
  • 当上下文感觉沉重（~50+工具调用）时

动作：

  1. 创建归档条目：archive/YYYY-MM-DD[-topic].md
  2. 完整检查点
  3. 从current-state.md中清除详细笔记
  4. 如果引入了新模式，则更新code-landmarks.md

决策启发式

┌─────────────────────────────────────────────────────┐
│ 完成工作后，问：                         │
├─────────────────────────────────────────────────────┤
│ 做出了决策吗？        → 记录到decisions.md   │
│ 任务需要>10个工具调用？   → 完整检查点       │
│ 主要功能完成了吗？     → 归档               │
│ 会话结束？             → 归档 + 交接     │
│ 否则                   → 快速更新          │
└─────────────────────────────────────────────────────┘

会话状态结构

创建_project_specs/session/目录：

_project_specs/
└── session/
    ├── current-state.md      # 现场会话状态（频繁更新）
    ├── decisions.md          # 关键决策日志（仅附加）
    ├── code-landmarks.md     # 重要代码位置
    └── archive/              # 过去会话摘要
        └── 2025-01-15.md

当前状态文件

_project_specs/session/current-state.md - 每15-20分钟或在重大进展后更新。

# 当前会话状态

*最后更新：2025-01-15 14:32*

## 活动任务
[一句话：我们现在正在做什么]

示例：使用JWT令牌实现用户认证流程

## 当前状态
- **阶段**：[探索 | 规划 | 实施 | 测试 | 调试 | 重构]
- **进展**：[X of Y步骤完成，或百分比]
- **阻塞问题**：[无，或描述阻塞者]

## 上下文摘要
[2-3句话总结当前工作状态]

示例：创建了认证中间件和登录端点。JWT签名有效。
目前正在实现令牌刷新逻辑。需要添加刷新令牌
旋转以提高安全性。

## 正在修改的文件
| 文件 | 状态 | 笔记 |
|------|--------|-------|
| src/auth/middleware.ts | 完成 | JWT验证 |
| src/auth/refresh.ts | 进行中 | 令牌旋转 |
| src/auth/types.ts | 完成 | 令牌接口 |

## 下一步
1. [ ] 在refresh.ts中完成刷新令牌旋转
2. [ ] 添加用于注销的令牌黑名单
3. [ ] 为认证流程编写集成测试

## 要保留的关键上下文
- 根据安全要求使用RS256算法（而不是HS256）
- 刷新令牌存储在HttpOnly cookies中
- 访问令牌：15分钟，刷新令牌：7天

## 恢复指令
要继续这项工作：
1. 阅读src/auth/refresh.ts - 目前在第45行
2. rotateRefreshToken()函数需要错误处理
3. 检查decisions.md，了解为什么我们选择RS256而不是HS256

决策日志

_project_specs/session/decisions.md - 仅附加的架构和实现决策日志。

# 决策日志

跟踪关键决策以供将来参考。永远不要删除条目。

---

## [2025-01-15] JWT算法选择

**决策**：使用RS256而不是HS256进行JWT签名

**上下文**：实施认证系统

**考虑的选项**：
1. HS256（对称）- 更简单，单一密钥
2. RS256（非对称）- 公/私钥对

**选择**：RS256

**理由**：
- 允许在不暴露签名密钥的情况下验证令牌
- 更适合微服务（服务只需要公钥）
- 生产系统的行业标准

**权衡**：
- 密钥管理稍微复杂一些
- 令牌大小更大

**参考**：
- src/auth/keys/ - 密钥存储
- docs/security.md - 安全架构

---

## [2025-01-14] 数据库架构方法

**决策**：使用Drizzle ORM与PostgreSQL

**上下文**：设置数据层

**考虑的选项**：
1. Prisma - 流行，良好的DX
2. Drizzle - 类型安全，类似SQL
3. 原始SQL - 最大控制

**选择**：Drizzle

**理由**：
- 比Prisma更好的TypeScript推断
- 更透明的SQL生成
- 更轻量级，更快的冷启动

**参考**：
- src/db/schema.ts - 架构定义
- src/db/migrations/ - 迁移文件

代码地标

_project_specs/session/code-landmarks.md - 重要代码位置的快速参考。

# 代码地标

快速参考代码库中的重要部分。

## 入口点
| 位置 | 目的 |
|----------|---------|
| src/index.ts | 主应用入口 |
| src/api/routes.ts | API路由定义 |
| src/workers/index.ts | 后台作业入口 |

## 核心业务逻辑
| 位置 | 目的 |
|----------|---------|
| src/core/auth/ | 认证系统 |
| src/core/billing/ | 支付处理 |
| src/core/workflows/ | 主工作流引擎 |

## 配置
| 位置 | 目的 |
|----------|---------|
| src/config/index.ts | 环境配置 |
| src/config/features.ts | 功能标志 |
| drizzle.config.ts | 数据库配置 |

## 关键模式
| 模式 | 示例位置 | 笔记 |
|---------|------------------|-------|
| 服务层 | src/services/user.ts | 业务逻辑封装 |
| 仓库 | src/repos/user.ts | 数据访问抽象 |
| 中间件 | src/middleware/auth.ts | 请求处理 |

## 测试
| 位置 | 目的 |
|----------|---------|
| tests/unit/ | 单元测试 |
| tests/integration/ | API测试 |
| tests/e2e/ | 端到端测试 |
| tests/fixtures/ | 测试数据 |

## 陷阱和非明显行为
| 位置 | 问题 | 笔记 |
|----------|-------|-------|
| src/utils/date.ts | 时区处理 | 内部始终使用UTC |
| src/api/middleware.ts:45 | 认证绕过 | 健康检查跳过认证 |
| src/db/pool.ts | 连接限制 | 开发中最大10个连接 |

CLAUDE.md会话规则

将此部分添加到CLAUDE.md：

## 会话管理

**重要**：遵循session-management.md技能。在自然断点处更新会话状态。

### 每个任务完成后
问自己：
1. 做出了决策吗？ → 记录到`decisions.md`
2. 这需要>10个工具调用吗？ → 完整检查点到`current-state.md`
3. 主要功能完成了吗？ → 创建归档条目
4. 否则 → 快速更新到`current-state.md`

### 检查点触发器
**快速更新**（current-state.md）：
- 完成任何待办事项
- 进行小更改

**完整检查点**（current-state.md + decisions.md）：
- 重大更改后
- 大约20个工具调用后
- 做出任何决策后
- 当切换焦点区域时

**归档**（archive/ + 完整检查点）：
- 会话结束
- 主要功能完成
- 上下文感觉沉重

### 会话开始协议
开始工作时：
1. 阅读`_project_specs/session/current-state.md`
2. 检查`_project_specs/todos/active.md`
3. 如有需要，查看最近的`decisions.md`条目
4. 从“下一步”继续

### 会话结束协议
在结束或上下文限制接近时：
1. 创建归档：`_project_specs/session/archive/YYYY-MM-DD.md`
2. 使用交接格式更新current-state.md
3. 确保下一步具体且可执行

压缩策略

何时压缩（第3层归档）

触发器 动作
~50+工具调用 总结进展，归档详细笔记
主要功能完成 归档功能细节，更新地标
上下文转变 总结之前的上下文，归档，重新开始
会话结束 完整的会话交接和归档

保留与归档

保留在活动上下文中：

  • 当前任务和接下来的步骤
  • 活动文件列表及其状态
  • 阻塞问题
  • 影响当前工作的决策

归档/总结：

  • 没有成功探索的路径
  • 详细的调试跟踪（仅保留结论）
  • 冗长的错误消息（仅保留根本原因）
  • 研究笔记（仅保留建议）

压缩模板

压缩时，使用此格式：

## 压缩上下文 - [主题]

**摘要**：[1-2句话]

**关键发现**：
- [重要发现的项目点]

**做出的决策**：
- [参考decisions.md条目]

**相关代码**：
- [文件：行引用]

**归档细节**：[如果创建了归档文件，则链接到归档文件]

会话归档

在重要工作或会话结束时创建归档：

_project_specs/session/archive/YYYY-MM-DD[-topic].md

# 会话归档：[日期] - [主题]

## 摘要
[总结完成的工作的段落]

## 完成的任务
- [TODO-XXX] 描述 - 完成
- [TODO-YYY] 描述 - 完成

## 关键决策
- [参考本会话中做出的decisions.md条目]

## 代码更改
| 文件 | 更改类型 | 描述 |
|------|-------------|-------------|
| src/auth/login.ts | 创建 | 登录端点 |
| src/auth/types.ts | 修改 | 添加RefreshToken类型 |

## 添加的测试
- tests/auth/login.test.ts - 登录流程测试
- tests/auth/refresh.test.ts - 令牌刷新测试

## 继续进行的开放项目
- [任何未完成的项目，现在在active.md中]

## 会话统计
- 持续时间：~3小时
- 工具调用：~120
- 修改的文件：8
- 添加的测试：12

与待办事项系统集成

将待办事项链接到会话

在活动待办事项中，引用会话上下文：

## [TODO-042] 实施令牌刷新

**状态：** 进行中
**会话上下文：** 参见current-state.md

### 进展笔记
- 2025-01-15：开始实施，基础结构完成
- 2025-01-15：添加旋转逻辑，需要错误处理

在待办事项完成时自动更新

完成待办事项时：

  1. 在active.md中标记待办事项为完成
  2. 更新current-state.md的进展
  3. 记录任何做出的决策
  4. 如果引入了新模式，则更新code-landmarks.md

快速命令

将这些添加到项目脚本或别名中：

# 显示当前会话状态
alias session-status="cat _project_specs/session/current-state.md"

# 快速编辑会话状态
alias session-edit="$EDITOR _project_specs/session/current-state.md"

# 查看最近的决策
alias decisions="tail -100 _project_specs/session/decisions.md"

# 创建会话归档
session-archive() {
  cp _project_specs/session/current-state.md \
     "_project_specs/session/archive/$(date +%Y-%m-%d).md"
  echo "Archived to _project_specs/session/archive/$(date +%Y-%m-%d).md"
}

执行机制

1. CLAUDE.md作为入口点

CLAUDE.md必须在技能部分引用session-management.md。Claude首先读取CLAUDE.md，然后指示它遵循会话规则。

2. 会话文件头带有提醒

在会话文件头中包含执行提醒：

current-state.md头部：

<!--
检查点规则（来自session-management.md）：
- 快速更新：在完成任何待办事项后
- 完整检查点：在大约20个工具调用或决策后
- 归档：在会话结束或主要功能完成时
-->

3. 自我检查问题

完成任何任务后，Claude应该问：

□ 我做出决策了吗？ → 记录它
□ 这需要>10个工具调用吗？ → 完整检查点
□ 功能完成了吗？ → 归档
□ 我结束/切换上下文了吗？ → 归档 + 交接

4. 会话开始验证

开始会话时，Claude必须：

  1. 检查current-state.md是否存在并阅读它
  2. 宣布它找到了什么：“从[最后状态]恢复”
  3. 在继续之前确认下一步

5. 定期自我审计

每大约20个工具调用，Claude应该检查：

  • current-state.md是最新的吗？
  • 有没有未记录的决策？
  • 上下文变得沉重了吗？

6. 用户提示

用户可以通过询问来执行：

  • “更新会话状态” → 触发检查点
  • “当前状态是什么？” → Claude阅读并报告
  • “结束会话” → 触发归档 + 交接
  • “从上一个会话恢复” → Claude首先读取状态文件

反模式

  • 没有状态跟踪 - 盲目飞行，无法恢复
  • 过于冗长的状态 - 保持可扫描，而不是小说
  • 过时的状态文件 - 定期更新，否则它们变得无用
  • 缺少决策 - 未来的你不会记得为什么
  • 没有代码地标 - 浪费时间重新发现代码库
  • 从不归档 - 会话文件变得杂乱无章
  • 忽略压缩信号 - 上下文过载会降低性能
  • 在决策后跳过检查点 - 关键上下文丢失
  • 会话结束时没有交接 - 下一个会话开始时盲目

快速参考

检查点决策树

任务完成了吗？
    │
    ├── 决策做出？ ──────────────────→ 记录到decisions.md
    │
    ├── >10个工具调用或重大？ ──→ 完整检查点
    │
    ├── 主要功能完成了吗？ ─────────────→ 归档
    │
    └── 否则 ───────────────────────→ 快速更新

文件一览

文件 更新频率 目的
current-state.md 每个任务 现场状态，下一步
decisions.md 做出决策时 架构选择
code-landmarks.md 模式变化时 代码导航
archive/*.md 会话结束/功能 历史记录