WORKFLOW.md

Claude Code 项目工作流手册 (Project Workflow Guide)

定位: 本手册是 README.md（技能参考手册）的配套实操指南。 README 回答"有什么工具"，本手册回答"怎么用这些工具跑完一个项目"。

---

目录

1. 项目生命周期总览
2. Plan Mode 与 /plan 命令
3. Phase 0：立项与规划
4. 模块开发流程总览
5. 模块开发详解（Plan Mode 工作流）
6. Phase 3：集成与收尾
7. 会话管理：开始与结束仪式
8. 跨会话持续性策略
9. 质量关卡速查
10. 故障排除与常见陷阱
11. 附录：项目模板

---

1. 项目生命周期总览

flowchart TD
    %% Phase 0
    subgraph P0["Phase 0: 立项与规划 (/project-plan)"]
        Brainstorm["头脑风暴<br>Brainstorming"] --> InitClaude["初始化项目文件<br>CLAUDE.md + PROGRESS.md"]
        InitClaude --> Research["技术调研 (可选)<br>Context7 / Crawl4AI"]
        Research --> Arch["架构设计<br>docs/architecture.md"]
        Arch --> PlanReview0["/plan-review project<br>(推荐) 审查架构完整性"]
    end

    %% Phase 1+2: 模块开发循环
    subgraph DevLoop["Phase 1-2: 模块开发"]
        PlanMode["/module-plan<br>讨论并持久化方案"] --> PlanReviewM["/plan-review<br>(可选) 审查方案可行性"]
        PlanReviewM --> Execute["/module-dev<br>按方案逐步实现 + 验收"]
        Execute --> CR1["/code-review<br>(可选) 代码审查"]
        CR1 --> Commit["/commit"]
        Commit --> Update["/module-done"]
        Update -->|"还有模块"| PlanMode
    end

    %% Phase 3
    subgraph P3["Phase 3: 集成与收尾"]
        PlanReviewFinal["/plan-review project<br>(推荐) 最终方案审查"] --> TechVerify["/verify 技术检查"]
        TechVerify --> E2E["/e2e 端到端测试"]
        E2E --> PRReview["/review-pr 深度审查"]
        PRReview --> Security["安全审查"]
        Security --> Ship["/commit-push-pr"]
    end

    %% 连接各阶段
    PlanReview0 --> PlanMode
    Update -->|"所有模块完成"| PlanReviewFinal

Loading

阶段	目标	核心指令	产出物
Phase 0	明确做什么、怎么做	/project-plan → /plan-review project（推荐）	CLAUDE.md + PROGRESS.md + docs/architecture.md
Phase 1-2	逐模块设计与实现	/module-plan → /plan-review（可选）→ /module-dev → /code-review（可选）→ /commit → /module-done	可运行的代码 + 测试
Phase 3	全局验证与上线	/plan-review project（推荐）→ /verify → /e2e → /review-pr → /commit-push-pr	PR、部署产物

---

2. Plan Mode 与 /plan 命令

在深入工作流之前，必须理解两个容易混淆的规划工具。它们是不同层面的东西，可以搭配使用。

Plan Mode（内置模式切换）

Claude Code 内置的权限模式，通过 Shift+Tab 在输入框中循环切换：

Shift+Tab 循环：Normal → Plan → Auto-accept → Normal → ...

模式	Claude 的行为
Normal	默认模式，每次编辑都请求你批准
Plan	只思考和讨论，不修改任何文件。你可以反复对话直到方案满意
Auto-accept	自动执行所有编辑，不再逐个请求批准

也可以通过 CLI 启动时指定：claude --permission-mode plan

Claude Code 创始人 Boris Cherny 的做法：几乎所有非平凡任务都先进入 Plan 模式，反复讨论直到满意，再切到 Auto-accept 让 Claude 一次完成。 "A good plan is really important!"

/plan 命令（ECC 插件）

/plan 是 everything-claude-code 插件提供的斜杠命令，调用 Planner Agent 输出一份结构化的实施步骤文档。

区别与选择

维度	Plan Mode (Shift+Tab)	/plan 命令
来源	Claude Code 内置	everything-claude-code 插件
本质	模式开关，控制 Claude 是否能编辑文件	Agent 调用，输出实施计划文档
交互	多轮自由对话，可质疑、对比、要求探查代码	单轮输出结构化方案
工具	主 agent 全部工具可用	planner agent 仅有 Read/Grep/Glob
深度	取决于讨论轮数，上不封顶	一次推理，按模板填充

如何选择

一句话：能一句话说清的用 /plan，说不清的用 Plan Mode。

场景	选择	原因
需求明确，实现路径清晰（如"加一个 CRUD"）	/plan	不需要讨论，快速出步骤直接执行
需求明确但有技术选型要权衡	Plan Mode	需要对比方案、讨论 trade-off
需求模糊，做之前要先探查代码	Plan Mode	需要 Claude 用全部工具探索代码库
改动涉及多个模块，影响面大	Plan Mode	需要多轮讨论确认边界和风险
项目初期，不熟悉代码结构	Plan Mode	需要 Claude 先帮你理解现有架构

推荐流程：

1. Shift+Tab → 进入 Plan 模式
2. 多轮对话讨论方案，反复打磨直到满意
3. /module-plan               ← 将方案持久化到 docs/plan.md，更新 PROGRESS.md
   (或手动让 Claude 写入 docs/plan.md + 更新 PROGRESS.md)
4. (可选) 用其他模型审查 docs/plan.md ← 复杂功能建议做
5. /compact                    ← 方案已持久化，压缩上下文为执行腾出空间
6. Shift+Tab → 切到 Auto-accept 模式
7. Claude 按方案执行

可选：用独立模型审查方案 复杂功能建议在执行前，将 docs/plan.md 中的方案交给另一个 AI（Gemini、Codex 等）以 Staff Engineer 角色审查。 同一个模型讨论出的方案容易有确认偏误，独立模型能从不同角度发现盲点。 简单功能无需此步骤。

为什么不用 /plan 整理讨论结论？ /plan 会启动独立的 planner 子 agent 重新生成方案，而不是整理你们的讨论结论，内容可能与讨论结果有出入。 直接让主 agent 整理更准确：

把我们刚才讨论确定的当前模块方案整理成结构化文档，包含：
需求确认、架构变更、实施步骤、测试策略、风险评估
写入 docs/plan.md，然后更新 PROGRESS.md 的模块状态

---

3. Phase 0：立项与规划

目标: 从模糊的想法收敛到可执行的需求清单和全局架构设计。

推荐: 使用 /project-plan 命令，它会引导你完成整个 Phase 0 流程（需求梳理 → 技术调研 → 澄清问题 → 架构设计 → 持久化到项目文件）。以下是各步骤的详细说明，也可手动逐步执行。

步骤 1：头脑风暴

帮我头脑风暴一下 XXX 项目的方案

Brainstorming 技能会引导你思考：

• 核心用户是谁？解决什么问题？
• MVP 包含哪些功能？哪些是 v2？
• 有没有类似项目可以参考？

产出: 一份需求要点列表。

步骤 2：初始化项目文件

头脑风暴结束后，立即让 Claude 创建项目的 CLAUDE.md：

根据刚才的头脑风暴结果，帮我创建：
1. CLAUDE.md — 项目简介、功能范围、技术选型（初版）、模块清单、编码约定（< 300 行，参考第 11 节模板）
2. PROGRESS.md — 模块进度表、下次继续的入口

为什么这一步不能跳过？ CLAUDE.md 是 Claude Code 的"长期记忆"。每次新会话自动加载。 没有它，下次开会话你得从头解释一遍背景。

为什么分两个文件？ CLAUDE.md 放不常变的静态配置（技术选型、编码约定），PROGRESS.md 放频繁变化的动态进度（模块状态、当前入口）。这样 CLAUDE.md 保持稳定精简，进度更新不会污染它。详见 8.1 节。

步骤 3：技术调研（可选）

如果技术选型不确定，可以利用工具辅助决策：

• Context7 (MCP): 查阅框架最新文档，对比方案
• Crawl4AI / Agent Browser: 抓取竞品或参考项目的实现
• Audit Website: 如果是改造已有站点，先做全面体检

用 Context7 查一下 Next.js 15 和 Nuxt 4 在 SSR 性能上的差异

步骤 4：架构设计

Shift+Tab 进入 Plan Mode（参见第 2 节），讨论项目的全局架构：

Shift+Tab → 进入 Plan 模式

我们来设计这个项目的整体架构。需要讨论：
1. 前后端怎么分？模块间怎么通信？
2. 核心数据模型有哪些实体？关系是什么？
3. 每个模块的职责边界和对外接口怎么定？
4. 技术选型有哪些 trade-off 需要权衡？
先从系统大图开始，再逐个细化。

讨论中可借助以下技能：

技能	用途	调用方式
Backend Architect	服务拆分、API 全局设计	描述需求时自动触发
Architect agent	系统设计、技术选型	涉及架构决策时自动触发
Mermaid Diagrams	生成架构图、ER 图、时序图	"用 mermaid-diagrams 画出系统架构图"
Architect Review	评审 SOLID/DDD 合规性	"用 architect-review 审查方案"（复杂项目推荐）

讨论确认后，将方案文档化：

把我们确认的架构方案写入 docs/architecture.md，包含：
1. 系统架构图（Mermaid）
2. 数据模型（ER 图或表结构）
3. 模块边界（职责、接口、依赖）
4. 关键设计决策（trade-off 分析）

docs/architecture.md 是项目的全局设计详情文档，整个项目生命周期内持续维护。 与 CLAUDE.md 中的"架构概览"（一段话摘要）互补：CLAUDE.md 给方向，docs/architecture.md 给细节。

全局设计 vs 模块方案

Step 4 产出的 docs/architecture.md 是全局设计——解决"系统怎么搭"。进入模块开发后，每个模块还有自己的实施方案（docs/plan.md）——解决"这个模块怎么写"。两者都用 Plan Mode 讨论，但范围和辅助技能不同：

	全局设计（Phase 0）	模块方案（Phase 1-2 每模块）
解决的问题	系统怎么搭	这个模块怎么写
讨论范围	系统架构、数据模型、模块边界、技术选型	表结构、API 路由、实现步骤、测试策略
辅助技能	Backend Architect、Mermaid Diagrams、Architect Review	技术栈对应技能（自动触发）、/module-dev
产出文件	docs/architecture.md（持久）	docs/plan.md（临时，每模块覆盖）

模块方案讨论中，技术栈相关的技能会根据讨论内容自动触发（如 FastAPI Expert、Vercel React/Next.js、Supabase Best Practices 等）。完整的技能选用指南见 README.md 第 5 节。

Phase 0 完成检查清单

• CLAUDE.md 已创建（项目简介、技术选型、模块清单、编码约定，< 300 行）
• PROGRESS.md 已创建（模块进度表、下次继续的入口）
• docs/architecture.md 已创建（架构图、数据模型、模块边界、设计决策）
• (推荐) /plan-review project 审查架构完整性（需求覆盖、依赖完整性）
• /commit 提交当前状态

---

4. 模块开发流程总览

目标: 每个模块按统一流程完成：规划 → 执行 → 验证 → 审查 → 提交 → 更新进度。

flowchart TD
    Start["/module-plan<br>讨论并持久化方案"] --> Review["/plan-review<br>(可选) 审查方案可行性"]
    Review --> Dev["/module-dev<br>按方案逐步实现 + 验收"]
    Dev --> CR2["/code-review<br>(可选) 代码审查"]
    CR2 --> Commit["/commit"]
    Commit --> Done["/module-done"]
    Done -->|"还有模块"| Start
    Done -->|"全部完成"| P3["Phase 3: 集成与收尾"]

Loading

启动模块规划

推荐使用 /module-plan：它会引导你完成从加载项目上下文、探索现有代码、讨论设计方案到持久化的完整流程。对于涉及大量现有代码的复杂模块，/module-plan 会自动启动 2-3 个 codebase-explorer agent 并行扫描代码库，发现可复用的模式和架构层次。

/module-plan 产出的实现步骤采用可验证格式：每步包含精确文件路径、接口签名（含类型）、关键断言（输入 → 预期结果）和验证命令。这为 /module-dev 的 Spec Check 和 Phase 4 验收提供了精确的比对锚点。

也可以用 Plan Mode 手动讨论方案（参见第 2 节），确认后手动将当前模块的详细实施方案写入 docs/plan.md，更新 PROGRESS.md。手动编写时也建议遵循可验证格式（精确文件路径 + 接口签名 + 关键断言 + 验证命令），确保 /module-dev 能有效执行 Spec Check。然后按第 5 节的流程执行开发。

docs/plan.md 是当前模块的临时实施方案，每开发一个新模块时覆盖更新。它的作用是跨越 /compact 的上下文桥梁——压缩后 Claude 可以重新读取该文件恢复方案细节。

---

5. 模块开发详解（Plan Mode 工作流）

目标: 按模块逐个实现，每个模块走完整的开发-测试-审查流程。本节详解第 4 节流程中各步骤的具体操作。

5.1 核心原则

1. 每次只做一个功能 — 不要试图在一次会话中完成所有模块。一次做太多会导致上下文耗尽，留下半成品（Anthropic 官方称此为 "one-shotting" 失败模式）。
2. 先基础后业务: 数据库 → 认证 → 核心业务 → 辅助功能
3. 先后端后前端: API → 页面 → 交互优化。全栈项目中，同一功能拆为 功能/后端 + 功能/前端 两个独立模块，后端先行并产出 API 契约，前端依赖后端模块完成后再开始。
4. 先主路径后边界: Happy path → 错误处理 → 边界场景

5.2 单模块开发流程

每个模块按以下顺序执行：

flowchart TD
    A["/module-plan<br>讨论并持久化方案"] -->|"方案确认"| PR["/plan-review<br>(可选) 审查方案可行性"]
    PR --> Dev["/module-dev<br>逐步实现 + 关键行为测试"]
    Dev --> Verify["Phase 4 验收<br>build + 测试 + 对照 plan"]
    Verify --> Fix{"有问题?"}
    Fix -->|"是"| FixIt["修复"] --> Verify
    Fix -->|"否"| CR["/code-review<br>(可选) 代码审查"]
    CR --> Commit["/commit"]
    Commit --> Update["/module-done<br>含 Code Review Gate"]
    Update -->|"下一个模块"| A

Loading

第一步：Plan 模式讨论方案

推荐使用 /module-plan，它会引导你完成从加载上下文到讨论方案再到持久化的完整流程。也可以手动操作：Shift+Tab 进入 Plan 模式（参见第 2 节），用自然语言和 Claude 讨论模块的实现方案：

Shift+Tab → 进入 Plan 模式

实现订单模块的 CRUD API，包括创建订单、查询列表（分页）、查看详情、取消订单。
数据库用什么表结构？API 路由怎么设计？分页用 cursor-based 还是 offset？

Plan 模式的核心是多轮对话——你可以质疑方案、提出约束、要求 Claude 探查现有代码、对比不同方案，直到满意为止。这是规划环节最重要的部分。

讨论中，技术栈相关的技能（如 FastAPI Expert、Vercel React/Next.js、Supabase Best Practices）和 Architect agent 会根据讨论内容自动触发，无需手动调用。全局 vs 模块的范围区分见第 3 节「全局设计 vs 模块方案」。

/plan 可以作为可选的起点——如果你不确定从哪里开始讨论，先用 /plan "模块描述" 让 Claude 输出一份结构化方案，然后在 Plan 模式下针对这份方案逐项讨论修改。

注意: Plan 模式下的讨论和 /plan 的输出都只存在于当前会话中，不会自动保存到项目文件。 方案确认后，用 /module-plan 持久化到项目文件（它会写入 docs/plan.md 并更新 PROGRESS.md）。 复杂模块建议在持久化后运行 /plan-review 审查方案可行性，再进入 /module-dev。 也可以手动完成：

把刚才确认的实施方案写入 docs/plan.md（详细版），
然后更新 PROGRESS.md：标记当前模块为"方案已确认"，记录下次入口

第二步：执行开发

推荐使用 /module-dev：它会自动加载 CLAUDE.md、docs/plan.md、docs/architecture.md 全量上下文，从 plan 中提取实现步骤，逐步完成代码和测试。

/module-dev

/module-dev 的测试策略是按 plan 定向测试，而非一刀切：

步骤类型	处理方式
涉及业务逻辑、边界条件、错误处理的步骤	先写测试再实现（plan 中标注的关键行为）
配置、迁移、简单 wiring 等步骤	直接实现，不写测试

每个步骤完成后，/module-dev 会对照 docs/plan.md 做一次规格自检（Spec Check）：该步骤要求的功能是否全部实现？是否有计划之外的添加？接口签名是否与 plan 一致？发现偏差时立即停下告知用户，修正后才继续下一步。这样在步骤级别就能拦截过度建设和规格偏移，而非等到模块末尾才发现。

所有步骤完成后，/module-dev 会自动进入 Phase 4 验收（build 检查 + 测试 + 对照 plan 逐项核对 + 编码规范检查）。如果验收发现问题，可再次运行 /module-dev 进入 Refinement Mode 修补。

第三步：验证

"给 Claude 一种验证自己工作的方式，质量会提升 2-3 倍。" — Boris Cherny

每个功能都应验证，不要等到最后。 验证方式取决于项目类型：

• API 项目: 运行测试套件，用 curl 或 Postman 手动测一遍
• Web 项目: 启动 dev server，用 Agent Browser 或手动浏览器验证 UI
• CLI 工具: 运行实际命令，检查输出

运行 dev server 并验证刚才实现的订单创建功能是否正常工作

关于 /verify: 构建、类型、lint 等技术检查已由 PostToolUse hooks 在每次编辑后实时执行，模块级无需额外跑 /verify。/verify 作为全量技术兜底放在 Phase 3 集成收尾阶段（见 6.1 节）。

第四步：代码审查

/code-review

修复审查发现的问题后继续。

何时可以跳过？ 对于简单模块（CRUD、配置、样式），PostToolUse hooks 已覆盖格式化、类型检查和 console.log 检测。可以跳过模块级 /code-review，留到 Phase 3 的 /review-pr 做批量深度审查。核心业务模块（支付、权限、数据处理）建议保留。

第五步：提交并更新进度

/commit
/module-done

/module-done 会先检查是否有未提交的变更——如果有，会提醒你先运行 code review 再提交（Code Review Gate，可跳过）。然后标记模块为"已完成"、更新 PROGRESS.md 的下次入口、并在需要时创建模块级 CLAUDE.md。也可以手动更新：

帮我更新 PROGRESS.md，标记订单模块 CRUD API 已完成，更新"下次继续的入口"

5.3 模块间的衔接

模块完成后，先评估上下文状态再决定如何继续：

上下文使用量	下一步	操作
< 50%	继续当前会话	直接开始下一个模块
50-70%	/compact 后继续	压缩上下文，保留关键信息再继续
> 70%，或下个模块复杂	开新会话	/commit → /module-done → 开新会话

如何查看上下文用量？ 观察 Claude Code 状态栏的 token 计数。

继续当前会话时：

/module-done                  ← 标记当前模块完成，更新 PROGRESS.md
/module-plan 支付模块          ← 开始下一个模块的方案讨论

或手动衔接：

我已完成订单模块，现在开始开发支付模块。
请先阅读 CLAUDE.md 了解整体架构，然后我们讨论支付模块的实现方案。

开新会话时：

# 确保当前会话已 /commit 并运行了 /module-done
claude                        # 开新会话
请阅读 CLAUDE.md 和 PROGRESS.md，从支付模块开始

5.4 上下文管理

上下文窗口是 Claude Code 最核心的约束。社区反馈中，上下文管理不当是排名第一的失败原因。

核心工具

命令	作用	何时使用
/compact	压缩对话历史，保留关键信息	上下文 50-70% 时主动使用
/clear	完全清除对话历史（不可逆）	切换到完全无关的任务时
!command	直接执行 bash 命令，不经模型处理，零 token 消耗	运行你已知的命令（!git status、!npm test）

上下文退化的信号

当出现以下症状时，说明上下文已开始退化：

• Claude 开始犯之前没犯过的低级错误
• Claude 忘记了会话早期讨论过的约定
• Claude 尝试随机方案而不是推理解决问题
• 你发现自己在重复之前说过的话

一旦出现这些信号，不要继续推。执行 /compact，或者 /commit 后开新会话。

推荐策略：Plan 讨论后压缩

Plan Mode 讨论可能消耗 20-30% 上下文。讨论完毕后：

1. /module-plan            ← 持久化方案到 docs/plan.md + 更新 PROGRESS.md
2. /compact               ← 方案已持久化，可以安全压缩
3. Shift+Tab → Auto-accept 模式开始执行

这样执行阶段能获得最大的可用上下文。

Subagent 原则

把探索性工作交给 subagent，保持主上下文干净：

用 subagent 调查 src/payments/ 的支付流程实现，总结关键发现

Subagent 在独立上下文中工作，只向主 agent 返回摘要。这避免了大量文件内容填满主上下文。

---

6. Phase 3：集成与收尾

目标: 所有模块完成后的全局验证、优化和上线准备。

6.0 方案终审（推荐）

/plan-review project

在进入代码级质量关卡前，先做一次项目级方案审查：检查需求覆盖、架构偏移、跨模块接口一致性。此时所有模块已实现，五个审查维度均可执行，能发现积累的规划偏差。

6.1 技术验证

/verify

对整个项目做一次全量技术检查：构建（Build）→ 类型（Types）→ 代码规范（Lint）→ 测试套件（Tests）→ Console.log 审计 → Git 状态。模块开发阶段 PostToolUse hooks 已做实时检查，这里是上线前的最终兜底。

6.2 端到端测试

/e2e

覆盖关键用户流程：注册 → 登录 → 核心操作 → 支付 → 退出。

6.3 深度 PR 审查

/review-pr

这比 /code-review 更重，6 个维度的专家审查，适合合并到主分支前。

6.4 安全审查

Security Reviewer 会在涉及认证、用户输入时自动触发。 但在上线前建议手动做一次全面检查：

对整个项目做一次安全审查，重点检查认证流程、API 权限、输入校验

6.5 性能与审计（针对 Web 项目）

用 audit-website 对站点做全面体检

6.6 提交并创建 PR

/commit-push-pr

---

7. 会话管理：开始与结束仪式

Claude Code 的每次会话是独立的。通过固定的"仪式"保证跨会话的连续性。

flowchart TD
    Start["开始工作"] --> Q{"有之前的会话?"}
    Q -->|"是"| Resume["claude -c 或 --resume<br>恢复会话上下文"]
    Q -->|"否"| New["新会话<br>请阅读 CLAUDE.md + PROGRESS.md"]
    Resume --> Dev["正常开发循环<br>Plan → 执行 → 验证 → /code-review → /commit"]
    New --> Dev
    Dev --> End["准备结束会话"]
    End --> C1["/commit<br>确保代码已提交"]
    C1 --> C2["/module-done<br>更新 PROGRESS.md<br>(含 Code Review Gate)"]
    C2 --> C3["(可选) /update-docs<br>(可选) /learn"]

Loading

恢复已有会话

在开新会话之前，先考虑是否可以恢复之前的会话：

claude -c                    # 继续最近一次会话（保留完整上下文）
claude --resume              # 弹出选择器，列出最近的会话供你选择
claude --resume abc123       # 恢复指定 ID 的会话

恢复的会话保留之前的全部对话上下文，不需要重新解释背景。

会话开始仪式（新会话）

如果是全新会话：

请阅读 CLAUDE.md 和 PROGRESS.md，告诉我当前项目进度和下一步应该做什么

Claude 会自动加载 CLAUDE.md，但 PROGRESS.md 需要显式要求读取。两者结合才能恢复完整上下文。

会话结束仪式

每次关闭会话前执行：

必做: /commit                        ← 确保代码已提交
必做: /module-done                   ← 更新 PROGRESS.md（模块状态 + 下次入口）
      (或手动更新 PROGRESS.md)
可选: 更新 CLAUDE.md                 ← 仅当发现新的编码约定或常见错误时
可选: /update-docs                   ← 有较多文件变更时更新代码地图
可选: /learn                         ← 踩到坑或发现重要经验时提取教训

更新 PROGRESS.md 的示例：

帮我更新 PROGRESS.md：
- 标记模块 B 已完成
- 在"下次继续的入口"写上：从模块 C（支付集成）开始，先设计 Webhook 处理流程

CLAUDE.md 什么时候需要更新？ 只有发现新的编码约定（如 "日期库统一用 date-fns"）或 Claude 常犯的错误时才更新 CLAUDE.md。模块进度的变化只更新 PROGRESS.md。

会话仪式速查卡

┌──────────────────────────────────────────────────────┐
│             恢复会话（优先）                           │
│  claude -c  或  claude --resume                       │
├──────────────────────────────────────────────────────┤
│             新会话开始                                │
│  "请阅读 CLAUDE.md 和 PROGRESS.md，总结进度和下一步"   │
├──────────────────────────────────────────────────────┤
│             正常开发                                  │
│  /module-plan → 执行 → 验证 → /code-review → /commit  │
├──────────────────────────────────────────────────────┤
│             会话结束                                  │
│  /commit → /module-done → (可选)/update-docs/learn     │
└──────────────────────────────────────────────────────┘

---

8. 跨会话持续性策略

8.1 持久化层级

项目的"记忆"分为静态配置和动态进度两类，再按加载可靠性分层：

层级	载体	性质	加载方式	内容	行数建议
L1 自动	根目录 CLAUDE.md	静态	每次会话自动加载	项目简介、技术选型、编码约定、常见错误	100-300 行
L2 自动	[tier]/CLAUDE.md	静态	Claude 读取该 tier 目录文件时自动加载	Tier 级上下文：tier 技术栈、构建/测试命令、tier 编码约定（仅声明了 tier 的项目）	每个 50-100 行
L3 按需自动	src/xxx/CLAUDE.md	静态	Claude 读取该目录文件时自动加载	模块级上下文：接口契约、数据模型、注意事项	每个 50-150 行
L4 显式读取	PROGRESS.md	动态	会话开始时显式要求读取	模块进度表、下次继续的入口	不限
L4 显式读取	docs/architecture.md	静态	需要时显式要求读取	全局设计详情：架构图、数据模型、模块边界、设计决策	不限
L4 显式读取	docs/plan.md	临时	需要时显式要求读取	当前模块的实施方案（每个模块覆盖更新）	不限
L5 全局经验	/learn 产出	静态	持久化到 ~/.claude/，自动生效	经验教训、踩坑记录	—

核心分离原则：静态配置（CLAUDE.md）与动态进度（PROGRESS.md）分开存放。

• CLAUDE.md = 宪法（constitution）：技术选型、编码约定、常见错误。项目生命周期内很少改动。
• PROGRESS.md = 工作日志（logbook）：模块状态、当前入口。每次会话都可能更新。

为什么不把进度放 CLAUDE.md？

1. Claude Code 在加载 CLAUDE.md 时注入 "this context may or may not be relevant"——频繁变化的进度信息会稀释稳定的编码指令
2. Boris Cherny 的 CLAUDE.md 仅约 100 行（~2.5k tokens），只放 conventions 和 mistakes，不放进度
3. Anthropic 官方长周期 Agent 指南明确分离：CLAUDE.md（静态）+ claude-progress.txt（动态）

8.2 CLAUDE.md 与 PROGRESS.md 的维护原则

CLAUDE.md（静态配置，< 300 行）：

1. 保持精简: 控制在 300 行以内。超出说明有内容应该外移
2. 很少改动: 只在发现新的编码约定或 Claude 常犯的错误时更新
3. 不放进度: 模块状态、当前入口等动态信息全部放 PROGRESS.md

适合放入 CLAUDE.md 的内容：

• 项目简介（一段话）
• 技术选型表（框架、数据库、认证等）
• 模块清单（只列名称和职责，不含状态）
• 编码约定（如 "日期库统一用 date-fns，不用 moment"）
• Claude 常犯的错误（如 "不要在 Server Component 中用 useState"）
• 参考文档指针（docs/plan.md、docs/architecture.md 等）

不适合放入 CLAUDE.md 的内容（应外移）：

• 模块进度和状态 → PROGRESS.md
• 全局设计详情（架构图、数据模型、模块边界、设计决策） → docs/architecture.md
• 当前模块的实施方案 → docs/plan.md（临时，每模块覆盖）
• 架构决策记录 (ADR) → docs/adr/ 目录
• 模块接口契约 → src/xxx/CLAUDE.md

PROGRESS.md（动态进度，每次会话更新）：

1. 每次会话结束时更新: 标记完成的模块，更新下次入口
2. 入口要具体: "下次继续的入口"写得像交接文档——下一个人（或下一次的你）能直接上手
3. 定期清理: 已完成的模块细节精简为一行记录，不保留完整步骤
4. 会话开始时显式读取: 新会话需要用 请阅读 PROGRESS.md 显式加载（不会自动加载）

8.3 大型项目的分级策略

当项目超过 5 个模块时，使用子目录 CLAUDE.md 分散上下文：

项目根目录/
├── CLAUDE.md              ← 静态配置：项目简介、技术选型、编码约定（< 300 行）
├── PROGRESS.md            ← 动态进度：模块状态表、下次继续的入口
├── src/
│   ├── auth/
│   │   └── CLAUDE.md      ← 模块级：认证模块的接口契约、数据模型、注意事项
│   ├── orders/
│   │   └── CLAUDE.md      ← 模块级：订单模块的接口契约、数据模型、注意事项
│   └── payments/
│       └── CLAUDE.md      ← 模块级：支付模块的接口契约、数据模型、注意事项
└── docs/
    ├── architecture.md    ← 全局设计详情（架构图、数据模型、模块边界、设计决策）
    ├── plan.md            ← 当前模块的实施方案（临时，每模块覆盖更新）
    └── adr/               ← 架构决策记录

为什么用子目录 CLAUDE.md 而不是在根 CLAUDE.md 中写指针？ Claude Code 内置了子目录自动加载机制——当 Claude 读取某个目录下的文件时，该目录的 CLAUDE.md 会自动加载到上下文中。这是确定性的（由系统保证），比在根 CLAUDE.md 中写 "需要时请读取 xxx" 更可靠（后者依赖 Claude 自行判断，Vercel 的测试数据显示仅约 56% 的情况会被执行）。

开发某个模块时，只需让 Claude 进入对应目录工作，模块级 CLAUDE.md 会自动生效：

开始开发支付模块，请先阅读 src/payments/ 下的代码了解当前状态

根目录 CLAUDE.md 始终自动加载提供全局视角，src/payments/CLAUDE.md 在 Claude 进入该目录时自动加载提供模块细节。

多 tier 项目的目录结构

多 tier 项目在根目录和模块之间增加一层 tier 目录，每个 tier 有自己的 CLAUDE.md：

项目根目录/
├── CLAUDE.md                  ← L1 静态配置：项目简介、技术选型、编码约定（< 300 行）
├── PROGRESS.md                ← L4 动态进度：模块状态表（模块名用斜杠标记 tier）
├── backend/
│   ├── CLAUDE.md              ← L2 tier 配置：后端技术栈、构建/测试命令、编码约定（50-100 行）
│   └── src/
│       ├── auth/
│       │   └── CLAUDE.md      ← L3 模块级：认证模块的接口契约、数据模型、注意事项
│       └── orders/
│           └── CLAUDE.md      ← L3 模块级：订单模块的接口契约、数据模型、注意事项
├── frontend/
│   ├── CLAUDE.md              ← L2 tier 配置：前端技术栈、构建/测试命令、编码约定（50-100 行）
│   └── src/
│       ├── auth/
│       │   └── CLAUDE.md      ← L3 模块级：认证页面的组件契约、状态管理、注意事项
│       └── orders/
│           └── CLAUDE.md      ← L3 模块级：订单页面的组件契约、状态管理、注意事项
└── docs/
    ├── architecture.md        ← 全局设计详情（含 API 契约章节）
    ├── plan.md                ← 当前模块的实施方案
    └── adr/                   ← 架构决策记录

加载层级：L1（根 CLAUDE.md，自动）→ L2（tier CLAUDE.md，进入 tier 目录时自动）→ L3（模块 CLAUDE.md，进入模块目录时自动），逐层细化上下文。

---

9. 质量关卡速查

在不同阶段应触发的质量检查：

时机	触发动作	说明
架构规划完成后	/plan-review project	需求覆盖、依赖完整性审查（推荐）
模块方案确认后	/plan-review 模块名	方案可行性、接口一致性审查（可选）
写完一段代码	/code-review	日常轻量检查（简单模块可跳过，见 5.2）
标记模块完成时	/module-done	Code Review Gate：检查未提交变更，提醒运行 code-review
构建失败	/build-fix	自动诊断修复
模块实现时	/module-dev	按 plan 逐步实现，关键行为先写测试，每步 Spec Check，Phase 4 验收
涉及数据库改动	Database Reviewer 自动触发	Schema、索引、RLS 检查
涉及认证/用户输入	Security Reviewer 自动触发	OWASP Top 10 检查
所有模块完成、上线前	/verify	全量技术兜底：构建 + 类型 + lint + 测试 + console.log
合并到主分支前	/review-pr	6 维度深度审查
上线前	/e2e + audit-website	端到端测试 + 全面审计

---

10. 故障排除与常见陷阱

构建失败

/build-fix

如果 /build-fix 无法解决，尝试更具针对性的命令：

• Go 编译错误: /go-build

测试失败

/module-dev

再次运行 /module-dev 进入 Refinement Mode，Phase 4 会定位失败的测试并修复。原则：修实现，不改测试（除非测试本身有误）。

方向跑偏：Re-plan

"Plan Mode discipline: when something goes sideways, re-plan. Don't keep pushing." — Boris Cherny

当发现实现偏离预期、越改越乱时，停下来重新规划，不要硬推：

Shift+Tab → 切回 Plan 模式
当前实现遇到了 XXX 问题，让我们重新规划一下方案

这比反复用 /build-fix 修补更有效。

会话上下文丢失

如果感觉 Claude 偏离了之前的约定：

请重新阅读 CLAUDE.md，严格按照其中的架构决策和技术选型继续开发

代码质量下降

/refactor-clean

分析死代码、冗余代码并安全清除。

常见陷阱（来自 Anthropic 官方总结）

陷阱	症状	对策
One-shotting	试图一次做完所有模块，上下文耗尽，留下半成品	每次只做一个功能，做完提交再做下一个
Premature Completion	Claude 看到已有部分功能就宣布完成，实际还有很多没做	在 PROGRESS.md 中维护明确的功能清单和状态标记
Context Exhaustion	项目后期 Claude 要读太多文件，上下文不够用	及时 /compact；保持 CLAUDE.md 精简；用模块级 CLAUDE.md 分散上下文（详见 8.3）
MCP 上下文挤占	启用过多 MCP 后，200k 上下文缩减到 70k	在项目配置中用 disabledMcpServers 禁用不需要的 MCP

---

11. 附录：项目模板

新项目初始化时需要创建两个文件。

CLAUDE.md 模板（静态配置，目标 < 300 行）

# [项目名称]

## 项目简介
一句话描述项目目标。

## 功能范围
- 包含：功能 A、功能 B、功能 C
- 不包含：功能 X（计划 v2）、功能 Y（不做）

## 技术选型
| 类别 | 选择 | 理由 |
|:---|:---|:---|
| 框架 | Next.js 15 | 团队熟悉 React 生态 |
| 数据库 | Supabase | MVP 优先开发速度 |
| 认证 | Supabase Auth | 与数据库一体化 |
| 部署 | Vercel | 与 Next.js 无缝集成 |

## 架构概览
前后端分离，Next.js API Routes + Supabase。
详细架构图、数据模型和模块边界见 `docs/architecture.md`。

## 模块清单
- auth/ — 用户认证（注册、登录、Token 刷新）
- orders/ — 订单系统（CRUD、分页、状态流转）
- payments/ — 支付集成（Stripe 一次性支付、订阅、Webhook）
- admin/ — 管理后台（用户管理、订单管理）

## 编码约定
- 日期库统一用 date-fns，不用 moment
- 分页统一用 cursor-based，不用 offset
- API 响应统一用 { success, data, error } 格式
- 环境变量清单见 .env.example

## 注意事项
- Stripe Webhook 需要配置公网 URL（开发时用 ngrok）
- Supabase RLS 策略必须在 Schema 迁移中一并创建
- 不要在 Server Component 中使用 useState/useEffect

## 参考文档
- `PROGRESS.md` — 模块进度和当前入口
- `docs/architecture.md` — 全局设计详情（架构图、数据模型、模块边界、设计决策）
- `docs/plan.md` — 当前模块的实施方案
- `docs/adr/` — 架构决策记录

多 tier 项目补充：在上述模板的"功能范围"之后增加"项目类型"节，声明 tier 结构。模块清单使用斜杠标记 tier（如 认证/后端、认证/前端）。具体格式见 project-plan.md Phase 5 item 1。

PROGRESS.md 模板（动态进度，每次会话更新）

# 项目进度

## 模块状态
| 模块 | 状态 | 备注 |
|:---|:---|:---|
| 数据库 Schema | 已完成 | |
| 用户认证 | 已完成 | |
| 订单系统 | 方案已确认 | CRUD 完成，缺分页 |
| 支付集成 | 未开始 | |
| 管理后台 | 未开始 | |

## 下次继续的入口
从订单模块的分页查询开始。参考 `src/orders/CLAUDE.md` 中的接口契约。
分页使用 cursor-based（见 `docs/adr/003-cursor-pagination.md`）。

## 已完成的里程碑
- 2024-01-15: 数据库 Schema 设计与迁移
- 2024-01-16: 用户注册/登录 API + JWT
- 2024-01-17: 订单 CRUD API

两个文件的分工：

• CLAUDE.md（~40 行模板）：每次会话自动加载，放不常变的配置和约定
• PROGRESS.md（~20 行模板）：每次会话开始时显式读取，放频繁变化的进度
• 合计约 60 行模板，留足业务内容空间

Tier-level CLAUDE.md 模板（多 tier 项目，目标 50-100 行）

多 tier 项目中，每个 tier 目录各一份。

# [Tier 名称] (Backend / Frontend)

## 技术栈
| 类别 | 选择 | 版本 |
|:---|:---|:---|
| 运行时 | Node.js | 20.x |
| 框架 | Express | 4.x |
| ORM | Prisma | 5.x |
| 测试 | Vitest | 1.x |

## 构建命令
| 操作 | 命令 |
|:---|:---|
| 开发 | `cd backend && npm run dev` |
| 构建 | `cd backend && npm run build` |
| Lint | `cd backend && npm run lint` |
| 类型检查 | `cd backend && npm run typecheck` |

## 测试命令
| 操作 | 命令 |
|:---|:---|
| 单元测试 | `cd backend && npm test` |
| 集成测试 | `cd backend && npm run test:integration` |
| 覆盖率 | `cd backend && npm run test:coverage` |

## 编码约定
- [Tier 特有的编码约定，如后端的错误处理模式、前端的组件命名规则]
- [文件组织规则]
- [导入顺序规则]

## 注意事项
- [Tier 特有的常见错误和陷阱]

多 tier 项目 PROGRESS.md 模板（模块名用斜杠标记 tier）

# 项目进度

## 模块状态
| 模块 | 状态 | 备注 |
|:---|:---|:---|
| 数据库 Schema | 已完成 | |
| 认证/后端 | 已完成 | |
| 认证/前端 | 方案已确认 | 依赖：认证/后端 |
| 订单/后端 | 未开始 | |
| 订单/前端 | 未开始 | 依赖：订单/后端 |
| 支付/后端 | 未开始 | |
| 支付/前端 | 未开始 | 依赖：支付/后端 |

## 下次继续的入口
从认证/前端模块开始。认证/后端已完成，API 契约见 docs/architecture.md。
参考 backend/src/auth/CLAUDE.md 中的接口契约。

## 已完成的里程碑
- 2024-01-15: 数据库 Schema 设计与迁移
- 2024-01-16: 认证/后端 — 注册/登录 API + JWT