2.2 规划先行的设计与开发

为什么不能直接开始

很多人与 AI 协作的第一反应是直接开始：把需求扔给 AI，让它马上生成代码。这种做法往往效率很低。

最常见的问题是方向错误。就像盖房子不看图纸就开工，可能盖到一半才发现地基打错了位置。AI 在信息不足时会做出假设，这些假设可能与你的实际需求不符。

例如，某开发者让 Claude 实现实时仪表盘功能，AI 立刻开始编写 WebSocket 代码。但项目已经在用 Supabase，它内置了实时功能。如果先规划、先了解现有架构，就能避免重复造轮子。

规划先行的好处：

  • 避免方向性错误：先确认理解一致，再投入执行
  • 提高代码质量：AI 有机会理解整体架构，做出更合理的设计
  • 节省时间成本：减少后期调试和返工

实践证明，使用规划模式能显著提高开发效率和项目成功率。

Opencode 的 Plan 代理

Plan Mode 工作流程图

Opencode 专门设计了 Plan 代理来支持规划先行的工作方式。Opencode 采用 Build/Plan 双主代理架构：Build 代理负责执行，Plan 代理负责规划。

切换方法很简单：按 Tab 键即可在 Build 代理和 Plan 代理之间切换，界面会显示当前所在的代理标识。

在 Plan 代理下，AI 不会直接修改代码。它会：

  1. 先阅读项目文件，理解现有结构
  2. 分析代码依赖关系
  3. 制定详细的实施计划
  4. 等待你审核批准后再执行

一个典型的对话：

用户：我想给应用添加暗黑模式切换功能

AI（Plan Mode）：
好的，让我先分析一下项目结构...

【实施计划】
1. 创建主题配置文件 (src/theme/config.ts)
   - 定义亮色和暗色主题变量

2. 添加主题状态管理 (src/stores/themeStore.ts)
   - 使用 localStorage 持久化用户偏好

3. 修改现有组件
   - Header.tsx: 添加切换按钮
   - App.tsx: 包裹 ThemeProvider

4. 更新样式文件
   - 将硬编码颜色改为主题变量

预计影响：5 个文件
潜在风险：需要测试所有页面的显示效果

是否批准此计划？

你可以对计划提出修改意见，反复讨论直到满意，然后再批准执行。

探索-规划-执行三阶段法

Anthropic 工程师 Boris Cherny 分享过他使用 AI 编码代理的工作流：

我几乎所有会话都从规划模式开始。先和 AI 反复讨论计划，直到满意为止，然后切换到执行模式。一个好的计划真的非常重要。

基于这一理念，我们可以将 AI 协作分为三个阶段：

第一阶段：探索（Explore）

让 AI 先了解现有情况。这个阶段不做任何修改，只是收集信息。

典型提示词：

先不要写代码，帮我了解一下这个项目的结构，
特别是与 [功能X] 相关的部分。

第二阶段：规划（Plan）

让 AI 制定实施方案。明确要创建或修改哪些文件、执行顺序、潜在风险。

典型提示词：

我想实现 [功能描述]。
请先给我一个实施计划，包括：
1. 需要创建/修改的文件
2. 实施步骤
3. 潜在风险
不要直接写代码。

第三阶段：执行（Code）

审核通过后，让 AI 按计划实施。

典型提示词：

计划看起来不错，请按照计划开始实施。
完成每个步骤后告诉我进度。

这三个阶段可以迭代。执行中发现问题，回到规划阶段调整；信息不足，回到探索阶段收集更多背景。

AGENTS.md：项目的记忆文件

Opencode 有一个特殊功能：它会在每次对话开始时自动读取项目根目录的 AGENTS.md 文件。你可以把它当作项目的入职说明书——让 AI 一进来就知道项目背景、技术栈、代码规范、注意事项。

一个 AGENTS.md 模板：

# 项目概述
这是一个金融数据分析平台，主要功能是...

# 技术栈
- 前端：React + TypeScript
- 后端：Python + FastAPI
- 数据库：PostgreSQL

# 代码规范
- 使用函数式组件
- 变量命名采用驼峰式
- 每个函数需要注释

# 常用命令
- npm run dev: 启动开发服务器
- pytest: 运行测试

# 注意事项
- 不要修改 /generated/ 目录下的文件
- 敏感配置在 .env 中，不要提交

有了 AGENTS.md，你不需要每次对话都重复说明背景。AI 会自动理解项目约定，生成符合规范的代码。随着项目推进，你可以不断更新这个文件，记录重要决策和学到的教训。

注记兼容性说明

Opencode 也兼容 CLAUDE.md 格式。如果你的项目根目录同时存在 AGENTS.md 和 CLAUDE.md，Opencode 会优先读取 AGENTS.md。

金融场景：投资研究的规划先行

让我们用一个金融场景来说明规划先行的价值。

假设你要分析一家上市公司。传统做法是直接让 AI 写分析，但更好的方法是：

探索阶段：

我要分析 [公司名称] 这家公司。
请先告诉我分析一家上市公司通常需要哪些信息？
数据来源有哪些？

规划阶段：

基于刚才的讨论，请制定一个分析计划：
1. 需要收集哪些数据
2. 分析的顺序和框架
3. 最终输出什么格式的报告

执行阶段：

计划批准。请按步骤执行：
1. 先收集基本面数据
2. 完成后告诉我，我审核后再进行下一步

这种方法确保了：你和 AI 对任务的理解一致；分析框架经过讨论确认；每一步都有审核机会。