DEV Community: 277479420@qq.com

Claude Code 跨会话上下文恢复：从 8 次纠正到 0 次的工程实践

277479420@qq.com — Sun, 01 Mar 2026 14:38:59 +0000

如果你用 Claude Code 做过超过一周的项目开发，大概率遇到过这个场景：

上午做了一半的功能，下午开新会话继续，结果 Claude 完全不记得之前的工作。你得花 10 分钟解释项目背景、当前进度、技术决策的理由。更糟的是，解释完了它还经常理解偏——你说"继续做登录模块的 token 刷新"，它开始给你重写整个认证系统。

这不是偶发问题。Claude Code 是会话级工具，每次新建会话就是一张白纸。在短期任务中这没什么，但在持续迭代的项目开发中，跨会话的上下文断裂会造成三个累积问题：

恢复成本递增：项目越复杂，每次恢复需要的解释越多
纠正成本递增：Claude 基于不完整上下文做出错误判断的概率随项目复杂度上升
一致性递减：同一个功能跨会话开发时，技术方案、命名风格、架构决策会产生漂移

我做了一个量化测试：同一个中等规模项目（十几个功能模块），3 次模拟会话中断后恢复上下文，用手动维护 CLAUDE.md 的方案需要 8 次人工纠正，才能让 Claude 准确对齐之前的工作进度和技术决策。

现有方案的局限

目前社区常见的方案有两类：

方案 A：手动维护 CLAUDE.md

在 CLAUDE.md 中写项目说明、技术约束、当前进度。问题是：

你得记得更新它——做完一个功能忘了改进度，下次就会脱节
格式不统一——每次手写的粒度不一样，Claude 解析不稳定
只有"是什么"没有"在哪"——知道项目用 React，但不知道 token 刷新做到哪一步了

方案 B：TodoWrite 任务列表

用 Claude 内置的 TodoWrite 跟进度。问题是：

任务完成就消失了——没有历史上下文
不处理变更——你说"这个先不做了"，TodoWrite 没有"暂停并保留工作成果"的概念
没有质量保障——Claude 跳过测试或者自己审批自己的事经常发生

两种方案的共同问题：它们管的是信息，不是流程。 真正需要的是项目状态的自动维护 + 流程规则的强制执行。

解决思路：让 Claude 自己维护项目状态

核心设计思路有三条：

状态自动维护：每次会话结束时 Claude 自动更新项目状态文件，下次会话自动读取恢复。人不需要手动维护任何东西
结构化 Markdown：所有状态文件是纯 Markdown，有明确的 Schema 约束。LLM 和人类都能读写，不依赖任何外部服务
规则驱动行为：通过 Claude Code Plugin 的 Rules 机制注入行为规则，让 Claude 在特定场景下自动执行流程（创建变更请求、质量检查、等待人工审批等）

基于这个思路，做了 devpace——一个 Claude Code Plugin，v1.6.0，MIT 开源。

核心机制

双模式设计

devpace 有两种工作模式：

Explore 模式（默认）：自由读代码、分析、讨论。不触发任何流程，不修改状态文件。问问题、看代码时零摩擦。
Advance 模式（改代码时）：通过 /pace-dev 触发。创建变更请求（CR），进入状态机（created → developing → verifying → in_review → approved → merged），自动运行质量检查。

你不需要主动想模式的事。问问题就是 Explore，开始实现功能就是 Advance。

.devpace/ 目录结构

运行 /pace-init 后生成最小状态目录：

.devpace/
├── state.md          # 项目状态快照（限制 15 行）
├── project.md        # 价值功能树：目标→功能→任务
├── backlog/          # 初始为空，开始开发后自动创建 CR 文件
│   └── CR-001.md     # （第一个任务时自动出现）
└── rules/
    ├── workflow.md   # CR 状态机规则
    └── checks.md     # 质量检查（从工具链自动检测）

关键：state.md 限制在 15 行。过长的状态文件增加 token 消耗且降低恢复准确率。15 行包含：业务目标摘要、当前进行中的工作、下一步建议。

11 个 Hook 管理完整的会话生命周期：

session-start.sh：读取 state.md，注入上下文。Claude 一句话报告现状。
session-end.sh：更新 state.md，记录工作进展和下一步。
pre-compact.sh：上下文窗口压缩前保存状态，防止长对话丢失信息。
intent-detect.mjs：检测代码变更意图，建议进入 Advance 模式。

渐进式披露：初始化只有最小文件集。迭代文件在 /pace-plan 时出现，度量文件在 /pace-retro 时出现，发布文件在 /pace-release 时出现。你不会看到不需要的复杂度。

state.md 示例

> 目标：用户权限系统 → 成效指标：支持 RBAC + OAuth 登录
> 迭代：ITER-002（核心权限模块）| 进度：3/5 产品功能已完成

- **进行中**：Token 刷新机制 → 步骤 3/5：middleware 实现
- **待 Review**：角色权限矩阵
- **决策**：选择 JWT 而非 Session | Redis 缓存 Token 黑名单
- **下一步**：完成 middleware 后运行集成测试，然后提交 Review

会话开始时 Claude 读到这个，输出："上次停在 Token 刷新的 middleware 实现，角色权限矩阵在等 Review。继续？"——不输出 ID、状态机术语，只说人话。

三级质量门

级别	触发时机	执行者	可跳过？
Gate 1	开发完成 → 进入验证	Claude 自动	否
Gate 2	验证通过 → 提交审查	Claude 自动	否
Gate 3	审查 → 批准合并	人工审批	不可跳过

Gate 3 是硬约束——写死在规则里，无论 Claude 认为变更多简单，都必须等人确认。

三个专业子代理

pace-engineer：处理实现（/pace-dev、/pace-test）。技术视角，关注代码和测试。
pace-pm：处理规划和变更（/pace-change、/pace-plan）。业务视角，关注价值和优先级。
pace-analyst：处理回顾（/pace-retro）。数据视角，关注度量和趋势。

数据对比

跨会话恢复测试

指标	devpace	手动 CLAUDE.md
3 次中断后纠正次数	0 次	8 次
恢复方式	自动读取 state.md	手动解释

7 维度能力对比

维度	devpace	手动方案	TodoWrite
跨会话恢复	自动	手动	无持久化
变更管理	5 种场景 + 影响分析	无	无
质量保障	3 级质量门，人审不可跳过	无	无
价值追溯	OBJ→BR→PF→CR 全链路	无	任务→完成
度量能力	DORA 代理指标	无	无
风险管理	预飞行扫描 + 分级响应	无	无
角色适配	5 种角色视角	无	无

总分：devpace 21/21 vs 手动方案 7/21 vs TodoWrite 4/21

变更管理：核心差异化

开发中途需求变了是常态，但现有工具都没有真正处理这个问题。

devpace 的 /pace-change 支持 5 种变更场景：

场景	触发方式	Claude 的处理
需求插入	"加一个 XX 功能"	影响分析 → 容量评估 → 创建 CR
需求暂停	"这个先不做了"	保留工作成果 → CR 暂停 → 解除依赖
需求恢复	"之前暂停的继续做"	从暂停点恢复 → 检查上下文是否过期
优先级重排	"XX 先做"	重排计划 → 更新 state.md
需求修改	"XX 的要求变了"	识别返工 → 质量检查重置 → 更新验收标准

还支持 undo（撤销上次变更）和 batch（批量变更）。

安装与试用

Marketplace 安装（推荐）：

/plugin marketplace add arch-team/devpace
/plugin install devpace@devpace

从源码安装：

git clone https://github.com/arch-team/devpace.git
claude --plugin-dir ./devpace

然后：

/pace-init

Claude 问你一个问题："用一句话描述项目做什么"。然后自动检测工具链，创建 .devpace/。开始工作，关会话，开新会话。看 Claude 是否还记得。

局限与诚实评价

价值感知延迟：第一个会话感受不明显，需要 2-3 次跨会话恢复才能体会
概念门槛：BizDevOps 的价值链对不熟悉的开发者有理解成本（但日常只用 3-4 个命令）
适用范围：不适合一次性脚本。目标是多会话持续迭代的项目
平台限制：目前只支持 Claude Code

GitHub：github.com/arch-team/devpace
许可：MIT | 版本：v1.6.0 | 18 Skills | 34 场景验证

一个受够了每天早上对 Claude 说三遍"不对，我们已经决定过了"的开发者做的。

Claude Code Keeps Forgetting Your Project? Here's a Fix

277479420@qq.com — Sun, 01 Mar 2026 06:37:20 +0000

You close your Claude Code session at 6 PM. You open it back up the next morning. And the first thing you type is a three-paragraph explanation of what you were doing yesterday.

Sound familiar?

The Problem Nobody Talks About

Claude Code is one of the most capable AI coding assistants available. It can write whole modules, refactor complex systems, and reason through architecture decisions. But it has a blind spot that costs developers real time every single day: it forgets everything between sessions.

This isn't a bug. It's how the tool works. Claude Code operates in isolated sessions. There is no persistent project memory. No state carried over. When you start a new session, Claude sees your codebase, your CLAUDE.md if you have one, and nothing else. It doesn't know what you were working on, what state your feature is in, which tests were passing, what your acceptance criteria are, or what you decided in the last three sessions.

For a one-off script, this is fine. For sustained product development across days or weeks, it's a serious friction point. You end up repeating yourself. You correct Claude when it makes wrong assumptions. You re-explain decisions you already made. And every interruption — lunch break, meeting, end of day — resets the clock.

What Manual Solutions Look Like (and Where They Break)

The most common workaround is a well-crafted CLAUDE.md file. You write down your project structure, conventions, current goals, maybe a list of TODOs. Some developers keep a separate notes file that they paste into the conversation at the start of each session. Others manually update a "project status" section after each work block.

These approaches help — up to a point. They cover the static parts: "this is a TypeScript project, we use Vitest, here are the coding conventions." But they fail at the dynamic parts:

What's in progress right now? A CLAUDE.md doesn't update itself. By your third session, the "current work" section is stale.
What are the acceptance criteria for this feature? You wrote them down somewhere, but did you paste them into the context? Probably not.
What's the quality gate status? Did the last session's tests pass? Were there lint issues? What about the intent check — does the code match what you originally planned? Manual notes don't capture this.
What changed since last time? If you or someone else pushed commits between sessions, your manual context is now out of sync with reality.

The fundamental issue is maintenance. Keeping manual context accurate requires effort proportional to your project's complexity. And the whole point of using an AI coding assistant is to reduce effort, not create new bookkeeping tasks.

What Happens When Context Is Actually Maintained

I built devpace, a Claude Code plugin, partly to solve this problem. The core idea is simple: maintain project state as plain Markdown files in a .devpace/ directory, and have Claude read them automatically at every session start.

But instead of just claiming it works, let me show you numbers from an actual comparison test.

The Test Setup

I took the same project and ran it through three deliberate interruption points — simulating a developer closing their laptop, taking a call, switching projects, and coming back. I ran this twice: once with devpace managing the state, once with a manually maintained CLAUDE.md.

At each interruption recovery, I counted how many times I had to correct Claude's understanding of the project state. A "correction" means Claude either assumed something wrong, forgot something important, or started working in the wrong direction.

The Results

devpace: 0 user corrections across 3 interruption points.

Manual approach: 8 user corrections across 3 interruption points.

Eight times I had to stop Claude and say "no, that's not where we were" or "we already decided against that approach" or "the acceptance criteria require X, not Y."

But the raw correction count only tells part of the story. I also ran a 7-dimension analysis comparing what each approach actually preserved across sessions:

Dimension	devpace (auto)	Manual CLAUDE.md
D1: Current work status	Pass	Pass
D2: Feature context (what and why)	Pass	Pass
D3: Acceptance criteria state	Pass	Fail
D4: Quality gate status	Pass	Fail
D5: Decision history	Pass	Partial
D6: Dependency/blocker state	Pass	Partial
D7: Next step recommendation	Pass	Fail

devpace scored 21/21. Manual scored 7/21.

The critical gap is D3 and D4. Acceptance criteria and quality gate state are completely uncovered by manual approaches. No developer is going to manually write "Gate 1 passed, Gate 2 pending, lint passed on 14 files, type check failed on auth.ts line 42" in their CLAUDE.md after every session. It's too granular, too tedious, and too easy to forget. But that's exactly the information Claude needs to resume work without false starts.

How devpace Does It

devpace is a Claude Code plugin with 18 skills, 11 automated hooks, and 3 specialized sub-agents. But for cross-session continuity, only a few pieces matter:

Two Work Modes

devpace operates in two modes:

Explore mode (default): Claude freely reads, analyzes, and discusses your code. No process triggered, no state files modified. This is important — devpace doesn't get in your way when you're just asking questions or exploring ideas.
Advance mode (when changing code): Triggered by /pace-dev. Claude creates a Change Request (CR), tracks progress through a state machine (created → developing → verifying → in_review → approved → merged), and runs quality checks automatically.

You don't have to think about modes. Ask a question, you're in Explore. Start implementing, you're in Advance. The overhead is zero until you actually need the structure.

The State Files

When you run /pace-init, devpace creates a minimal .devpace/ directory:

.devpace/
├── state.md          ← Session anchor (capped at 15 lines)
├── project.md        ← Value-feature tree: goals → features → tasks
├── backlog/          ← Empty at init, CRs auto-created as you work
│   └── CR-001.md     ← (appears when you start your first task)
└── rules/
    ├── workflow.md   ← CR state machine
    └── checks.md     ← Quality checks (auto-detected from your toolchain)

state.md is the key file for cross-session continuity. It's capped at 15 lines — not a brain dump but a structured checkpoint containing your current goal, active work, and next step. Eleven hooks manage the session lifecycle:

session-start.sh: Reads state.md, injects context. Claude reports one sentence on the current situation.
session-end.sh: Updates state.md with what's in progress and what comes next.
pre-compact.sh: Saves state before context window compaction, so nothing is lost when the conversation gets long.
intent-detect.mjs: Detects when you're about to change code and suggests entering Advance mode.

Everything is Markdown. You can read it, edit it, commit it to git, diff it. No proprietary formats, no external services, no database.

Three Quality Gates

When you're in Advance mode, every CR passes through three gates:

Gate 1 (developing → verifying): Code quality checks and requirement completeness. Claude handles this autonomously.
Gate 2 (verifying → in_review): Integration checks and intent consistency — does the code match what you originally asked for? Also autonomous.
Gate 3 (in_review → approved): Human approval required. This is an iron rule in devpace — Claude cannot bypass it. You review the work, approve or reject, and only then does the CR merge.

This matters for cross-session continuity because gate status is tracked in each CR file. When you resume a session, Claude knows exactly which gates passed, which are pending, and what needs your attention.

Three Sub-Agents

devpace routes work to specialized sub-agents, each with a distinct perspective:

pace-engineer: Handles implementation (/pace-dev, /pace-test). Thinks in code, tests, and technical constraints.
pace-pm: Handles planning and changes (/pace-change, /pace-plan). Thinks in business value, priorities, and scope.
pace-analyst: Handles retrospectives (/pace-retro). Thinks in metrics, trends, and process improvements.

When you say "add SSO support," pace-pm assesses the impact on existing work before pace-engineer starts coding. This prevents the chaos of requirements changing mid-build — which is a separate article's worth of content.

The 30-Second Experience

# First time (once per project)
/pace-init my-app

# Claude asks one question: "Describe what this project does in one sentence."
# Then auto-detects your toolchain, creates .devpace/, injects into CLAUDE.md.
# Done. Start working:

"Help me implement user authentication"
# Claude enters Advance mode, creates CR-001, writes code, runs quality checks

# --- session break ---

# Next session, Claude reports:
# "Last session stopped at auth module, JWT refresh token pending. Continue?"

"continue"
# Picks up exactly where it left off. No re-explanation.

For existing projects with a PRD or requirements doc:

/pace-init --from prd.md
# Parses your doc → generates a goal-feature-task tree → you confirm → start working

The key design principle is progressive disclosure. At init, you get a minimal .devpace/ with just state.md, project.md, and an empty backlog/. Features appear only when you need them: iteration files appear when you run /pace-plan, metrics when you run /pace-retro, release tracking when you run /pace-release. You never see complexity you haven't asked for.

What This Isn't

devpace is not a CI/CD platform. It's not a replacement for GitHub Issues or Jira. It doesn't have a web dashboard or team collaboration features. It's a plugin that runs inside Claude Code and maintains the project state that Claude needs to work autonomously across sessions.

It does more than just cross-session continuity — there's change management (/pace-change with 9 sub-commands including undo and batch), iteration planning, DORA metric proxies, risk scanning, and a full traceability chain from business goals to code. But the cross-session problem is the entry point. It's the pain you feel every morning.

Honest caveats: it's opinionated about workflow (a BizDevOps-inspired value chain from business goals to code), and the full 18-skill surface has a learning curve. But day-to-day you really only use 3–4 commands: /pace-init, /pace-dev, /pace-status, and /pace-next. The rest is there when you need it.

Try It

Marketplace install (recommended):

/plugin marketplace add arch-team/devpace
/plugin install devpace@devpace

From source:

git clone https://github.com/arch-team/devpace.git
claude --plugin-dir ./devpace

Then:

/pace-init

You'll see a .devpace/ directory appear with your project's state files. Work for a while, close the session, open a new one. See if Claude remembers.

The repo is MIT licensed and open source: github.com/arch-team/devpace

For the full feature set: User Guide | End-to-end walkthrough

Built by a developer tired of saying "no, we already decided that" to Claude for the third time in one morning.