教程概述

$plan 是 oh-my-codex 的规划技能，它将需求转化为可执行的 PRD（产品需求文档），是规划驱动开发的核心。

你将学到

• ✅ $plan 的工作原理
• ✅ PRD 的结构和生成机制
• ✅ 规划驱动的实现流程
• ✅ 与 /prompts:architect 的配合
• ✅ 计划到执行的衔接

触发方式标识

trigger_mode: "显式命令（$plan）"
codex_native_alternative: "手动规划对话"
superpowers_equivalent: "writing-plans 技能"
when_to_use_omx: "任何需要规划的任务"
when_to_skip_omx: "极简单、单文件修改"

为什么需要 $plan？

没有规划的问题

flowchart TD
    A[需求] --> B[直接开始编码]
    B --> C[遗漏边界情况]
    C --> D[代码重构]
    D --> E[功能遗漏]
    E --> F[返工循环]

    style B fill:#ffcccc
    style C fill:#ffcccc
    style F fill:#ffcccc

规划驱动的优势

flowchart TD
    A[需求] --> B[$plan 生成 PRD]
    B --> C[明确任务清单]
    C --> D[/prompts:executor 执行]
    D --> E[按清单完成]
    E --> F[一次交付]

    style B fill:#e1f5ff
    style C fill:#e1f5ff

$plan 是什么？

$plan 是 oh-my-codex 提供的规划工作流，它将你的需求转化为：

1. PRD 文档 - 详细的产品需求文档
2. 技术计划 - 实现方案和技术选型
3. 任务清单 - 可执行的原子化任务
4. 验收标准 - 明确的完成指标

输出位置

生成的计划存储在 .omx/plans/ 目录：

.omx/plans/
├── 20260325-feature-name/
│   ├── PRD.md              # 产品需求文档
│   ├── tech-spec.md        # 技术规格
│   └── tasks.json          # 任务清单

PRD 结构详解

PRD 标准模板

# 功能名称 PRD

## 1. 概述
- 目标：一句话描述这个功能的目的
- 背景：为什么需要这个功能
- 范围：包含和不包含的功能

## 2. 功能需求
### 2.1 用户故事
- 作为 [角色]，我想要 [功能]，以便 [价值]

### 2.2 功能清单
- [ ] 功能点 1
- [ ] 功能点 2
- [ ] 功能点 3

## 3. 技术方案
### 3.1 架构设计
[架构图或描述]

### 3.2 数据模型
[数据库表结构]

### 3.3 API 设计
[接口定义]

## 4. 验收标准
- [ ] 标准 1
- [ ] 标准 2
- [ ] 标准 3

## 5. 风险评估
- 风险 1：缓解措施
- 风险 2：缓解措施

完整实战案例

场景：实现 JWT 认证系统

步骤 1：运行 $plan

$plan "实现用户 JWT 认证系统，包含登录、注册、token 刷新"

生成的 PRD 示例：

# JWT 认证系统 PRD

## 1. 概述
- **目标**：实现基于 JWT 的用户认证系统
- **背景**：当前系统无认证机制，需要保护 API
- **范围**：
  - ✅ 包含：注册、登录、token 刷新、登出
  - ❌ 不包含：第三方登录、权限管理

## 2. 功能需求
### 2.1 用户故事
- 作为用户，我想要注册账号，以便使用系统
- 作为用户，我想要登录系统，以便访问受保护资源
- 作为用户，我想要 token 自动刷新，以免频繁登录

### 2.2 功能清单
- [ ] 用户注册 API
- [ ] 用户登录 API
- [ ] Token 生成（access + refresh）
- [ ] Token 刷新 API
- [ ] Token 验证中间件
- [ ] 登出 API（token 黑名单）

## 3. 技术方案
### 3.1 架构

Client -> API Gateway -> Auth Service -> Database | v JWT Token

### 3.2 数据模型
```typescript
// User 表
{
  id: string
  email: string
  passwordHash: string
  createdAt: Date
  updatedAt: Date
}

// RefreshToken 表
{
  id: string
  userId: string
  tokenHash: string
  expiresAt: Date
  revoked: boolean
}

3.3 API 设计

• POST /api/auth/register - 注册
• POST /api/auth/login - 登录
• POST /api/auth/refresh - 刷新 token
• POST /api/auth/logout - 登出

3.4 JWT 配置

{
  accessTokenSecret: process.env.JWT_ACCESS_SECRET,
  refreshTokenSecret: process.env.JWT_REFRESH_SECRET,
  accessTokenExpiry: '15m',
  refreshTokenExpiry: '7d'
}

4. 验收标准

• 注册接口返回 201，包含用户信息和 tokens
• 登录接口验证密码，返回 tokens
• Access token 15 分钟过期
• Refresh token 7 天过期
• Token 刷新接口验证 refresh token
• 受保护 API 验证 access token
• 登出使 refresh token 失效

5. 风险评估

• 密码泄露：使用 bcrypt 哈希
• Token 泄露：短期 token + HTTPS
• 并发刷新：使用 token 轮换

---

## 规划驱动的工作流程

```mermaid
flowchart TD
    A[明确需求] --> B[$plan 生成 PRD]
    B --> C{PRD 审查}
    C -->|需要修改| D[调整需求]
    D --> B
    C -->|批准| E[存储到 .omx/plans/]
    E --> F[/prompts:executor 执行]
    F --> G[按任务清单完成]
    G --> H[sparkshell 验证]

    style B fill:#e3f2fd
    style E fill:#e8f5e9
    style H fill:#fff3e0

与 /prompts:architect 的配合

架构规划组合

flowchart LR
    A[复杂需求] --> B[/prompts:architect]
    B --> C[生成架构方案]
    C --> D[$plan]
    D --> E[基于架构生成 PRD]
    E --> F[执行]

    style B fill:#e3f2fd
    style D fill:#e3f2fd

使用场景

场景 1：简单功能

$plan "添加用户头像上传"
# 直接生成 PRD

场景 2：复杂功能

/prompts:architect "设计微服务订单系统"
# 生成架构方案后
$plan "基于上述架构实现订单服务"
# 生成详细 PRD

PRD 审查与迭代

审查清单

□ 功能范围是否清晰
□ 技术方案是否可行
□ 验收标准是否可测试
□ 风险是否已识别
□ 时间估算是否合理

迭代流程

# 第 1 版 PRD
$plan "实现功能 X"

# 审查后调整
$plan "调整：添加性能要求，使用 Redis 缓存"

# 最终版
$plan "功能 X 最终版本"

反模式与常见错误

反模式 1：过度规划

❌ 错误：
为一个简单表单生成 50 页 PRD

✅ 正确：
根据复杂度调整 PRD 深度
- 简单功能：1-2 页
- 中等功能：3-5 页
- 复杂功能：5-10 页

反模式 2：规划而不执行

❌ 错误：
反复调整 PRD，从不进入执行

✅ 正确：
PRD "足够好" 就执行
在执行中发现问题再调整

反模式 3：忽视验收标准

❌ 不完整的 PRD：
没有验收标准章节

✅ 完整的 PRD：
明确的验收标准
可测试的完成指标

vs 原生 Codex

vs Superpowers

快速参考

命令速查

# 基础规划
$plan "功能描述"

# 基于架构规划
/prompts:architect "架构设计"
$plan "基于架构实现"

# 审查模式
$plan "审查并优化 PRD"

PRD 质量检查清单

• 一句话能说明功能目标
• 有明确的不做清单
• 用户故事符合格式
• 技术方案有具体选型
• 验收标准可验证

小结

$plan 将模糊的需求转化为清晰的执行路径，是 oh-my-codex 工作流的核心环节。

核心要点：

1. 任何非简单任务先用 $plan
2. PRD 是执行的基础文档
3. 审查 PRD 后再执行
4. 与 architect 配合处理复杂需求

上一篇：教程 2：$deep-interview - 意图澄清工作流

下一篇：教程 4：/prompts 角色系统详解