Claude Code会话全生命周期管理实战：从创建到归档的完整掌控

~/.claude/
├── projects/
│   └── -home-gprshome-myproject/    # 项目路径编码
│       ├── session-abc123.jsonl      # 会话文件
│       ├── session-def456.jsonl
│       └── ...
├── settings.json                     # 全局设置
└── credentials.json                  # 认证信息

{"type":"user","message":{"role":"user","content":"帮我分析这个项目的依赖关系"},"timestamp":"2026-05-21T08:30:00Z"}
{"type":"assistant","message":{"role":"assistant","content":"我来分析..."},"timestamp":"2026-05-21T08:30:05Z","toolUses":["Read","Grep","Glob"]}
{"type":"tool_result","toolName":"Read","result":"文件内容...","timestamp":"2026-05-21T08:30:06Z"}
{"type":"summary","content":"用户要求分析项目依赖，已读取package.json和tsconfig.json","contextUsed":45000,"contextTotal":200000}

# 查看当前会话ID（在Claude Code内部输入）
/status

# 输出示例：
# Session: a3f8c2e1-9b4d-4f7a-b5e6-1234567890ab
# Context: 45,230 / 200,000 tokens (22.6%)
# Cost: $0.12

# 恢复上一个会话，继续对话
claude --continue

# 简写形式
claude -c

# 恢复并直接发送新消息（非交互模式）
claude --continue -p "继续完成昨天未完成的测试"

# 列出最近会话供选择
claude --resume

# 输出交互式列表：
# ? Select a session to resume:
# ❯ a3f8c2e1 - "重构认证模块" (2 hours ago, 45K tokens)
#   b7d4e3f2 - "修复支付Bug" (5 hours ago, 28K tokens)
#   c9e5f4a3 - "添加用户导出功能" (1 day ago, 62K tokens)

# 通过会话ID精确恢复
claude --resume a3f8c2e1-9b4d-4f7a-b5e6-1234567890ab

# 启动带名称的会话
claude --session-id auth-refactor

# 恢复命名会话
claude --resume auth-refactor

> /session-name auth-refactor-phase2
Session renamed to: auth-refactor-phase2

# 列出所有会话（含摘要）
claude --sessions

# 搜索包含特定关键词的会话
claude --sessions --grep "认证模块"

# 在headless模式下搜索
claude -p "列出所有与支付相关的历史会话"

# 在Claude Code交互中
> /branch try-redis-cache
Created branch: try-redis-cache
Current context preserved. You can now explore an alternative approach.

# 现在你可以大胆尝试Redis缓存方案
# 如果不理想，切回主干继续

gitGraph
    commit id: "初始对话"
    commit id: "分析需求"
    commit id: "设计方案A"
    branch try-redis-cache
    checkout try-redis-cache
    commit id: "实现Redis方案"
    commit id: "测试失败"
    checkout main
    commit id: "改用方案B"
    commit id: "实现Memcached"
    commit id: "测试通过 ✓"

# 从最近的会话创建分支
claude --continue --fork-session cache-experiment

# 从指定会话创建分支
claude --resume a3f8c2e1 --fork-session parallel-approach

# 创建分支并立即执行任务
claude --resume a3f8c2e1 --fork-session quick-test -p "尝试用B-tree替代哈希表实现"

# 步骤1：在主会话中完成基础设计
> 帮我设计数据库访问层的重构方案
[...完成方案设计...]

# 步骤2：创建分支A - Prisma方案
> /branch try-prisma
> 按照方案用Prisma实现UserRepository
[...完成Prisma实现...]

# 步骤3：切回主会话
> /branch try-typeorm
> 按照方案用TypeORM实现UserRepository
[...完成TypeORM实现...]

# 步骤4：对比评估
> 对比两个分支的实现，分析性能差异

graph LR
    A[会话开始<br/>0% 上下文] --> B[轻度对话<br/>20-30%]
    B --> C[工具密集调用<br/>50-60%]
    C --> D{到达阈值?}
    D -->|否| C
    D -->|是 60%| E[建议 /compact]
    D -->|是 90%| F[自动压缩]
    E --> G[手动压缩<br/>保留关键信息]
    F --> G
    G --> H[压缩后<br/>15-25%]
    H --> C

# 手动压缩（推荐在上下文60%时执行）
> /compact
Compacting conversation...
Summary generated. Context reduced from 125,000 to 18,000 tokens (85.6% reduction).

# 带指令的压缩——强调保留特定信息
> /compact 保留所有已修改文件的路径和修改原因，丢弃工具调用的详细输出

# 策略1：主动压缩（推荐）
在上下文达到50-60%时主动执行 /compact
优点：信息损失最小，AI有足够上下文生成高质量摘要

# 策略2：阈值触发
在上下文达到80%时执行
优点：保留更多细节
缺点：压缩质量下降，接近极限时AI推理能力减弱

# 策略3：阶段转换时压缩
每完成一个子任务后执行
优点：每个阶段有清晰的压缩锚点

> /clear
Context cleared. Starting fresh in current project.

# 带说明的重置
> /clear 放弃当前方向，从零开始重新设计API

> /cost
Session cost breakdown:
┌─────────────────────────────────────────┐
│ Input tokens:     89,230  ($0.27)       │
│ Output tokens:    12,450   ($0.19)      │
│ Cache read:       45,000   ($0.02)      │
│ Cache creation:   67,800   ($0.34)      │
│─────────────────────────────────────────│
│ Total:                     $0.82        │
│ Context window: 146,680 / 200,000 (73%) │
│ Suggestion: Consider /compact           │
└─────────────────────────────────────────┘

# 终端1：前端模块
claude --session-id frontend-dashboard
> 实现Dashboard页面的数据可视化组件...

# 终端2：后端API
claude --session-id api-v2-endpoints
> 为Dashboard设计REST API端点...

# 终端3：数据库迁移
claude --session-id db-migration-may
> 编写v2到v3的数据库迁移脚本...

graph TD
    A[Day 1: 会话 init-project] --> B[初始化项目结构]
    B --> C[/compact 阶段性压缩]
    C --> D[完成基础架构]
    D --> E[Day 2: --continue]
    E --> F[实现核心功能]
    F --> G[/branch try-new-algo]
    G --> H[Day 3: --resume分支]
    H --> I[性能测试与优化]
    I --> J[Day 4: --resume主会话]
    J --> K[集成与E2E测试]
    K --> L[/compact 最终压缩]
    L --> M[Day 5: --continue]
    M --> N[部署与文档]

# 在会话A中写入项目状态
> 更新CLAUDE.md，添加以下进度信息：
> - 认证模块已完成（JWT + Refresh Token）
> - 下一步：实现RBAC权限系统
> - 注意事项：使用casbin库，参考/docs/rbac-design.md

# 在会话B中自动继承
claude --session-id rbac-impl
# Claude Code自动读取项目根目录的CLAUDE.md

# 会话A：生成设计文档
claude -p "将当前认证模块的架构设计写入 docs/auth-architecture.md"

# 会话B：读取设计文档
claude --session-id rbac-impl -p "阅读docs/auth-architecture.md，基于其中的设计实现RBAC"

# 在任意会话中
> /memory 添加：项目使用pnpm，不要用npm
> /memory 添加：数据库迁移必须向后兼容

# 这些记忆会在所有新会话中自动加载

#!/bin/bash
# ci-code-review.sh - CI中的代码审查脚本

# 获取PR变更
git diff origin/main...HEAD > /tmp/pr-diff.patch

# 使用命名会话，方便追踪
claude -p \
  --session-id "pr-review-$(date +%Y%m%d-%H%M%S)" \
  --output-format json \
  --max-turns 5 \
  "审查以下代码变更，关注安全问题和性能隐患: $(cat /tmp/pr-diff.patch)"

# 查看历史CI审查会话
claude --sessions --grep "pr-review"

主会话 (session-abc123)
├── 用户请求："重构整个认证系统"
├── Task工具 → Subagent-1 (session-sub-001)
│   └── 独立上下文："重构JWT签发逻辑"
├── Task工具 → Subagent-2 (session-sub-002)
│   └── 独立上下文："重写权限中间件"
└── 汇总结果 → 主会话继续

import { ClaudeCode } from '@anthropic-ai/claude-code';

// 自定义会话存储后端
const agent = new ClaudeCode({
  sessionStorage: {
    // 将会话存储到S3
    async save(sessionId, data) {
      await s3.putObject({
        Bucket: 'claude-sessions',
        Key: `${sessionId}.jsonl`,
        Body: JSON.stringify(data),
      });
    },
    async load(sessionId) {
      const result = await s3.getObject({
        Bucket: 'claude-sessions',
        Key: `${sessionId}.jsonl`,
      });
      return JSON.parse(result.Body);
    },
  },
});

# 内置诊断
> /doctor
Running diagnostics...
✓ API connection: healthy
✓ Context window: 45% used (good)
✓ Session file: intact (2.3MB)
⚠ Last compact: 4 hours ago (consider /compact)
✓ Project config: CLAUDE.md found
✓ MCP servers: 3 connected

# 手动检查会话文件
ls -lh ~/.claude/projects/-home-myproject/*.jsonl

# 输出：
# -rw-r--r--  1 user  staff  2.3M  session-abc123.jsonl
# -rw-r--r--  1 user  staff  890K  session-def456.jsonl
# -rw-r--r--  1 user  staff  4.1M  session-ghi789.jsonl  ← 过大，需要compact

graph TD
    subgraph "Week 1: 基础架构"
        A1[session: init-scaffold] --> A2[session: db-schema-v2]
        A2 --> A3[session: api-gateway]
    end
    subgraph "Week 2: 核心业务"
        B1[session: user-auth] --> B2[session: order-flow]
        B2 --> B3[session: payment-integration]
    end
    subgraph "Week 3: 测试与部署"
        C1[session: e2e-testing] --> C2[session: perf-optimization]
        C2 --> C3[session: deployment]
    end
    A3 --> B1
    B3 --> C1

# 创建项目并启动首个会话
cd ~/ecommerce-refactor
claude --session-id init-scaffold

# 在会话中
> 这是一个Express.js电商后端项目，需要重构为模块化架构。
> 先分析当前项目结构，然后提出重构方案。

# 完成后压缩
> /compact 保留项目结构分析结果和重构方案决策

# 结束会话
> /cost  # 记录消耗：$0.45
> exit

# 新会话，但延续项目知识
claude --session-id db-schema-v2

# CLAUDE.md已包含昨日决策，Claude自动继承上下文
> 基于昨天的重构方案，设计新的数据库Schema。
> 要求支持多租户、软删除、完整的审计日志。

# 遇到设计分歧时使用分支
> /branch try-nosql
> 尝试用MongoDB替代PostgreSQL的设计方案

# 评估后决定保留PostgreSQL
> /branch try-multi-tenant-schema
> 用Schema隔离方案实现多租户

# 压缩保存
> /compact 保留最终Schema设计和放弃的方案及其原因

claude --continue  # 继续昨天的会话

# 上下文已满60%，先压缩
> /compact 保留已完成的认证流程图和JWT配置，丢弃中间调试日志

# 继续开发
> 实现Refresh Token轮换机制

# 发现安全漏洞需要紧急修复
> /branch hotfix-token-validation
> Token验证存在时间攻击漏洞，立即修复

# 修复完成后回到主线
> /compact
> 继续实现RBAC权限系统

# 恢复多个会话进行集成
claude --session-id integration-test

# 引用之前会话的成果
> 读取以下文件了解已完成模块的接口定义：
> - docs/auth-api.md（来自user-auth会话）
> - docs/order-api.md（来自order-flow会话）
> - docs/payment-api.md（来自payment-integration会话）
> 
> 编写跨模块的集成测试

# 使用 /compact 管理大量测试输出
> /compact 保留失败的测试用例和错误信息，丢弃通过的测试详细输出

#!/bin/bash
# session-manager.sh - 项目会话管理工具

PROJECT_DIR="$HOME/ecommerce-refactor"
SESSIONS_DIR="$HOME/.claude/projects/$(echo $PROJECT_DIR | sed 's/\//-/g')"

# 列出所有会话及大小
list_sessions() {
    echo "=== 项目会话列表 ==="
    for f in "$SESSIONS_DIR"/*.jsonl; do
        size=$(du -h "$f" | cut -f1)
        name=$(basename "$f" .jsonl)
        modified=$(stat -f "%Sm" -t "%Y-%m-%d %H:%M" "$f" 2>/dev/null || stat -c "%y" "$f" | cut -d'.' -f1)
        lines=$(wc -l < "$f")
        echo "[$size] $name | 修改: $modified | 记录数: $lines"
    done
}

# 清理30天前的旧会话
archive_old_sessions() {
    echo "=== 归档30天前的会话 ==="
    find "$SESSIONS_DIR" -name "*.jsonl" -mtime +30 | while read f; do
        echo "归档: $(basename $f)"
        gzip "$f"  # 压缩但不删除
    done
}

# 会话大小预警
check_session_health() {
    echo "=== 会话健康检查 ==="
    for f in "$SESSIONS_DIR"/*.jsonl; do
        size=$(stat -f%z "$f" 2>/dev/null || stat -c%s "$f")
        if [ "$size" -gt 5242880 ]; then  # >5MB
            echo "⚠ $(basename $f): $(( size / 1024 ))KB — 建议compact或归档"
        elif [ "$size" -gt 10485760 ]; then  # >10MB
            echo "🔴 $(basename $f): $(( size / 1024 ))KB — 严重过大！"
        else
            echo "✓ $(basename $f): $(( size / 1024 ))KB"
        fi
    done
}

case "${1:-list}" in
    list)   list_sessions ;;
    archive) archive_old_sessions ;;
    health) check_session_health ;;
    *)      echo "用法: $0 {list|archive|health}" ;;
esac

# 错误示范
> 继续继续继续...  # 上下文95%
> 再加一个功能...   # 上下文98%
> 为什么回答质量下降了？  # 上下文100%，AI被迫自动压缩

# 错误示范：用同一个会话处理前端、后端、DevOps
> 帮我写React组件
> 然后配置K8s部署
> 再写个数据库迁移脚本

会话生命周期命令一览：

# 创建
claude                          # 新建会话
claude --session-id <name>      # 命名会话

# 延续
claude --continue               # 恢复最近会话
claude --continue -p "任务"     # 恢复并执行
claude -c                       # --continue的简写

# 定位
claude --resume                 # 选择历史会话
claude --resume <id>            # 恢复指定会话
claude --sessions               # 列出所有会话

# 分支
> /branch <name>               # 在交互中创建分支
claude --continue --fork-session <name>  # CLI创建分支

# 管理
> /compact                     # 压缩上下文
> /compact <指令>              # 带指导的压缩
> /clear                       # 清空上下文
> /cost                        # 查看费用
> /doctor                      # 健康诊断
> /session-name <name>         # 重命名当前会话
> /status                      # 查看会话状态

# 外部
> /memory add <内容>           # 添加全局记忆