project-session-management

项目会话管理技能

使用 SESSION.md 跟踪各工作会话的进度，并通过 Git 检查点和明确的后续操作进行记录。

---

适用场景

• project-planning 生成 IMPLEMENTATION_PHASES.md 后启动项目
• 上下文清除后恢复工作
• 上下文已满时创建阶段中途检查点
• 阶段转换
• 跟踪“实现 → 验证 → 调试”循环

---

阶段与会话

阶段（IMPLEMENTATION_PHASES.md）：工作单元（例如“数据库架构”“身份验证 API”）。包含验证／退出标准，可能跨多个会话。

会话（SESSION.md）：上下文单元。在清除／压缩上下文前完成。可以完成一个阶段、阶段的一部分，或多个小阶段。

示例：阶段 3（任务 API）→ 会话 1（GET/POST）→ 会话 2（PATCH/DELETE）→ 会话 3（验证）✅

---

工作流

启动新项目：

1. project-planning 创建 IMPLEMENTATION_PHASES.md 后，询问：“创建 SESSION.md 来跟踪进度吗？”
2. 根据阶段生成 SESSION.md，将阶段 1 设为 🔄（进行中），并设置明确的“下一步操作”

结束会话：

• 自动：/wrap-session（更新 SESSION.md、创建检查点提交、输出摘要）
• 手动：更新 SESSION.md → Git 检查点 → 设置明确的“下一步操作”

恢复工作：

• 自动：/continue-session（加载上下文、显示摘要、从“下一步操作”继续）
• 手动：阅读 SESSION.md → 查看“下一步操作” → 继续

---

自动化命令

/wrap-session：分析状态 → 更新 SESSION.md → 更新相关文档 → 创建检查点提交 → 输出摘要 → 可选推送

/continue-session：加载 SESSION.md + 规划文档 → 显示 Git 历史记录 + 摘要 → 显示验证标准（处于验证阶段时）→ 打开“下一步操作”对应的文件 → 询问是否继续

---

SESSION.md 结构

用途：导航中心，用于引用规划文档并跟踪当前进度
目标：项目根目录下少于 200 行
更新时机：取得重大进展后（不是每次变更后）

模板

# Session State

**Current Phase**: Phase 3
**Current Stage**: Implementation (or Verification/Debugging)
**Last Checkpoint**: abc1234 (2025-10-23)
**Planning Docs**: `docs/IMPLEMENTATION_PHASES.md`, `docs/ARCHITECTURE.md`

---

## Phase 1: Setup ✅
**Completed**: 2025-10-15 | **Checkpoint**: abc1234
**Summary**: Vite + React + Tailwind v4 + D1 binding

## Phase 2: Database ✅
**Completed**: 2025-10-18 | **Checkpoint**: def5678
**Summary**: D1 schema + migrations + seed data

## Phase 3: Tasks API 🔄
**Type**: API | **Started**: 2025-10-23
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-3`

**Progress**:
- [x] GET /api/tasks endpoint (commit: ghi9012)
- [x] POST /api/tasks endpoint (commit: jkl3456)
- [ ] PATCH /api/tasks/:id ← **CURRENT**
- [ ] DELETE /api/tasks/:id
- [ ] Verify all endpoints (see IMPLEMENTATION_PHASES.md for criteria)

**Next Action**: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47, handle validation and ownership check

**Key Files**:
- `src/routes/tasks.ts`
- `src/lib/schemas.ts`

**Known Issues**: None

## Phase 4: Task UI ⏸️
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-4`

---

状态图标

请始终如一地使用以下表情符号状态图标：

• ⏸️ = 尚未开始（待处理）
• 🔄 = 进行中
• ✅ = 已完成
• 🚫 = 已阻塞

---

阶段内的步骤

1. 实现 → 编写代码
2. 验证 → 根据标准进行测试
3. 调试 → 修复问题

在 SESSION.md 中更新当前步骤和进度。示例：

**Current Stage**: Verification

**Verification Progress**:
- [x] GET /api/tasks returns 200 ✅
- [x] POST /api/tasks creates task ✅
- [ ] POST with invalid data returns 400 ❌ (returns 500)

**Current Issue**: Invalid data returning 500. Check src/middleware/validate.ts

---

SESSION.md 指南

✅ 折叠已完成的阶段（2–3 行），明确“下一步操作”（文件+行号+任务），引用规划文档，在阶段结束或上下文已满时创建检查点

❌ 不复制代码，不重复 IMPLEMENTATION_PHASES.md 内容，不写模糊的操作，保持少于 200 行

---

Git 检查点格式

checkpoint: Phase [N] [Status] - [Brief Description]

Phase: [N] - [Name]
Status: [Complete/In Progress/Paused]
Session: [What was accomplished this session]

Files Changed:
- path/to/file.ts (what changed)

Next: [Concrete next action]

示例（阶段完成）：

checkpoint: Phase 3 Complete - Tasks API

Phase: 3 - Tasks API
Status: Complete
Session: Completed all CRUD endpoints and verified functionality

Files Changed:
- src/routes/tasks.ts (all CRUD operations)
- src/lib/schemas.ts (task validation)

Next: Phase 4 - Start building Task List UI component

---

预期的未提交文件（重要）

检查点周期：/wrap-session 创建提交 → 获取哈希值 → 使用该哈希值更新 SESSION.md。因此，恢复工作时 SESSION.md 始终处于未提交状态（这是设计如此）。

预期的未提交文件（无需警告）：

• SESSION.md - 检查点哈希值在提交后更新，因此会话之间始终处于未提交状态（正常）
• CLAUDE.md - 开发过程中经常会更新，可能尚未提交（正常）
• .roomodes - 编辑器／IDE 状态，与会话交接无关（可安全忽略）

警告触发条件（意外情况）：

• 源文件（.ts、.tsx、.js）
• 配置文件（vite.config.ts、wrangler.jsonc）
• 规划文档（IMPLEMENTATION_PHASES.md、ARCHITECTURE.md）
• 新的未跟踪文件

/continue-session 行为：

• 仅 SESSION.md/CLAUDE.md/.roomodes 处于未提交状态时，显示 ℹ️ 信息
• 代码／文档变更处于未提交状态时，显示 ⚠️ 警告（显示筛选后的列表，不包含预期文件）

上下文管理

阶段中途上下文已满：更新 SESSION.md → 创建检查点 → 清空上下文 → 阅读 SESSION.md + 规划文档 → 从“下一步操作”继续

阶段已完成：检查验证标准 → 将 🔄 标记为 ✅ → 创建检查点 → 进入下一阶段，将 ⏸️ 标记为 🔄

故障排除：将阶段更新为“调试” → 记录“当前问题” → 修复后，返回“验证”或“实施”

---

与 project-planning 集成

project-planning 生成 IMPLEMENTATION_PHASES.md（计划）→ project-session-management 创建 SESSION.md（跟踪文档）→ 按阶段推进 → 创建 git 检查点 → 从 SESSION.md 恢复

规划文档（/docs）：参考资料，很少更改 SESSION.md（根目录）：持续更新的文档

---

为新项目创建 SESSION.md

project-planning 运行后：

1. 阅读 IMPLEMENTATION_PHASES.md
2. 在根目录创建 SESSION.md：将阶段 1 标记为 🔄，其余阶段标记为 ⏸️
3. 为阶段 1 添加任务清单
4. 设置明确的“下一步操作”
5. 输出供审阅

提示：“你希望我创建 SESSION.md 来跟踪这些阶段的进度吗？（明确当前阶段、跟踪进度、便于恢复、采用 git 检查点格式）”

---

附带资源

模板：SESSION.md.template、checkpoint-commit-format.md、CLAUDE-session-snippet.md

脚本：resume.sh（显示当前状态）

参考资料：session-handoff-protocol.md、best-practices.md