Claude-Code-Workflow/docs/zh/skills/codex-workflow.md

Codex Skills - 工作流类

一句话定位

工作流类 Codex Skills 是协作分析和并行开发工作流系统 — 通过文档化讨论、多视角分析和协作规划实现高效的团队协作。

解决的痛点

痛点	现状	Codex Skills 方案
讨论过程丢失	讨论结果只保存结论	文档化讨论时间线
探索重复	每次分析重复探索代码库	共享发现板
调试盲目	缺少假设验证机制	假设驱动调试
协作割裂	各角色独立工作	多视角并行分析

Skills 列表

Skill	功能	触发方式
analyze-with-file	协作分析（4 视角）	/analyze-with-file TOPIC="..."
brainstorm-with-file	头脑风暴（4 视角）	/brainstorm-with-file TOPIC="..."
debug-with-file	假设驱动调试	/debug-with-file BUG="..."
collaborative-plan-with-file	协作规划	/collaborative-plan-with-file <task>
unified-execute-with-file	通用执行引擎	/unified-execute-with-file <session>
roadmap-with-file	需求路线图	/roadmap-with-file <requirements>
review-cycle	审查循环	/review-cycle <target>
workflow-test-fix-cycle	测试修复工作流	/workflow-test-fix-cycle <tests>

Skills 详解

analyze-with-file

一句话定位: 协作分析 — 文档化讨论、内联探索、理解演进的交互式分析

核心工作流:

Topic → Explore → Discuss → Document → Refine → Conclude → (Optional) Quick Execute

关键特性:

• 文档化讨论时间线: 捕获跨所有阶段的理解演进
• 每个关键点决策记录: 强制记录关键发现、方向变更、权衡
• 多视角分析: 支持最多 4 个分析视角（串行、内联）
• 交互式讨论: 多轮 Q&A，用户反馈和方向调整
• Quick execute: 将结论直接转换为可执行任务

决策记录协议:

触发	记录内容	目标部分
方向选择	选择内容、原因、替代方案	#### Decision Log
关键发现	发现内容、影响范围、置信度	#### Key Findings
假设变更	旧假设 → 新理解、原因、影响	#### Corrected Assumptions
用户反馈	用户原始输入、采用/调整原因	#### User Input

分析视角 (串行、内联):

视角	CLI 工具	角色	关注领域
Product	gemini	产品经理	市场契合度、用户价值、业务可行性
Technical	codex	技术主管	可行性、技术债务、性能、安全
Quality	claude	QA 主管	完整性、可测试性、一致性
Risk	gemini	风险分析师	风险识别、依赖、失败模式

会话文件夹结构:

{projectRoot}/.workflow/.analyze/ANL-{slug}-{date}/
├── discussion.md               # 讨论时间线 + 理解演进
├── explorations/               # 代码库探索报告
│   ├── exploration-summary.md
│   ├── relevant-files.md
│   └── patterns.md
└── conclusion.md               # 最终结论 + Quick execute 任务

执行流程:

Phase 1: Topic Analysis
    ├─ 检测深度模式 (quick/standard/deep)
    ├─ 会话检测: {projectRoot}/.workflow/.analyze/ANL-{slug}-{date}/
    └─ 输出: sessionId, depth, continueMode

Phase 2: Exploration
    ├─ 检测上下文: discovery-context.json, prep-package.json
    ├─ 代码库探索: Glob + Read + Grep 工具
    ├─ 写入: explorations/exploration-summary.md
    └─ 输出: explorationResults

Phase 3: Discussion (Multiple Rounds)
    ├─ 初始化: discussion.md (Section: Exploration Summary)
    ├─ Round 1: 基于 explorationResults 生成初始分析
    ├─ 迭代: 用户反馈 → 修正理解 → 更新 discussion.md
    └─ 每轮更新: Decision Log, Key Findings, Current Understanding

Phase 4: Refinement
    ├─ 合并: explorations/ 内容合并到 discussion.md
    ├─ 检查: 所有关键点已记录
    └─ 输出: refinedDiscussion

Phase 5: Conclusion
    ├─ 生成: conclusion.md (Executive Summary, Findings, Recommendations)
    └─ Quick Execute (可选): 生成可执行任务

Phase 6: (可选) Quick Execute
    ├─ 转换结论为: 任务 JSON 或 plan file
    └─ 调用: workflow-execute 或直接执行

深度模式:

模式	探索范围	分析轮次
quick	基础搜索，10 文件	1 轮
standard	标准探索，30 文件	2-3 轮
deep	深度探索，100+ 文件	3-5 轮

---

brainstorm-with-file

一句话定位: 多视角头脑风暴 — 4 视角（Product、Technical、Risk、User）并行分析

关键特性:

• 4 视角并行分析：Product、Technical、Risk、User
• 一致性评分和收敛判定
• 可行性建议和行动项

视角:

视角	关注领域
Product	市场契合度、用户价值、业务可行性
Technical	可行性、技术债务、性能、安全
Risk	风险识别、依赖、失败模式
User	可用性、用户体验、采用障碍

输出格式:

## 一致性判定
状态: <consensus_reached | consensus_blocked>
平均评分: <N>/5
收敛点: <list>
分歧点: <list>

## 可行性建议
推荐: <proceed | proceed-with-caution | revise | reject>
理由: <reasoning>
行动项: <action items>

---

debug-with-file

一句话定位: 假设驱动调试 — 文档化探索、理解演进、分析辅助修正

核心工作流:

Explore → Document → Log → Analyze → Correct Understanding → Fix → Verify

关键增强:

• understanding.md: 探索和学习的时间线
• 分析辅助修正: 验证和修正假设
• 整合: 简化已证明错误的理解，避免混乱
• 学习保留: 保留从失败尝试中学到的内容

会话文件夹结构:

{projectRoot}/.workflow/.debug/DBG-{slug}-{date}/
├── debug.log           # NDJSON 日志（执行证据）
├── understanding.md    # 探索时间线 + 整合理解
└── hypotheses.json     # 假设历史（带判定）

模式:

模式	触发条件	行为
Explore	无会话或无 understanding.md	定位错误源，记录初始理解，生成假设，添加日志
Continue	会话存在但无 debug.log 内容	等待用户复现
Analyze	debug.log 有内容	解析日志，评估假设，更新理解

假设生成: 基于错误模式生成针对性假设：

错误模式	假设类型
not found / missing / undefined	data_mismatch
0 / empty / zero / registered	logic_error
timeout / connection / sync	integration_issue
type / format / parse	type_mismatch

NDJSON 日志格式:

{"sid":"DBG-xxx-2025-01-21","hid":"H1","loc":"file.py:func:42","msg":"Check dict keys","data":{"keys":["a","b"],"target":"c","found":false},"ts":1734567890123}

Understanding Document 模板:

# Understanding Document

**Session ID**: DBG-xxx-2025-01-21
**Bug Description**: [original description]
**Started**: 2025-01-21T10:00:00+08:00

---

## Exploration Timeline

### Iteration 1 - Initial Exploration (2025-01-21 10:00)

#### Current Understanding
...

#### Evidence from Code Search
...

#### Hypotheses Generated
...

---

## Current Consolidated Understanding

### What We Know
- [valid understanding points]

### What Was Disproven
- ~~[disproven assumptions]~~

### Current Investigation Focus
[current focus]

---

collaborative-plan-with-file

一句话定位: 协作规划 — 多代理协作规划（替代 team-planex）

功能:

• 多代理协作规划
• planner 和 executor 并行工作
• 中间产物文件传递 solution

Wave Pipeline (逐 Issue 节拍):

Issue 1:  planner 规划 solution → 写中间产物 → 冲突检查 → 创建 EXEC-* → issue_ready
                ↓ (executor 立即开始)
Issue 2:  planner 规划 solution → 写中间产物 → 冲突检查 → 创建 EXEC-* → issue_ready
                ↓ (executor 并行消费)
Issue N:  ...
Final:    planner 发送 all_planned → executor 完成剩余 EXEC-* → 结束

---

unified-execute-with-file

一句话定位: 通用执行引擎 — 替代 workflow-execute

功能:

• 通用执行引擎
• 支持多种任务类型
• 自动会话恢复

会话发现:

1. 计算 .workflow/active/ 中的活跃会话数
2. 决策:
   • count=0 → 错误：无活跃会话
   • count=1 → 自动选择会话
   • count>1 → AskUserQuestion（最多 4 个选项）

---

roadmap-with-file

一句话定位: 需求路线图规划

功能:

• 需求到路线图的规划
• 优先级排序
• 里程碑定义

输出结构:

.workflow/.roadmap/{session-id}/
├── roadmap.md                 # 路线图文档
├── milestones.md              # 里程碑定义
└── priorities.json            # 优先级排序

---

review-cycle

一句话定位: 审查循环（Codex 版本）

功能:

• 代码审查
• 修复循环
• 验证修复效果

循环流程:

审查代码 → 发现问题 → [有问题] → 修复代码 → 验证 → [仍有问题] → 修复代码
                          ↑______________|

---

workflow-test-fix-cycle

一句话定位: 测试修复工作流

功能:

• 诊断测试失败原因
• 修复代码或测试
• 验证修复
• 循环直到通过

流程:

诊断失败 → 确定根因 → [代码问题] → 修复代码 → 验证
                          ↑___________|

相关命令

• Codex Skills - 生命周期
• Codex Skills - 专项
• Claude Skills - 工作流

最佳实践

1. 选择合适的工作流:

   • 协作分析 → analyze-with-file
   • 头脑风暴 → brainstorm-with-file
   • 调试 → debug-with-file
   • 规划 → collaborative-plan-with-file

2. 文档化讨论: 利用文档化讨论时间线，捕获理解演进

3. 决策记录: 在关键点记录决策，保留决策历史

4. 假设驱动调试: 使用假设驱动调试，系统化解决问题

5. 多视角分析: 利用多视角并行分析，获得全面理解

使用示例

# 协作分析
/analyze-with-file TOPIC="How to optimize database queries?"

# 深度分析
/analyze-with-file TOPIC="Architecture for microservices" --depth=deep

# 头脑风暴
/brainstorm-with-file TOPIC="Design payment system"

# 调试
/debug-with-file BUG="System crashes intermittently"

# 协作规划
/collaborative-plan-with-file "Add user notifications"

# 测试修复
/workflow-test-fix-cycle "Unit tests failing"