mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
docs: add VitePress documentation site
- Add docs directory with VitePress configuration - Add GitHub Actions workflow for docs build and deploy - Support bilingual (English/Chinese) documentation - Include search, custom theme, and responsive design
This commit is contained in:
catlog22
366
docs/zh/skills/codex-workflow.md
Normal file
366
docs/zh/skills/codex-workflow.md
Normal file
@@ -0,0 +1,366 @@
|
||||
# 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 日志格式**:
|
||||
```json
|
||||
{"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 模板**:
|
||||
```markdown
|
||||
# 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-lifecycle.md)
|
||||
- [Codex Skills - 专项](./codex-specialized.md)
|
||||
- [Claude Skills - 工作流](./claude-workflow.md)
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **选择合适的工作流**:
|
||||
- 协作分析 → `analyze-with-file`
|
||||
- 头脑风暴 → `brainstorm-with-file`
|
||||
- 调试 → `debug-with-file`
|
||||
- 规划 → `collaborative-plan-with-file`
|
||||
|
||||
2. **文档化讨论**: 利用文档化讨论时间线，捕获理解演进
|
||||
|
||||
3. **决策记录**: 在关键点记录决策，保留决策历史
|
||||
|
||||
4. **假设驱动调试**: 使用假设驱动调试，系统化解决问题
|
||||
|
||||
5. **多视角分析**: 利用多视角并行分析，获得全面理解
|
||||
|
||||
## 使用示例
|
||||
|
||||
```bash
|
||||
# 协作分析
|
||||
/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"
|
||||
```
|
||||
Reference in New Issue
Block a user