教程概述

/prompts 是 oh-my-codex 的角色系统，通过预定义的专业角色（architect/executor/debugger/critic）实现多阶段协作开发。

你将学到

• ✅ /prompts 系统的工作原理
• ✅ 四个核心角色的职责和使用场景
• ✅ 角色切换策略
• ✅ 自定义角色方法
• ✅ 多角色协作实战

触发方式标识

trigger_mode: "显式命令（/prompts:role）"
codex_native_alternative: "无（需手动切换上下文）"
superpowers_equivalent: "子代理系统"
when_to_use_omx: "需要专业视角的任意任务"
when_to_skip_omx: "极简单、单阶段任务"

为什么需要 /prompts？

单一视角的问题

flowchart TD
    A[需求] --> B[通用 AI 执行]
    B --> C[设计考虑不全]
    C --> D[代码质量不稳定]
    D --> E[测试覆盖不足]

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

多角色协作的优势

flowchart TD
    A[需求] --> B[/prompts:architect]
    B --> C[架构设计]
    C --> D[/prompts:executor]
    D --> E[代码实现]
    E --> F[/prompts:debugger]
    F --> G[问题调试]
    G --> H[/prompts:critic]
    H --> I[代码审查]
    I --> J[高质量交付]

    style B fill:#e1f5ff
    style D fill:#e1f5ff
    style F fill:#e1f5ff
    style H fill:#e1f5ff

四个核心角色

角色概览

角色详解

/prompts:architect

职责：

• 分析需求并设计技术方案
• 评估技术选型的优缺点
• 定义系统架构和模块边界
• 识别潜在风险

使用场景：

/prompts:architect "设计一个支持 10k QPS 的 API 系统"
/prompts:architect "评估 GraphQL vs REST 的利弊"
/prompts:architect "设计微服务拆分方案"

输出示例：

## 架构设计方案

### 技术选型
- API 网关：Kong（理由：插件丰富、性能高）
- 服务框架：Express.js（团队熟悉）
- 缓存：Redis（会话和热点数据）
- 数据库：PostgreSQL（关系型数据）

### 架构图
[负载均衡] -> [API Gateway] -> [Service A] -> [DB]
                            -> [Service B] -> [Redis]

### 风险评估
- 风险：单点故障 -> 缓解：多实例部署
- 风险：缓存穿透 -> 缓解：布隆过滤器

/prompts:executor

职责：

• 根据设计实现代码
• 编写单元测试
• 代码重构
• 集成实现

使用场景：

/prompts:executor "实现上述架构的 API 服务"
/prompts:executor "根据 PRD 实现用户认证模块"
/prompts:executor "重构这个函数，提高可读性"

输出示例：

// auth.service.ts
export class AuthService {
  async login(email: string, password: string): Promise<AuthResult> {
    const user = await this.userRepo.findByEmail(email);
    if (!user) {
      throw new UnauthorizedError('Invalid credentials');
    }

    const valid = await bcrypt.compare(password, user.passwordHash);
    if (!valid) {
      throw new UnauthorizedError('Invalid credentials');
    }

    return this.generateTokens(user);
  }
}

/prompts:debugger

职责：

• 诊断代码问题
• 分析错误日志
• 定位性能瓶颈
• 排查复杂 Bug

使用场景：

/prompts:debugger "这个 API 返回 500，找出原因"
/prompts:debugger "分析这个内存泄漏"
/prompts:debugger "性能分析：为什么查询这么慢？"

输出示例：

## 问题诊断报告

### 现象
API 间歇性返回 500

### 根因分析
1. 数据库连接池耗尽
2. 异步操作未正确 await
3. 导致请求堆积

### 修复建议
1. 增加连接池大小
2. 添加 await 检查
3. 实现请求超时

/prompts:critic

职责：

• 代码质量审查
• 安全检查
• 性能优化建议
• 最佳实践检查

使用场景：

/prompts:critic "审查这个 PR 的代码质量"
/prompts:critic "检查这段代码的安全漏洞"
/prompts:critic "评估这个实现的性能"

输出示例：

## 代码审查报告

### 问题清单
- [ ] 缺少输入验证（高危）
- [ ] 硬编码配置（中危）
- [ ] 缺少错误处理（中危）

### 建议改进
1. 使用 joi 进行输入验证
2. 配置提取到环境变量
3. 添加 try-catch 块

### 评分：B（需要改进）

角色协作流程

标准四阶段流程

flowchart LR
    A[需求] --> B[/p:architect]
    B --> C{方案确定}
    C --> D[/p:executor]
    D --> E[代码实现]
    E --> F{遇到问题?}
    F -->|是| G[/p:debugger]
    G --> D
    F -->|否| H[/p:critic]
    H --> I[完成]

    style B fill:#e3f2fd
    style D fill:#e8f5e9
    style G fill:#fff3e0
    style H fill:#fce4ec

实战案例：用户系统开发

场景：开发用户认证系统

步骤 1：架构设计

/prompts:architect "设计用户认证系统，支持 JWT 和 Session"

输出：技术选型、数据库设计、API 设计

步骤 2：代码实现

/prompts:executor "实现上述架构的认证服务"

输出：可运行的代码

步骤 3：问题调试（可选）

/prompts:debugger "登录 API 返回 401，排查问题"

输出：问题根因和修复方案

步骤 4：代码审查

/prompts:critic "审查认证服务的代码质量"

输出：审查报告和改进建议

角色切换策略

何时切换角色

切换命令

# 从 architect 切换到 executor
/prompts:executor "基于上述架构实现代码"

# 从 executor 切换到 debugger
/prompts:debugger "排查以下问题..."

# 从 executor 切换到 critic
/prompts:critic "审查刚实现的代码"

自定义角色

创建自定义角色

在 ~/.omx/prompts/ 创建自定义角色文件：

# 创建性能专家角色
cat > ~/.omx/prompts/performance-expert.md << 'EOF'
# Performance Expert

You are a performance optimization expert.
Focus on:
- Algorithm efficiency
- Database query optimization
- Memory management
- Caching strategies
- Load testing

Always:
1. Measure before optimizing
2. Provide benchmarks
3. Consider trade-offs
EOF

使用自定义角色

/prompts:performance-expert "优化这个查询的性能"

反模式与常见错误

反模式 1：角色错配

❌ 错误：
用 executor 做架构设计

✅ 正确：
用 architect 做架构设计
用 executor 做代码实现

反模式 2：频繁切换

❌ 错误：
每分钟切换一次角色

✅ 正确：
完成当前阶段再切换
 architect -> executor -> critic

反模式 3：跳过 critic

❌ 错误：
实现后直接提交，不审查

✅ 正确：
重要代码必须经过 critic 审查

vs 原生 Codex

vs Superpowers

快速参考

命令速查

# 架构设计
/prompts:architect "描述你的架构问题"

# 代码实现
/prompts:executor "描述实现需求"

# 问题调试
/prompts:debugger "描述问题现象"

# 代码审查
/prompts:critic "描述审查范围"

# 自定义角色
/prompts:your-role "描述任务"

角色选择速查表

小结

/prompts 角色系统让 AI 助手像专业团队一样协作，是 oh-my-codex 的核心能力。

核心要点：

1. 根据任务阶段选择合适角色
2. architect -> executor -> critic 是标准流程
3. 遇到问题用 debugger
4. 可以自定义专业角色

上一篇：教程 3：$plan - 规划驱动的实现路径

下一篇：教程 5：$ralph 与执行模式