古法编程

规划模式（Planning Mode）是 Claude Code 的一项高级功能，它让 AI 在动手写代码前先制定详细的实施计划，经你确认后再执行，特别适合处理复杂的、多文件、多阶段的开发任务。本文将基于真实示例，完整拆解其在构建 REST API、执行数据库迁移、重构前端代码、实施安全方案以及优化网站性能这五大场景中的具体规划思路与执行步骤。

规划模式 5 大实战场景：REST API、数据库迁移、前端重构、安全实现与性能优化

规划模式将开发工作流分为两个清晰的阶段：计划阶段与实施阶段。你首先通过 /plan 指令或 claude --permission-mode plan 启动此模式，Claude 会分析任务并生成一份结构化的计划。你审阅、修改并批准后，Claude 才会按照计划逐步执行代码生成或修改。这种方法的核心价值在于将大型、模糊的任务分解为可控、可评估、可回滚的步骤，有效管理开发风险与复杂度。根据《Claude HowTo 完全指南》的介绍，规划模式是掌握 Claude Code 高级功能的重要一环。

以下是五个源自《规划模式实战示例》的典型场景及其规划思路提炼。

场景一：构建 REST API（8 阶段分解）

构建一个完整的 REST API 涉及技术选型、架构设计、编码实现、测试和部署等多个环节。直接动手容易遗漏需求或陷入细节。规划模式将其分解为 8 个逻辑阶段：

  1. 项目设置：初始化项目（如 Node.js + Express），配置 TypeScript，安装核心依赖（如数据库驱动、JWT 库）。
  2. 数据库层：设计数据表 schema（如用户表、文章表、评论表），创建数据库连接池和迁移脚本。
  3. 认证实现：规划用户注册、登录、JWT 签发与刷新、密码加密及中间件的具体实现流程。
  4. Posts API 实现：列出所有需要实现的端点（如 GET /api/posts、POST /api/posts），并明确每个端点的权限要求（如是否需要认证）。
  5. Comments API 实现：规划评论相关的端点及其与文章的关联。
  6. 验证与错误处理：集成请求参数验证库，规划全局错误处理器、输入净化和速率限制策略。
  7. 测试：规划单元测试、集成测试的编写顺序和覆盖率目标。
  8. 文档与部署：生成 Swagger 文档，编写 README，并配置 Docker 化与 CI/CD 流水线。

这种分解确保了从基础设施到业务逻辑、从功能到质量的全链路覆盖，每个阶段都有明确产出，便于并行开发和进度跟踪。

场景二：数据库迁移（10 天计划与双写安全策略）

将生产数据库从 MongoDB 迁移到 PostgreSQL 是高风险操作。规划模式的核心是制定一个包含双写（Dual-Write）和逐步切换的 10 天安全计划：

  • 分析准备（第1天）：深入分析现有数据模型、数据量与关系，设计 PostgreSQL 的对应 schema。
  • 新库搭建（第1天）：部署 PostgreSQL，创建 schema、索引和备份策略。
  • 双写实现（第2-3天）：这是安全迁移的关键。创建一个数据访问抽象层，让应用同时向新旧两个数据库写入数据，并实现一致性校验。
  • 数据迁移（第4天）：编写脚本，对生产数据的副本进行历史数据迁移和验证。
  • 逐步切换（第5-7天）：在生产环境启用双写，分批迁移历史数据，持续监控数据同步状态。
  • 新库为主（第8天）：将应用的读操作切换到 PostgreSQL，继续监控查询性能，并优化慢查询，双写仍保持。
  • 旧库退役（第9-10天）：确认稳定后，停止向 MongoDB 写入，将 MongoDB 作为备份保留两周，最后清理代码并归档下线旧库。

这个计划通过双写提供了“刹车”机制，任何阶段出现问题都可以快速回退到旧库，确保零数据丢失和业务连续性。

场景三：前端重构（按复杂度分组迁移 React Hooks）

将基于 Class 的 React 组件重构为 Hooks 是前端现代化的常见任务。规划模式的策略是按组件复杂度分组，从易到难迁移：

  1. 简单组件（~15个）：仅管理状态（State）的组件。规划使用 useState 替换 this.state 和 this.setState。
  2. 中等组件（~23个）：使用生命周期方法（如 componentDidMount）的组件。规划使用 useEffect 替换这些生命周期，并处理清理函数。
  3. 复杂组件（~8个）：包含多个生命周期、Refs 或复杂逻辑的组件。规划引入 useRef，并思考将共享逻辑提取为自定义 Hooks（如 useAuth、useFetch）。
  4. 性能优化与清理：在所有组件迁移后，规划使用 React.memo、useCallback 和 useMemo 进行优化，并清理旧的 Class 工具代码。

这种方法避免了“大爆炸”式重构带来的风险。通过先迁移叶子组件（依赖少的），再向上推进，每一步都有明确的测试验证点，确保应用在重构过程中始终保持可用。

场景四：安全实现（OWASP Top 10 对齐方案）

为 Web 应用实施全面的安全加固，规划模式提供了一个对齐行业标准的方案，系统性地覆盖 OWASP Top 10：

  • 安全审计与认证加固（第1-3天）：运行安全扫描，审计认证流程，并规划实施强密码策略、双因素认证（2FA）、速率限制和安全的会话管理。
  • 授权与数据保护（第3-5天）：设计并实现基于角色的访问控制（RBAC），规划敏感数据的加密存储与传输、PII 数据在日志中的脱敏。
  • 输入验证与安全加固（第5-6天）：规划所有端点的输入验证，集成防 XSS 的 CSP 策略，使用参数化查询防止 SQL 注入，添加 CSRF 防护，并配置安全响应头（如 Strict-Transport-Security）。
  • 监控、测试与合规（第7-10天）：规划安全事件日志、异常检测系统，进行渗透测试，并确保符合 GDPR 等法规要求。

每一步都直接对应 OWASP Top 10 中的具体风险项，使得安全工作从“补漏洞”转变为“建体系”。

场景五：性能优化（8 阶段方案与具体指标）

优化电商网站性能时，规划模式结合了度量、实施与监控。计划从定义当前基线指标（如 LCP 4.2s， FID 280ms）和优化目标（LCP <2.0s， FID <50ms）开始，并将优化分解为 8 个有先后顺序的阶段：

  1. 性能审计：使用 Lighthouse 和 Chrome DevTools 建立基准。
  2. 图片优化（预期收益大）：转换 WebP 格式、实现懒加载和 CDN 加速。
  3. 代码拆分与懒加载：实施路由级代码分割，减小初始包体积。
  4. 缓存策略：配置浏览器缓存、Service Worker 和后端数据缓存。
  5. 数据库优化：添加索引、优化慢查询、实现读写分离。
  6. 前端优化：压缩资源、移除无用 CSS、优化 React 渲染。
  7. 网络优化：启用 HTTP/2 和 Brotli 压缩，减少请求数。
  8. 监控与测试：建立性能预算和持续监控。

此计划将优化工作从影响最大的“快赢”项（如图片、代码拆分）开始，逐步深入到需要更多改动的层面（如数据库），确保每一步都能带来可测量的性能提升。

配套保障：setup-auto-mode-permissions.py 与安全权限基准

规划模式通常与权限模式（Permission Modes）配合使用，以确保计划在受控环境下执行。仓库中的 setup-auto-mode-permissions.py 脚本提供了一种渐进式、安全的权限配置方案，它定义了一个保守的基准权限集（CORE_PERMISSIONS），作为使用规划模式或其他高级功能前的安全起点。

这个基准权限集主要包含只读和本地检查类操作，例如：Read(*)、Glob(*)、Grep(*)、以及查看 Git 状态的 Bash(git status:*)、Bash(git log:*) 等。脚本设计了多个可选权限组，你可以按需通过参数开启：

  • --include-edits：允许文件编辑（Edit(*)、Write(*)）。
  • --include-tests：允许运行测试（如 Bash(pytest:*)）。
  • --include-git-write：允许本地 Git 提交等操作（Bash(git commit:*)）。
  • --include-packages：允许安装依赖（Bash(npm install:*)）。

关键设计思路：脚本有意排除了高风险命令（如 rm -rf、sudo、DROP TABLE、git push --force）。这为规划模式的执行环境建立了一个安全的“沙盒”基础。你可以先在这个基准上运行 /plan 生成计划，审查无误后，再有选择地开启必要的权限组来执行计划，实现了从“规划”到“执行”的权限平滑升级。

FAQ

Q: 使用规划模式会额外消耗很多 Token 或时间吗？ A: 规划阶段确实会产生一定的 Token 消耗，因为它需要进行深度分析。但这通常远少于在没有计划的情况下反复试错、修改所消耗的 Token 总量。对于复杂任务，规划模式通过减少错误和返工，从整体上提升了开发效率。

Q: 规划模式和 Extended Thinking（扩展思考）有什么区别？ A: 两者解决不同问题。规划模式专注于任务分解和流程设计，输出结构化的步骤清单。扩展思考则专注于单个问题的深度推理，例如在面对“该选微服务还是单体架构”这类架构决策时，AI 会进行更长时间的推理分析。在实际使用中，可以在规划模式的某个阶段内使用扩展思考来攻克技术难点。