Back to Details

dev-session

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Dev Session

开发会话（Dev Session）

Manage multi-session development work with structured progress files, checkpoint commits, and durable learnings. Produces SESSION.md files that survive context compaction and enable clean handoff between sessions.
通过结构化进度文件、checkpoint提交和持久化学习内容，管理跨多会话的开发工作。生成的SESSION.md文件可在上下文压缩后保留，支持会话间的顺畅交接。

Operating Modes

操作模式

Mode 1: Start Session

模式1：启动会话（Start Session）

When: Beginning multi-step work, "start session", "new session for [feature]"
  1. Check if 
    SESSION.md
    already exists in the project root
    • If yes: read it and ask whether to continue the existing session or start fresh
    • If no: create from template (see references/session-template.md)
  2. Pre-fill fields:
    • Project: from CLAUDE.md or directory name
    • Branch: from 
      git branch --show-current
    • Last Updated: current timestamp
    • Phase: ask user what they're working on
  3. Read the project's CLAUDE.md to orient on context
  4. Present a brief summary: "Session started. Working on [phase] on branch [branch]."
触发时机：开始多步骤工作时，输入“start session”“new session for [feature]”
  1. 检查项目根目录是否已存在
    SESSION.md
    • 若存在：读取文件并询问用户是继续现有会话还是重新开始
    • 若不存在：根据模板创建（参考references/session-template.md）
  2. 预填字段：
    • 项目：来自CLAUDE.md或目录名称
    • 分支：来自
      git branch --show-current
      命令结果
    • 最后更新时间：当前时间戳
    • 阶段：询问用户当前工作内容
  3. 读取项目的CLAUDE.md以获取上下文信息
  4. 展示简要总结：“会话已启动。正在[分支]分支上进行[阶段]相关工作。”

Mode 2: Checkpoint

模式2：创建Checkpoint

When: "checkpoint", major milestone reached, before risky changes, context getting large
  1. Update SESSION.md:
    • Add completed items to What Works
    • Update Current Position with exact location (file paths, line numbers)
    • Clear resolved Blockers, add new ones
    • Write concrete Resume Instructions
  2. Capture learnings:
    • If any patterns, gotchas, or commands were discovered during work, add them to CLAUDE.md
    • One line per concept — concise, not verbose
  3. Git checkpoint:
    bash
    git add -A && git commit -m "WIP: [what was accomplished]"
  4. Record the commit hash in SESSION.md under Checkpoint
  5. Confirm: "Checkpointed at [hash]. SESSION.md updated."
触发时机：输入“checkpoint”、达到重要里程碑、进行高风险变更前、上下文内容过多时
  1. 更新SESSION.md：
    • 将已完成项添加到可用功能（What Works）
    • 在**当前位置（Current Position）**中更新具体位置（文件路径、行号）
    • 清除已解决的阻塞问题（Blockers），添加新的阻塞问题
    • 编写具体的恢复指引（Resume Instructions）
  2. 记录学习内容：
    • 若在工作中发现任何模式、注意事项或命令，将其添加到CLAUDE.md
    • 每个概念一行——简洁明了，避免冗长
  3. Git Checkpoint：
    bash
    git add -A && git commit -m "WIP: [what was accomplished]"
  4. 在SESSION.md的Checkpoint部分记录提交哈希值
  5. 确认提示：“已在[哈希值]处创建Checkpoint。SESSION.md已更新。”

Mode 3: Resume Session

模式3：恢复会话（Resume Session）

When: "resume", "continue from last session", "where were we", start of a new conversation
  1. Read 
    SESSION.md
    — if missing, inform user and offer to start a new session
  2. Read the project's 
    CLAUDE.md
    for context
  3. Check what's changed since the recorded checkpoint:
    bash
    git log --oneline [checkpoint-hash]..HEAD
  4. Check for uncommitted changes: 
    git status
  5. Present a summary:
    • Phase: what we were working on
    • Position: where we left off
    • Changes since: any commits or modifications since checkpoint
    • Blockers: anything unresolved
    • Suggested next step: first item from Resume Instructions
触发时机：输入“resume”“continue from last session”“where were we”、开启新对话时
  1. 读取
    SESSION.md
    ——若文件不存在，告知用户并提供启动新会话的选项
  2. 读取项目的
    CLAUDE.md
    获取上下文信息
  3. 检查自记录的Checkpoint以来的变更：
    bash
    git log --oneline [checkpoint-hash]..HEAD
  4. 检查未提交的变更：
    git status
  5. 展示总结信息：
    • 阶段：之前正在进行的工作内容
    • 位置：上次结束时的工作位置
    • 自上次以来的变更：自Checkpoint以来的所有提交或修改
    • 阻塞问题：所有未解决的问题
    • 建议下一步：恢复指引中的第一项内容

Mode 4: Wrap Session

模式4：结束会话（Wrap Session）

When: "wrap session", "done for now", "save progress", ending a session
  1. Run a full checkpoint (Mode 2)
  2. Review SESSION.md for completeness:
    • Are Resume Instructions concrete enough for a fresh session to continue?
    • Is Current Position specific (file paths, not vague descriptions)?
  3. If the phase is complete:
    • Collapse the phase summary to 2-3 lines
    • Clear Resume Instructions or note "Phase complete — ready for next phase"
  4. Confirm: "Session wrapped. Resume with 'resume session' next time."
触发时机：输入“wrap session”“done for now”“save progress”、结束会话时
  1. 执行完整的Checkpoint操作（模式2）
  2. 检查SESSION.md的完整性：
    • 恢复指引是否足够具体，以便新会话能够顺利继续？
    • 当前位置是否明确（文件路径，而非模糊描述）？
  3. 若当前阶段已完成：
    • 将阶段总结压缩为2-3行
    • 清除恢复指引或标注“阶段已完成——准备进入下一阶段”
  4. 确认提示：“会话已结束。下次可使用‘resume session’恢复。”

When to Use

使用场景

ScenarioUse this skill?
Multi-phase feature spanning 2+ sessionsYes
Work that might hit context compactionYes
Before making risky or destructive changesYes (checkpoint first)
Quick bug fix or single-file editNo
Single-session task with clear scopeNo
场景是否使用该技能？
跨2个及以上会话的多阶段功能开发是
可能遇到上下文压缩的工作是
进行高风险或破坏性变更前是（先创建Checkpoint）
快速修复bug或单文件编辑否
范围明确的单会话任务否

SESSION.md Principles

SESSION.md原则

  • Track progress, not architecture — SESSION.md is a work log, not project documentation
  • Concrete over vague — "Resume at 
    src/auth.ts:42
    , implement token refresh" beats "Continue auth work"
  • Collapse completed work — finished phases become 1-2 line summaries
  • Keep under 100 lines — if it's longer, collapse more aggressively
  • 跟踪进度，而非架构——SESSION.md是工作日志，而非项目文档
  • 具体而非模糊——“在
    src/auth.ts:42
    处恢复，实现令牌刷新”优于“继续认证相关工作”
  • 压缩已完成工作——已完成阶段需精简为1-2行总结
  • 保持篇幅在100行以内——若过长，需进一步压缩内容

Autonomy Rules

自治规则

  • Just do it: Read SESSION.md, read CLAUDE.md, check git status/log, present summaries
  • Brief confirmation: Creating new SESSION.md, committing WIP checkpoints
  • Ask first: Overwriting an existing SESSION.md, deleting session data
  • 直接执行：读取SESSION.md、读取CLAUDE.md、检查git状态/日志、展示总结
  • 简要确认：创建新SESSION.md、提交WIP Checkpoint时
  • 先询问用户：覆盖现有SESSION.md、删除会话数据时

Reference Files

参考文件

WhenRead
Creating a new SESSION.mdreferences/session-template.md
Context compaction tips, what survivesreferences/compaction-survival.md
时机读取文件
创建新SESSION.md时references/session-template.md
了解上下文压缩注意事项、哪些内容会被保留时references/compaction-survival.md