Claude Code 会话管理命令

适用于 Claude Code 的自定义斜杠命令，提供全面的开发会话跟踪和文档记录功能。基于 Claude Code 的自定义斜杠命令系统。

🎯 概述

这是一组专为 Claude Code 设计的自定义斜杠命令，旨在帮助开发者在与 Claude 的多次编码会话之间保持连贯性，具体功能包括：

• 记录进展：捕捉已完成的工作、实现方式以及决策背后的理由
• 跟踪变更：监控 Git 变更、待办事项及实现细节
• 知识传递：使后续会话无需重新分析整个代码库即可理解之前的工作
• 问题解决：记录遇到的问题及其解决方案，以供未来参考

这些命令通过项目特定的会话管理功能扩展了 Claude Code 的内置功能。

🚀 快速入门

# 开始新会话（可选名称）
/project:session-start authentication-refactor
# 或不指定名称
/project:session-start

# 在开发过程中更新进展（可选备注）
/project:session-update Implemented OAuth with Google
# 或不带备注（自动总结最近活动）
/project:session-update

# 结束会话并生成综合摘要
/project:session-end

# 查看当前会话状态
/project:session-current

# 列出所有过往会话
/project:session-list

📁 文件结构

commands/                       # 自定义命令目录
├── session-start.md           # 用于开始新会话的命令
├── session-update.md          # 用于更新当前会话的命令
├── session-end.md             # 用于结束并总结会话的命令
├── session-current.md         # 用于查看当前会话状态的命令
├── session-list.md            # 用于列出所有会话的命令
└── session-help.md            # 用于显示帮助信息的命令

sessions/                      # 会话存储目录
├── .current-session          # 跟踪当前活动会话的文件名
├── 2025-01-16-1347.md       # 示例会话文件
└── [YYYY-MM-DD-HHMM-name].md  # 会话命名格式

🛠️ 安装

1. 克隆此仓库或将文件夹复制到您的项目中：

   git clone git@github.com/iannuttall/claude-sessions.git
   # 或将 commands 和 sessions 文件夹复制到您的项目根目录
   

2. 创建会话跟踪文件：

   mkdir -p sessions
   touch sessions/.current-session
   

3. 如果您不想跟踪会话，请将其添加到 .gitignore 中：

   sessions/
   

📝 工作原理

本系统提供了受 Claude Code 的自定义斜杠命令 功能启发的自定义斜杠命令。虽然 Claude Code 通常会在 .claude/commands/ 目录下查找命令，但本仓库提供了一个独立的实现，命令位于 commands/ 目录中。

• 前缀：所有命令均使用 /project: 前缀（用于项目特定命令）
• 参数：命令支持使用 $ARGUMENTS 占位符传递参数
• 执行：Claude 会读取命令文件并执行其中的指令
• 注意：这些命令专为 Claude 设计，但也可适配于其他 AI 编码助手。

📋 命令参考

/project:session-start [name]

开始一个新的开发会话，可选指定描述性名称。

参数：

• [name]（可选）—— 会话的描述性名称。若省略，则仅按时间戳创建会话。

作用：

• 创建一个带有时间戳的新 Markdown 文件（格式为 YYYY-MM-DD-HHMM.md 或 YYYY-MM-DD-HHMM-name.md）
• 设置包含目标和进展部分的会话结构
• 更新 .current-session 文件以跟踪当前活动会话
• 若上下文不明确，则提示输入会话目标

示例：

# 带有描述性名称
/project:session-start refactor-auth-system

# 不带名称（仅时间戳）
/project:session-start

/project:session-update [notes]

向当前会话添加带时间戳的更新内容。

参数：

• [notes]（可选）—— 关于此次更新的自定义备注。若省略，则自动总结最近的活动。

作用：

• 追加带有时间戳的进展笔记
• 记录 Git 状态和变更
• 跟踪待办事项的进展
• 记录问题及解决方案
• 记录实现细节
• 若未提供备注，则自动生成摘要

示例：

# 带自定义备注
/project:session-update Fixed Next.js 15 params Promise issue

# 不带备注（自动汇总）
/project:session-update

/project:session-end

以综合摘要结束当前会话。

作用：

• 生成完整的会话摘要，包括：
  • 会话时长及时间安排
  • Git 变更摘要
  • 已完成和剩余的待办事项
  • 主要成就
  • 遇到的问题及解决方案
  • 依赖项和配置变更
  • 经验教训
  • 对未来开发者的建议
• 清除 .current-session 文件。

/project:session-current

显示当前活动会话的状态。

作用：

• 显示会话名称和持续时间
• 展示最近的更新
• 列出当前的目标和任务
• 提醒可用的命令

/project:session-list

列出所有会话文件及其摘要。

作用：

• 按日期排序显示所有会话文件
• 显示会话标题和时间戳
• 标明当前活动会话
• 提供每个会话的简要概述

/project:session-help

显示关于会话系统的帮助信息。

🎯 Claude Code 最佳实践

命令使用

• 这些命令仅在 Claude Code 的交互式会话中有效
• 命令是项目特定的，对所有团队成员可见
• 参数直接跟在命令名称后传递

会话管理

• 会话有助于 Claude 在多次对话中保持上下文连贯性
• 在开始相关工作之前，回顾过去的会话
• 会话文件可作为开发过程的文档记录

🔧 自定义

适配标准 Claude Code 设置

如果您希望将这些命令与 Claude Code 的标准目录结构一起使用：

1. 将 commands 文件夹复制到项目的 .claude/commands/ 目录中
2. 将命令文件中的路径从 sessions/ 更新为 .claude/sessions/

创建您自己的命令

• 修改命令文件以改变行为
• 创建额外的会话相关命令
• 将命令组织到子目录中以进行命名空间管理（例如 /project:session:feature:start）
• 在 ~/.claude/commands/ 中创建个人版本，并使用 /user: 前缀

📚 参考资料

• Claude Code 斜杠命令文档
• Claude Code 内存管理
• Claude Code 概述

🎯 最佳实践

开始会话

• 使用能表明主要关注点的描述性名称
• 为重要功能或 bug 修复启动会话
• 在开始时明确设定目标

开发过程中

• 完成重要任务时定期更新
• 记录意外问题及其解决方案
• 跟踪破坏性变更或重要发现
• 记录新增的依赖项或配置更改

结束会话

• 始终以 /project:session-end 结束会话
• 检查生成的摘要是否完整
• 在关闭前补充任何缺失的上下文

知识传递

• 在开始类似工作之前回顾相关的过往会话
• 在提交信息中引用会话文件以提供上下文
• 使用会话摘要进行站会更新或报告

💡 使用场景

1. 功能开发

/project:session-start 用户认证
# 实现认证逻辑
/project:session-update 添加了中间件和登录页面
# 修复问题
/project:session-update 解决了 Next.js 15 的异步 Cookie 问题
/project:session-end

2. Bug 修复

/project:session-start 修复邮件退回处理
# 调查问题
/project:session-update 发现 AWS SNS Webhook 配置错误
# 实施修复
/project:session-update 更新了 Webhook 处理程序并添加了日志记录
/project:session-end

3. 代码重构

/project:session-start 数据库服务重构
# 制定重构计划
/project:session-update 创建了新的数据库服务类架构
# 执行更改
/project:session-update 将所有查询迁移到新服务
/project:session-end

🤖 对 AI 代理的好处

1. 上下文保留：会话提供了关于过往工作的丰富上下文
2. 决策历史：了解为何采用某些方法
3. 问题意识：知晓已遇到并解决的问题
4. 代码演进：跟踪代码库随时间的变化
5. 依赖管理：了解所使用的包和工具

🔍 技巧与提示

1. 可搜索的会话：在更新中使用一致的术语以便于搜索
2. 关联问题：在更新中引用工单编号或 GitHub 问题
3. 代码片段：将重要的代码更改包含在会话更新中
4. 截图：引用 UI 更改的截图路径
5. 测试说明：记录测试场景和结果

⚙️ 配置

自定义命令

编辑 commands/ 中的命令文件以：

• 更改会话文件格式
• 添加自定义章节
• 修改摘要生成方式
• 调整 Git 跟踪细节

会话存储

• 默认：sessions/
• 可通过更新命令文件更改
• 应考虑版本控制需求

🚨 故障排除

未找到活动会话

• 使用 /project:session-start 启动新会话
• 检查 sessions/.current-session 是否存在

会话更新不生效

• 确保会话处于活动状态
• 检查 sessions/ 中的文件权限

缺少 Git 信息

• 确认当前位于 Git 仓库中
• 检查 Git 是否已正确初始化

📚 示例

完整功能实现会话

# 开发会话 - 2025-01-16 13:47 - 活动编辑器

## 目标
- [x] 创建专用的活动编辑器
- [x] 添加 Markdown 支持
- [x] 实现自动保存

## 进展
[多条详细更新，记录了实现过程]

## 会话摘要
成功实现了具有 Markdown 支持、实时预览和自动保存功能的完整活动编辑器。解决了 Next.js 15 的兼容性问题，并添加了适当的错误处理。

🤝 贡献

要改进此系统：

1. 提升命令说明以增强 AI 的理解能力
2. 添加针对特定工作流的新命令
3. 改进会话文件格式
4. 创建用于会话分析的实用工具

📄 许可证

本会话管理系统为开源，可在任何项目中使用。

---

请记住：今天的良好文档能节省明天的调试时间！

Claude Sessions 快速上手指南

claude-sessions 是一套专为 Claude Code 设计的自定义斜杠命令（Slash Commands），旨在帮助开发者在多次编码会话中保持上下文连续性。它能自动记录开发进度、追踪 Git 变更、归档决策逻辑，并生成详细的会话文档，避免每次重新分析整个代码库。

环境准备

在使用本工具前，请确保满足以下条件：

• 运行环境：已安装并配置好 Claude Code CLI 工具。
• 版本控制：项目需初始化 Git 仓库（用于自动追踪变更状态）。
• 文件系统：拥有项目根目录的读写权限，用于创建 commands/ 和 sessions/ 目录。
• 网络要求：需能正常访问 GitHub 以克隆仓库（如遇网络问题，建议配置代理或使用国内镜像源下载后手动复制文件）。

安装步骤

1. 获取工具文件

将仓库克隆到本地，或直接复制核心文件夹到你的项目根目录。

# 方式一：克隆仓库（推荐）
git clone git@github.com:iannuttall/claude-sessions.git
# 进入项目目录并将必要文件夹移动到你的目标项目根目录
mv claude-sessions/commands claude-sessions/sessions /path/to/your/project/

# 方式二：手动复制
# 直接从源码中复制 commands/ 和 sessions/ 文件夹到你的项目根目录

2. 初始化会话存储

确保会话记录目录及追踪文件已创建。

cd /path/to/your/project
mkdir -p sessions
touch sessions/.current-session

3. 配置忽略规则（可选）

如果你不希望将会话记录文件提交到版本控制系统，请将以下内容添加到 .gitignore：

sessions/

注意：默认情况下，命令查找路径为项目根目录下的 commands/。若需适配 Claude Code 标准结构 (.claude/commands/)，可将 commands 文件夹移动至 .claude/ 目录下，并修改命令文件内的路径引用。

基本使用

安装完成后，在 Claude Code 的交互式会话中即可使用 /project: 前缀的命令。

1. 开始新会话

启动一个带有描述性名称的新开发会话（名称可选）。

/project:session-start authentication-refactor
# 或者不带名称，仅使用时间戳
/project:session-start

执行效果：创建一个新的 Markdown 会话文件，记录开始时间与目标。

2. 更新进度

在开发过程中记录关键进展、解决的问题或 Git 变更。

# 添加自定义备注
/project:session-update Implemented OAuth with Google
# 不带备注时，系统将自动总结近期的活动与变更
/project:session-update

3. 结束会话

完成当前任务后，生成包含完整摘要、待办事项状态和经验总结的最终报告。

/project:session-end

4. 查看状态与历史

随时检查当前会话详情或浏览过往记录。

# 查看当前活跃会话的状态
/project:session-current

# 列出所有历史会话及其摘要
/project:session-list

通过上述流程，你可以轻松实现开发过程的自动化文档化，让 AI 助手在后续会话中快速理解之前的工作背景。