用 Claude Code 开发大功能的分阶段做法

修复“用户退出后旧 refresh token 仍然有效”这个问题，计划的第一步是让 Claude Code 写一个失败测试，证明缺陷存在。测试确实失败了，看上去一切按计划进行。

可仔细看失败信息：客户端根本连不上服务。这个测试证明的是环境有问题，和 token 一点关系都没有。如果就此进入下一步，最后很可能“修好”了环境，却把它当成了认证修复。

大任务交给 Claude Code，最常见的毛病是一口气往前推：研究漫无边际，计划只有“改认证服务、加测试”一句话，实现时按文件一个个改，中间状态没法验证。等到最后出问题，已经说不清是哪一步引起的。

把大任务拆成研究、计划、实现几个阶段，常被叫作 RPI。关键不在名字，而在每个阶段的出口条件：

• 研究只回答会改变方案的问题，证据够做决定就停；
• 计划写清改哪里、保留什么、出错怎么回滚、每阶段跑什么检查；
• 实现按“能单独验证的行为”切片，不按文件切；
• 每一段都等前一段的证据，再往下走。

开头那个失败测试，正好卡在第一个出口：它失败了，可失败的原因不对。下面沿着这个认证修复，把各阶段的做法和完成条件走一遍。

01 阶段可以用，文件按需要写

Research（研究）、Plan（计划）、Implement（实现），常缩写为 RPI。这个顺序可以用，但 Claude Code 没要求必须照做，也没要求固定创建 REQUEST.md、RESEARCH.md、PLAN.md、IMPLEMENT.md。

要不要写文件，可以看后面是否用得上。换会话、团队审查、长期跟踪，就留下正式材料；小任务在当前会话做完，研究和计划留在对话里即可。高风险改造值得认真记录，小修改可按后续使用需要保留记录。

研究和计划提供实现依据，实现、验证和复核再检查最初的验收要求。验收要求从哪来，见Claude Code 说修好了，你该怎么验收。

02 研究：只回答会改变方案的问题

研究只回答会改变方案的决策问题。开始前可以列出：

1. refresh token 当前存在哪里，是否可以按会话撤销？
2. 退出接口只清除浏览器状态，还是已经更新服务端记录？
3. 刷新接口怎样判断 token 有效，是否支持轮换和重放检测？
4. 现有多设备登录策略是否允许退出一个设备但保留其他设备？
5. 哪些测试可以复现缺陷，缺少哪些夹具？

这一阶段可以用 Plan 模式，先读、搜索、做只读调查，暂不改源码。Claude Code 的常用工作流文档对 Plan 模式的描述是：Claude 读取文件、提出计划，在你批准之前不做任何编辑。追调用链、归类测试日志、查官方资料，可以分别交给只读子代理，再由主会话汇总结论和证据位置，同一份文档也建议把研究委派给子代理，保持主上下文干净。

研究结果应提供下一步需要的判断依据：

• 已确认事实及文件位置。
• 仍未确认的假设。
• 可能受影响的模块和数据。
• 可选方案及关键取舍。
• 推荐方向和推荐理由。

已有证据足以支持下一步决定时，就结束这轮研究。继续调查应有能改变方案的新问题。几项相互独立的研究可以并行，怎样分工见多个子代理同时改代码时的分工方法。

03 计划：写到能逐段验证

“改认证服务、加测试”还没说清怎样做。计划至少补齐：

• 改哪些模块，为什么要改。
• 数据、函数约定或 API 行为会怎样变。
• 原来的哪些行为要保留。
• 旧状态怎样迁移，出错怎样回滚。
• 每阶段改完跑什么检查。
• 这次明确不做什么。

假设查清了两点：系统已有可撤销的会话记录，退出只影响当前设备。就可以按下面安排。如果 token 没有服务端记录，先解决怎样撤销，再写实现计划。

阶段 1：先写失败测试，证明 logout 后旧 refresh token 仍可刷新
完成条件：测试在当前实现上稳定失败，且失败原因与缺陷一致

阶段 2：退出时写入当前会话的撤销时间，并在 refresh 路径统一校验
完成条件：新测试通过，正常 refresh 与 token rotation 测试仍通过

阶段 3：处理多设备和并发刷新边界
完成条件：退出单设备不影响其他会话，并发重放得到预期错误

阶段 4：运行认证测试、类型检查和构建
完成条件：所有命令成功，并记录实际输出摘要

每个阶段都要形成可独立验证的行为变化。存在依赖时按顺序推进，后一步必须等待前一步证据。

看到阶段 1 的测试失败，还要问它为什么失败。客户端根本连不上服务，证明的是环境有问题；请求到了目标接口，旧 token 仍被接受，才捕捉到这次缺陷。把实际响应留下来，下一阶段才能比较。阶段 1 的完成条件里写着“失败原因与缺陷一致”，就是为了挡住开头那种情况。

04 实现：按可验证的行为切片

实现按可验证行为切片。第一段若是“退出使当前会话失效”，撤销状态、退出写入、刷新校验和测试就要一起到位。只加字段还无法验证这个行为；同一切片涉及多个文件是正常的。

这一段通过后，再处理其他设备和并发刷新，避免把相互依赖的代码与测试拆成难以判断的中间状态。

Git 提交也应保持逻辑内聚：

• 一个提交表达一个清楚目的。
• 提交完成后项目处于可理解、最好可验证的状态。
• 无关重构不混进缺陷修复。
• 回滚一个提交时，可以完整撤销一项行为；按孤立文件拆分很难做到这一点。

例如 session.ts 的字段、refresh.ts 的校验和 refresh.test.ts 的测试共同实现撤销行为，可以归入同一提交。

每完成一段，先跑离改动最近、最快的检查，再扩大到集成测试、类型检查和构建。这样报错时，更容易知道是刚才哪一步引起的。Claude Code 最佳实践解释了这样做的好处：给 Claude 一个能返回通过或失败的检查，它就能自己闭环，改完运行检查，出错就读输出修好，再跑一遍。

05 把稳定流程存成 Skill

当同一套“研究、计划、实现、验证、审查”在团队中反复出现时，可以创建项目 Skill：

---
name: safe-feature
description: 按研究、计划、实现、验证和独立复核流程完成跨模块功能。
argument-hint: "[功能或缺陷描述]"
disable-model-invocation: true
---

1. 先确认目标、范围、非目标和可观察验收证据。
2. 只读研究相关实现、测试和项目规则，列出已确认事实与未决问题。
3. 给出按可验证行为拆分的计划，等待用户确认后再修改。
4. 按切片实施，每个切片后运行最近的检查。
5. 运行完整验收命令，记录命令、结果和未验证项。
6. 使用只读子代理独立审查改动，复核有效发现后再收尾。

保存到 .claude/skills/safe-feature/SKILL.md 后，可以用 /safe-feature 显式调用。disable-model-invocation: true 防止 Claude 在你没有明确选择时自动启动一套复杂流程。

Skill 保存稳定做法。这次的文件名、错误日志和临时决定留在当前会话；用到模板或验证脚本时再读。

06 长任务里管好上下文

上下文管理要保留当前仍在使用的信息。先用 /context 查占用，再选择：

• 不相关任务之间用 /clear 或新会话。
• 正在推进的长任务需要保留决策时使用 /compact，并带上一句“请保留当前核心结论与测试命令”。
• 大量搜索与日志，适合时交给子代理整理。
• 后台测试和耗时命令通过 /tasks 查看进度。
• 需要跨阶段或跨会话保留的决策，写入项目文档或计划。

压缩前保留仍在使用的排错线索，只清理无关或随时能重新找回的内容。

每一段都形成一个能单独验证的行为变化，后一步等前一步的证据。开头那个“失败了但原因不对”的测试，在阶段 1 的出口就被拦住了，后面的修复才建立在真正捕捉到的缺陷上。