项目会话管理技能：使用SESSION.md和Git检查点高效跟踪开发进度

project-session-management by jezweb/claude-skills

379 周安装量

643 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/jezweb/claude-skills --skill project-session-management

开发项目管理自动化

🇨🇳中文介绍

项目会话管理技能

使用 SESSION.md 配合 git 检查点和具体的下一步操作，跨工作会话跟踪进度。

使用时机

在 project-planning 生成 IMPLEMENTATION_PHASES.md 后启动项目时
上下文清除后恢复工作时
上下文满载时的阶段中期检查点
阶段转换时
跟踪实现 → 验证 → 调试循环

阶段与会话

阶段 (IMPLEMENTATION_PHASES.md): 工作单元（例如，“数据库模式”、“认证 API”）。有验证/退出标准。可能跨越多个会话。

会话 (SESSION.md): 上下文单元。在清除/压缩上下文前完成。可以完成一个阶段、阶段的一部分或多个小阶段。

示例 : 阶段 3 (Tasks API) → 会话 1 (GET/POST) → 会话 2 (PATCH/DELETE) → 会话 3 (验证) ✅

工作流程

启动新项目 :

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

结束会话 :

自动 : /wrap-session（更新 SESSION.md，创建检查点提交，输出摘要）

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

FlyClaw：零登录航班聚合查询工具，Python实现多源航班信息与价格搜索

4,000,000 周安装

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

762,600 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

258,600 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

208,300 周安装

手动 : 更新 SESSION.md → git 检查点 → 设置具体的“下一步操作”

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

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

/continue-session : 加载 SESSION.md + 规划文档 → 显示 git 历史记录 + 摘要 → 显示验证标准（如果在验证阶段）→ 打开“下一步操作”文件 → 请求继续许可

目的 : 导航中心，引用规划文档，跟踪当前进度目标 : 项目根目录下 <200 行 更新时机 : 在取得重大进展后（不是每次更改）

# 会话状态

**当前阶段**: 阶段 3
**当前状态**: 实现 (或 验证/调试)
**最后检查点**: abc1234 (2025-10-23)
**规划文档**: `docs/IMPLEMENTATION_PHASES.md`, `docs/ARCHITECTURE.md`

---

## 阶段 1: 设置 ✅
**完成时间**: 2025-10-15 | **检查点**: abc1234
**摘要**: Vite + React + Tailwind v4 + D1 绑定

## 阶段 2: 数据库 ✅
**完成时间**: 2025-10-18 | **检查点**: def5678
**摘要**: D1 模式 + 迁移 + 种子数据

## 阶段 3: Tasks API 🔄
**类型**: API | **开始时间**: 2025-10-23
**规范**: `docs/IMPLEMENTATION_PHASES.md#phase-3`

**进度**:
- [x] GET /api/tasks 端点 (提交: ghi9012)
- [x] POST /api/tasks 端点 (提交: jkl3456)
- [ ] PATCH /api/tasks/:id ← **当前**
- [ ] DELETE /api/tasks/:id
- [ ] 验证所有端点 (参见 IMPLEMENTATION_PHASES.md 中的标准)

**下一步操作**: 在 src/routes/tasks.ts:47 实现 PATCH /api/tasks/:id，处理验证和所有权检查

**关键文件**:
- `src/routes/tasks.ts`
- `src/lib/schemas.ts`

**已知问题**: 无

## 阶段 4: 任务界面 ⏸️
**规范**: `docs/IMPLEMENTATION_PHASES.md#phase-4`

一致使用以下表情符号状态图标：

⏸️ = 未开始（待定）
🔄 = 进行中
✅ = 完成
🚫 = 受阻

实现 → 编写代码
验证 → 根据标准测试
调试 → 修复问题

使用当前状态和进度更新 SESSION.md。示例：

**当前状态**: 验证

**验证进度**:
- [x] GET /api/tasks 返回 200 ✅
- [x] POST /api/tasks 创建任务 ✅
- [ ] POST 无效数据返回 400 ❌ (返回 500)

**当前问题**: 无效数据返回 500。检查 src/middleware/validate.ts

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

❌ 不复制代码，不重复 IMPLEMENTATION_PHASES.md 内容，不使用模糊的操作，保持 <200 行

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 运行后：

阅读 IMPLEMENTATION_PHASES.md
在根目录创建 SESSION.md：阶段 1 设为 🔄，其他设为 ⏸️
展开阶段 1，包含任务清单
设置具体的“下一步操作”
输出以供审阅

询问：“您希望我创建 SESSION.md 来跟踪这些阶段的进度吗？（明确当前阶段、进度跟踪、轻松恢复、git 检查点格式）”

模板 : SESSION.md.template, checkpoint-commit-format.md, CLAUDE-session-snippet.md

脚本 : resume.sh (显示当前状态)

参考资料 : session-handoff-protocol.md, best-practices.md

🇺🇸English

Project Session Management Skill

Track progress across work sessions using SESSION.md with git checkpoints and concrete next actions.

When to Use

Starting projects after project-planning generates IMPLEMENTATION_PHASES.md
Resuming work after context clears
Mid-phase checkpoints when context is full
Phase transitions
Tracking Implementation → Verification → Debugging cycle

Phases vs Sessions

Phases (IMPLEMENTATION_PHASES.md): Units of WORK (e.g., "Database Schema", "Auth API"). Have verification/exit criteria. May span multiple sessions.

Sessions (SESSION.md): Units of CONTEXT. Complete before clearing/compacting context. Can complete a phase, part of a phase, or multiple small phases.

Example : Phase 3 (Tasks API) → Session 1 (GET/POST) → Session 2 (PATCH/DELETE) → Session 3 (verify) ✅

Workflow

Starting New Project :

After project-planning creates IMPLEMENTATION_PHASES.md, offer: "Create SESSION.md to track progress?"
Generate SESSION.md from phases, set Phase 1 as 🔄 (in progress), set concrete "Next Action"

Ending Session :

Automated : /wrap-session (updates SESSION.md, creates checkpoint commit, outputs summary)
Manual : Update SESSION.md → git checkpoint → set concrete "Next Action"

Resuming :

Automated : /continue-session (loads context, shows summary, continues from "Next Action")
Manual : Read SESSION.md → check "Next Action" → continue

Automation Commands

/wrap-session : Analyzes state → updates SESSION.md → updates related docs → creates checkpoint commit → outputs summary → optionally pushes

/continue-session : Loads SESSION.md + planning docs → shows git history + summary → displays verification criteria (if in Verification stage) → opens "Next Action" file → asks permission to continue

SESSION.md Structure

Purpose : Navigation hub referencing planning docs, tracking current progress Target : <200 lines in project root Update : After significant progress (not every change)

Template

# 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`

Status Icons

Use these emoji status icons consistently:

⏸️ = Not started (pending)
🔄 = In progress
✅ = Complete
🚫 = Blocked

Stages Within a Phase

Implementation → Writing code
Verification → Testing against criteria
Debugging → Fixing issues

Update SESSION.md with current stage and progress. Example:

**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 Guidelines

✅ Collapse completed phases (2-3 lines), concrete "Next Action" (file+line+task), reference planning docs, checkpoint at phase end or when context full

❌ No code copying, no duplicating IMPLEMENTATION_PHASES.md, no vague actions, keep <200 lines

Git Checkpoint Format

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]

Example (Phase Complete):

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

Expected Uncommitted Files (CRITICAL)

Checkpoint Cycle : /wrap-session creates commit → gets hash → updates SESSION.md with hash. Therefore SESSION.md is always uncommitted when resuming (BY DESIGN).

Expected uncommitted files (no warning):

SESSION.md - Checkpoint hash updated post-commit, always uncommitted between sessions (NORMAL)
CLAUDE.md - Often updated during dev, may be uncommitted (NORMAL)
.roomodes - Editor/IDE state, not relevant to session handoff (SAFE TO IGNORE)

Warning triggers (unexpected):

Source files (.ts, .tsx, .js)
Config files (vite.config.ts, wrangler.jsonc)
Planning docs (IMPLEMENTATION_PHASES.md, ARCHITECTURE.md)
New untracked files

/continue-session behavior:

ℹ️ Info message when only SESSION.md/CLAUDE.md/.roomodes uncommitted
⚠️ Warning when code/doc changes uncommitted (shows filtered list excluding expected files)

Context Management

Context full mid-phase : Update SESSION.md → checkpoint → clear context → read SESSION.md + planning docs → continue from "Next Action"

Phase complete : Check verification criteria → mark 🔄→✅ → checkpoint → move next phase ⏸️→🔄

Troubleshooting : Update to "Debugging" stage → document "Current Issue" → when fixed, return to "Verification" or "Implementation"

Integration with project-planning

project-planning generates IMPLEMENTATION_PHASES.md (the plan) → project-session-management creates SESSION.md (the tracker) → work through phases → git checkpoints → resume from SESSION.md

Planning docs (/docs): Reference material, rarely change SESSION.md (root): Living document, updates constantly

Creating SESSION.md for New Project

After project-planning runs:

Read IMPLEMENTATION_PHASES.md
Create SESSION.md in root: Phase 1 as 🔄, others as ⏸️
Expand Phase 1 with task checklist
Set concrete "Next Action"
Output for review

Offer: "Would you like me to create SESSION.md to track progress through these phases? (clear current phase, progress tracking, easy resume, git checkpoint format)"

Bundled Resources

Templates : SESSION.md.template, checkpoint-commit-format.md, CLAUDE-session-snippet.md

Scripts : resume.sh (show current state)

References : session-handoff-protocol.md, best-practices.md

Weekly Installs

379

Repository

jezweb/claude-skills

GitHub Stars

643

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

claude-code313

opencode254

gemini-cli244

cursor232

codex222

antigravity219

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

138,300 周安装