Claude Code + Codex 3.0 实战工作流 Dev：从配置到生产的完整指南

TLDR

Claude Code 3.0 工作流通过 /dev 命令实现了完整的开发生命周期自动化：需求澄清 → Codex 分析 → 生成开发计划 → 并发执行 → 测试验证。核心特性包括 codex-wrapper 并发调用、高测试覆盖率推荐（90%）、一键安装脚本。本文提供从零开始的配置教程和实战案例。

关键数据：

为什么需要 3.0 工作流

从 MCP 到 Skills 再到 Dev Workflow

1.0 版本（MCP Server）：

2.0 版本（Skills）：

3.0 版本（Dev Workflow）：

3.0 工作流的六大核心能力

1. 智能需求澄清

通过 AskUserQuestion 工具进行 2-3 轮交互式问答：

用户输入：实现用户登录功能

Claude Code 澄清：
Q1: 认证方式？
  - Email + 密码
  - 手机号 + 验证码
  - OAuth（Google/GitHub）

Q2: 会话管理？
  - JWT Token
  - Session Cookie
  - Redis Session

Q3: 安全要求？
  - 密码加密算法（bcrypt/argon2）
  - 登录失败限制
  - 双因素认证

2. Codex 深度分析

调用 Codex 分析代码库，提取：

3. 自动生成开发计划

通过 dev-plan-generator Agent 生成标准化文档：

.claude/specs/user-login/
└── dev-plan.md
    ├── 需求概述
    ├── 技术方案
    ├── 任务列表
    │   ├── Task 1: 数据库模型设计
    │   ├── Task 2: API 端点实现
    │   ├── Task 3: 前端表单组件
    │   └── Task 4: 集成测试
    ├── 测试要求（≥90% 覆盖率）
    └── 验收标准

4. 并发任务执行

codex-wrapper 工作原理：

Claude Code 调用 codex-wrapper --parallel
    ↓
从 stdin 读取任务配置（---TASK--- 格式）
    ↓
解析任务依赖关系
    ↓
拓扑排序（Kahn 算法）将任务分层
    ↓
第一层：无依赖任务并发执行
    ├── Task 1 → codex e --json
    ├── Task 2 → codex e --json
    └── Task 3 → codex e --json
    ↓
第二层：依赖第一层的任务执行
    └── Task 4 → codex e --json
    ↓
汇总结果（总数/成功/失败）返回

任务格式：

codex-wrapper --parallel <<'EOF'
---TASK---
id: backend_api
workdir: /project/backend
depends: database_model
---CONTENT---
implement REST endpoints

---TASK---
id: database_model
workdir: /project/backend
---CONTENT---
create User model with Prisma
EOF

并发策略：

输出和 Session 管理：

每个任务执行后返回：

恢复之前的会话：

# 继续之前未完成的任务
codex-wrapper resume thread_abc123 "继续实现功能"

# 或通过 stdin
codex-wrapper resume thread_abc123 - <<'EOF'
继续实现功能的剩余部分
EOF

超时控制：

5. 高测试覆盖率

每个任务推荐：

6. 标准化交付

最终输出：

环境配置：从零到生产

前置要求

操作系统：

为什么推荐 WSL1：

WSL1 配置示例：

# 安装 WSL1
wsl --install --no-distribution
wsl --set-default-version 1
wsl --install -d Ubuntu-22.04

# 访问 Windows 文件
cd /mnt/d/workspace/my-project

# 安装开发工具
sudo apt update
sudo apt install git python3 python3-pip

必需工具：

第一步：克隆配置仓库

# 克隆 myclaude 仓库
git clone https://github.com/cexll/myclaude.git ~/myclaude

# 查看目录结构
tree ~/myclaude -L 2
# 输出：
# myclaude/
# ├── dev-workflow/          # 3.0 工作流
# ├── skills/                # Skills 定义
# │   └── codex/
# ├── install.py             # 一键安装脚本
# └── README.md

第二步：执行一键安装

# 安装 dev 工作流
cd ~/myclaude
python3 install.py --module dev

# 安装过程：
# [1/5] 检查依赖（uv, codex）
# [2/5] 安装 codex-wrapper
# [3/5] 配置 Claude Code Skills
# [4/5] 安装 dev-workflow 命令
# [5/5] 验证安装

install.py 做了什么：

  1. 安装 codex-wrapper：

    # 安装到 ~/.local/bin/codex-wrapper
# 添加到 PATH

  2. 配置 Skills：

    # 复制到 ~/.claude/skills/codex/
# 包含 SKILL.md 和 scripts/codex.py

  3. 安装 /dev 命令：

    # 复制到 ~/.claude/commands/dev.md
# 注册 dev-plan-generator Agent

  4. 验证安装：

    # 测试 codex-wrapper 调用
# 测试 /dev 命令可用性

第三步：配置 Codex

⚠️ 重要：sandbox_mode 必须设置为 workspace-write 或更高权限，否则 Codex 无法写入文件。

3.1 配置 config.yaml

编辑 ~/.codex/config.yaml：

# 推荐配置（平衡性能和成本）
model = "gpt-5.1-codex-max"
model_reasoning_effort = "high"          # 不推荐 xhigh（浪费 token 和时间）
model_reasoning_summary = "detailed"
approval_policy = "never"                # 自动执行，无需确认
sandbox_mode = "workspace-write"         # 允许写入工作区（最低要求）
disable_response_storage = true
network_access = true

配置说明：

参数 推荐值 原因
model gpt-5.1-codex-max 最佳代码生成质量
reasoning_effort high xhigh 更高，提升有限
sandbox_mode workspace-write 允许修改文件，workspace-read 无法写入
approval_policy never 自动化执行，避免手动确认

3.2 配置 AGENTS.md（推荐）

创建 ~/.codex/AGENTS.md 定义 Codex 的行为准则：

You are Linus Torvalds. Apply kernel maintainer-level scrutiny to all code changes. Prioritize eliminating complexity and potential defects. Enforce code quality following KISS, YAGNI, and SOLID principles. Reject bloat and academic over-engineering.

Check if the project has a CLAUDE.md file. If it exists, read it as context.

为什么需要 AGENTS.md：

AGENTS.md 的作用：

第四步：清理 Claude Code 的 MCP 配置

⚠️ 关键步骤：不清理 MCP 会导致 Skills 调用失败或冲突。

为什么要清理：

注意：

# 移除所有 MCP Server
claude mcp list
claude mcp remove codex-cli  # 如果存在

# 清理 Claude Code 的 AGENTS.md（如果存在）
# 注意：这里清理的是 ~/.claude/AGENTS.md，不是 ~/.codex/AGENTS.md
rm ~/.claude/AGENTS.md

# 验证清理结果
claude mcp list  # 应为空
ls ~/.claude/AGENTS.md  # 应不存在
ls ~/.codex/AGENTS.md  # 应存在（第三步创建的 Codex 配置）

第五步：验证安装

# 启动 Claude Code
claude

# 测试 /dev 命令
/dev "创建一个计算斐波那契数列的函数"

# 预期流程：
# 1. AskUserQuestion 询问需求细节
# 2. 调用 Codex 分析代码库
# 3. 生成 dev-plan.md
# 4. 并发执行任务
# 5. 运行测试并报告覆盖率
# 6. 输出执行摘要

实战案例：实现用户认证功能

场景描述

为一个 Express.js 后端添加用户认证功能，包括：

完整执行流程

阶段 1：需求澄清

用户输入：
/dev "实现用户认证功能"

Claude Code 询问：
Q1: 认证方式？
  ✓ Email + 密码
  - 手机号 + 验证码
  - OAuth

Q2: Token 类型？
  ✓ JWT
  - Session Cookie

Q3: 安全措施？
  ✓ bcrypt 加密
  ✓ 登录失败限制
  - 双因素认证

用户选择：Email + 密码 + JWT + bcrypt + 失败限制

阶段 2：Codex 分析

# Claude Code 调用 Codex 分析代码库
codex-wrapper - <<'EOF'
分析现有代码库，提取用户认证相关的技术栈和架构模式：

1. 识别当前使用的 Web 框架和版本
2. 识别数据库类型和 ORM
3. 检查现有认证实现
4. 识别架构模式（RESTful/GraphQL、分层结构等）
5. 列出相关中间件和工具

输出格式：
- 技术栈：框架、数据库、现有认证
- 架构模式：API 设计、分层结构
- 核心任务：需要实现的功能列表
EOF

# Codex 输出（示例）：
技术栈：
- 框架：Express.js 4.18
- 数据库：PostgreSQL + Prisma ORM
- 现有认证：无

架构模式：
- RESTful API
- 中间件模式（已有 errorHandler, logger）
- 分层架构（routes → controllers → services → models）

核心任务：
1. 数据库模型设计（User 表 + 索引）
2. 认证服务实现（注册、登录、Token 生成）
3. API 端点（POST /auth/register, POST /auth/login）
4. 中间件（JWT 验证、失败限制）
5. 集成测试（覆盖率 ≥90%）

阶段 3：生成开发计划

# Claude Code 调用 dev-plan-generator Agent
# 生成 .claude/specs/user-auth/dev-plan.md

# dev-plan.md 内容：
## 需求概述
实现基于 JWT 的用户认证系统，支持注册、登录、密码加密、失败限制。

## 技术方案
- 数据库：Prisma + PostgreSQL
- 加密：bcrypt（salt rounds = 10）
- Token：jsonwebtoken（过期时间 7 天）
- 限流：express-rate-limit（5 次/小时）

## 任务列表

### Task 1: 数据库模型设计
**文件**：prisma/schema.prisma
**内容**：
- User 模型（id, email, password, createdAt）
- 唯一索引（email）
- 迁移脚本

**测试**：
- 模型验证测试
- 索引唯一性测试

### Task 2: 认证服务实现
**文件**：src/services/authService.js
**内容**：
- register(email, password)
- login(email, password)
- generateToken(userId)
- verifyToken(token)

**测试**：
- 注册成功/失败场景
- 登录成功/失败场景
- Token 生成/验证

### Task 3: API 端点
**文件**：src/routes/authRoutes.js, src/controllers/authController.js
**内容**：
- POST /auth/register
- POST /auth/login
- 输入验证（express-validator）

**测试**：
- API 集成测试
- 输入验证测试

### Task 4: 中间件
**文件**：src/middleware/authMiddleware.js, src/middleware/rateLimitMiddleware.js
**内容**：
- JWT 验证中间件
- 登录失败限制中间件

**测试**：
- 中间件单元测试
- 限流逻辑测试

## 测试要求
- 单元测试覆盖率 ≥90%
- 集成测试覆盖核心流程
- 使用 Jest + Supertest

## 验收标准
- ✓ 用户可以注册（密码已加密）
- ✓ 用户可以登录（返回 JWT）
- ✓ 登录失败 5 次后限制 1 小时
- ✓ 测试覆盖率 ≥90%

阶段 4：并发执行

# Claude Code 调用 codex-wrapper 并发执行
codex-wrapper --parallel <<'EOF'
---TASK---
id: database_model
workdir: ~/projects/my-app
---CONTENT---
根据 dev-plan.md Task 1 要求，创建 User 数据库模型：
- 使用 Prisma 定义 User 模型（id, email, password, createdAt）
- 添加 email 唯一索引
- 生成并运行迁移脚本
- 编写模型验证测试（覆盖率 ≥90%）

---TASK---
id: auth_service
workdir: ~/projects/my-app
depends: database_model
---CONTENT---
根据 dev-plan.md Task 2 要求，实现认证服务：
- register(email, password) - bcrypt 加密
- login(email, password) - 验证并生成 JWT
- generateToken(userId) - 7 天过期
- verifyToken(token)
- 编写单元测试（覆盖率 ≥90%）

---TASK---
id: api_endpoints
workdir: ~/projects/my-app
depends: auth_service
---CONTENT---
根据 dev-plan.md Task 3 要求，实现 API 端点：
- POST /auth/register
- POST /auth/login
- 使用 express-validator 验证输入
- 编写集成测试（覆盖率 ≥90%）

---TASK---
id: middleware
workdir: ~/projects/my-app
---CONTENT---
根据 dev-plan.md Task 4 要求，实现中间件：
- JWT 验证中间件
- 登录失败限制中间件（express-rate-limit）
- 编写中间件单元测试（覆盖率 ≥90%）
EOF

# 输出示例：
# ======================================
# Parallel Execution Summary
# ======================================
# Total tasks: 4
# Successful: 4
# Failed: 0
#
# Task Results:
# [✓] database_model (session: thread_abc123) - 完成时间: 45s
# [✓] auth_service (session: thread_def456) - 完成时间: 68s
# [✓] api_endpoints (session: thread_ghi789) - 完成时间: 52s
# [✓] middleware (session: thread_jkl012) - 完成时间: 38s

执行流程说明：

第一层（并行执行）：

第二层（等待第一层完成）：

第三层（等待第二层完成）：

阶段 5：测试验证

# 运行完整测试套件
npm test -- --coverage

# 输出：
Test Suites: 4 passed, 4 total
Tests:       28 passed, 28 total
Coverage:    93.2% (≥90% ✓)

File                          | % Stmts | % Branch | % Funcs | % Lines
------------------------------|---------|----------|---------|--------
src/services/authService.js   |   95.2  |   92.3   |   100   |   94.8
src/controllers/authController|   91.7  |   88.9   |   100   |   91.2
src/middleware/authMiddleware |   94.1  |   90.0   |   100   |   93.8
prisma/schema.prisma          |   100   |   100    |   100   |   100

阶段 6：执行摘要

Claude Code 输出：

## 执行摘要

### 已完成任务
✓ Task 1: 数据库模型设计（prisma/schema.prisma:1-15）
✓ Task 2: 认证服务实现（src/services/authService.js:1-87）
✓ Task 3: API 端点（src/routes/authRoutes.js:1-23, src/controllers/authController.js:1-56）
✓ Task 4: 中间件（src/middleware/authMiddleware.js:1-34, src/middleware/rateLimitMiddleware.js:1-18）

### 测试覆盖率
- 总体覆盖率：93.2%（≥90% ✓）
- 单元测试：24 个
- 集成测试：4 个

### 文件变更
- 新增：7 个文件
- 修改：2 个文件（package.json, app.js）
- 代码行数：+312 行

### 风险点
- 密码重置功能未实现（后续任务）
- 生产环境需配置 JWT_SECRET 环境变量
- 建议添加日志记录（登录失败、Token 过期）

### 后续步骤
1. 部署到测试环境验证
2. 实现密码重置功能
3. 添加用户权限管理

最佳实践

1. Codex 配置优化

不推荐 xhigh reasoning effort：

配置 Token 消耗 执行时间 质量提升
high 5K tokens 30 秒 基准
xhigh 15K tokens 90 秒 +5%

结论：xhigh 成本高 3 倍，质量提升有限，不适合生产环境。

推荐 sandbox_mode 配置：

模式 权限 适用场景
workspace-read 只读 代码分析、审查
workspace-write 读写工作区 开发、重构（推荐）
full 读写整个文件系统 系统级任务（谨慎使用）

AGENTS.md 的最佳实践：

配置 ~/.codex/AGENTS.md 可以统一 Codex 的代码质量标准：

You are Linus Torvalds. Apply kernel maintainer-level scrutiny to all code changes. Prioritize eliminating complexity and potential defects. Enforce code quality following KISS, YAGNI, and SOLID principles. Reject bloat and academic over-engineering.

Check if the project has a CLAUDE.md file. If it exists, read it as context.

AGENTS.md 的优势：

何时需要 AGENTS.md：

2. Claude Code 模型选择

推荐 Sonnet 4.5：

不推荐 Haiku：

3. 任务拆分原则

独立任务（并行执行）：

依赖任务（串行执行）：

4. 测试覆盖率策略

90% 覆盖率的实现方法：

不计入覆盖率的代码：

5. 成本控制

月成本估算（210 元预算）：

服务 模型 用量 成本
Claude Code Sonnet 4.5 500K tokens 150 元
Codex GPT-5.1 Codex Max 1M tokens 60 元

节省成本的技巧：

常见问题排查

Q1: install.py 执行失败

错误信息：

[ERROR] uv not found in PATH

解决方案：

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 添加到 PATH
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证安装
uv --version

Q2: codex-wrapper 调用失败

错误信息：

[ERROR] codex command not found

解决方案：

# 安装 Codex CLI
uv tool install codex

# 验证安装
codex --version

# 配置 API Key
export OPENAI_API_KEY="your-api-key"

Q3: /dev 命令不可用

错误信息：

Unknown command: /dev

解决方案：

# 检查命令文件是否存在
ls ~/.claude/commands/dev.md

# 如果不存在，手动复制
cp ~/myclaude/dev-workflow/dev.md ~/.claude/commands/

# 重启 Claude Code

Q4: 如何提升测试覆盖率

提示信息：

[INFO] Coverage 78% (建议提升至 90%)

解决方案：

# 查看未覆盖的代码
npm test -- --coverage --verbose

# 常见原因：
# 1. 缺少边界测试（null, undefined, 空数组）
# 2. 缺少异常测试（try-catch 分支）
# 3. 缺少集成测试（API 端点）

# 让 Codex 补充测试用例
codex-wrapper - <<'EOF'
补充测试用例，提升覆盖率至 90%：
- 添加边界测试（null, undefined, 空数组）
- 添加异常测试（try-catch 分支）
- 添加集成测试（API 端点）
- 运行测试并验证覆盖率 ≥90%
EOF

# 或使用恢复模式继续之前的会话
# codex-wrapper resume thread_xxxxx "继续补充测试用例"

Q5: Windows 环境配置问题

问题：install.py 在 PowerShell/Cmd 中失败

解决方案：使用 WSL1

# 安装 WSL1
wsl --install --no-distribution
wsl --set-default-version 1
wsl --install -d Ubuntu-22.04

# 进入 WSL
wsl

# 在 WSL 中执行配置
cd /mnt/c/Users/YourName/myclaude
python3 install.py --module dev

WSL1 优势：

总结

核心优势

3.0 工作流的三大突破：

  1. 端到端自动化

    • 从需求澄清到代码交付全流程自动化
    • 无需手动规划任务和编写测试
    • 标准化交付（代码 + 测试 + 文档）

  2. 高质量保证

    • 推荐 90% 测试覆盖率
    • 自动生成测试和覆盖率报告
    • 质量可控的代码交付

  3. 并发执行能力

    • codex-wrapper 支持多任务并行
    • 独立任务同时执行，依赖任务串行
    • 大幅缩短开发周期

适用场景

推荐使用 3.0 工作流：

不推荐使用 3.0 工作流：

成本效益

月成本 < 210 元：

生产力提升：

资源链接

官方资源：

API 服务：

相关技术：