mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
c3ddf7e322
- 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
416 lines
17 KiB
Markdown
416 lines
17 KiB
Markdown
# Codex Skills - 生命周期类
|
||
|
||
## 一句话定位
|
||
|
||
**生命周期类 Codex Skills 是全生命周期编排系统** — 通过 team-lifecycle 和 parallel-dev-cycle 实现从规范到实现到测试到审查的完整开发流程自动化。
|
||
|
||
## vs 传统方法对比
|
||
|
||
| 维度 | 传统方式 | **Codex Skills** |
|
||
| --- | --- | --- |
|
||
| 流水线编排 | 手动任务管理 | 自动 spawn-wait-close 流水线 |
|
||
| 代理通信 | 直接通信 | 子代理内联调用 |
|
||
| 代码库探索 | 重复探索 | 共享缓存系统 |
|
||
| 协调开销 | 每步协调 | Fast-advance 线性跳过 |
|
||
|
||
## Skills 列表
|
||
|
||
| Skill | 功能 | 触发方式 |
|
||
| --- | --- | --- |
|
||
| `team-lifecycle` | 全生命周期编排器 | `/team-lifecycle <task>` |
|
||
| `parallel-dev-cycle` | 多代理并行开发循环 | `/parallel-dev-cycle TASK="..."` |
|
||
|
||
## Skills 详解
|
||
|
||
### team-lifecycle
|
||
|
||
**一句话定位**: 全生命周期编排器 — 规范/实现/测试的 spawn-wait-close 流水线
|
||
|
||
**架构概览**:
|
||
```
|
||
+-------------------------------------------------------------+
|
||
| Team Lifecycle Orchestrator |
|
||
| Phase 1 -> Phase 2 -> Phase 3 -> Phase 4 -> Phase 5 |
|
||
| Require Init Dispatch Coordinate Report |
|
||
+----------+------------------------------------------------+--+
|
||
|
|
||
+-----+------+----------+-----------+-----------+
|
||
v v v v v
|
||
+---------+ +---------+ +---------+ +---------+ +---------+
|
||
| Phase 1 | | Phase 2 | | Phase 3 | | Phase 4 | | Phase 5 |
|
||
| Require | | Init | | Dispatch| | Coord | | Report |
|
||
+---------+ +---------+ +---------+ +---------+ +---------+
|
||
| | | ||| |
|
||
params session tasks agents summary
|
||
/ | \
|
||
spawn wait close
|
||
/ | \
|
||
+------+ +-------+ +--------+
|
||
|agent1| |agent2 | |agent N |
|
||
+------+ +-------+ +--------+
|
||
| | |
|
||
(may call discuss/explore subagents internally)
|
||
```
|
||
|
||
**关键设计原则**:
|
||
|
||
1. **Inline discuss subagent**: 生产角色（analyst, writer, reviewer）内联调用 discuss 子代理，将规范流水线从 12 拍减少到 6 拍
|
||
2. **Shared explore cache**: 所有代理共享集中式 `explorations/` 目录，消除重复代码库探索
|
||
3. **Fast-advance spawning**: 代理完成后立即派生下一个线性后继者
|
||
4. **Consensus severity routing**: 讨论结果通过 HIGH/MEDIUM/LOW 严重程度路由
|
||
5. **Beat model**: 每个流水线步骤是一拍 — 派生代理、等待结果、处理输出、派生下一个
|
||
|
||
**代理注册表**:
|
||
| 代理 | 角色文件 | 职责 | 模式 |
|
||
|------|----------|------|------|
|
||
| analyst | ~/.codex/agents/analyst.md | 种子分析、上下文收集、DISCUSS-001 | 2.8 Inline Subagent |
|
||
| writer | ~/.codex/agents/writer.md | 文档生成、DISCUSS-002 到 DISCUSS-005 | 2.8 Inline Subagent |
|
||
| planner | ~/.codex/agents/planner.md | 多角度探索、计划生成 | 2.9 Cached Exploration |
|
||
| executor | ~/.codex/agents/executor.md | 代码实现 | 2.1 Standard |
|
||
| tester | ~/.codex/agents/tester.md | 测试修复循环 | 2.3 Deep Interaction |
|
||
| reviewer | ~/.codex/agents/reviewer.md | 代码审查 + 规范质量、DISCUSS-006 | 2.8 Inline Subagent |
|
||
| architect | ~/.codex/agents/architect.md | 架构咨询（按需） | 2.1 Standard |
|
||
| fe-developer | ~/.codex/agents/fe-developer.md | 前端实现 | 2.1 Standard |
|
||
| fe-qa | ~/.codex/agents/fe-qa.md | 前端 QA、GC 循环 | 2.3 Deep Interaction |
|
||
|
||
**子代理注册表**:
|
||
| 子代理 | 代理文件 | 可调用者 | 用途 |
|
||
|--------|----------|----------|------|
|
||
| discuss | ~/.codex/agents/discuss-agent.md | analyst, writer, reviewer | 通过 CLI 工具进行多视角批判 |
|
||
| explore | ~/.codex/agents/explore-agent.md | analyst, planner, 任意代理 | 带共享缓存的代码库探索 |
|
||
|
||
**流水线定义**:
|
||
```
|
||
Spec-only (6 beats):
|
||
RESEARCH-001(+D1) → DRAFT-001(+D2) → DRAFT-002(+D3) → DRAFT-003(+D4) → DRAFT-004(+D5) → QUALITY-001(+D6)
|
||
|
||
Impl-only (3 beats):
|
||
PLAN-001 → IMPL-001 → TEST-001 || REVIEW-001
|
||
|
||
Full-lifecycle (9 beats):
|
||
[Spec pipeline] → PLAN-001 → IMPL-001 → TEST-001 || REVIEW-001
|
||
```
|
||
|
||
**Beat Cycle**:
|
||
```
|
||
event (phase advance / user resume)
|
||
↓
|
||
[Orchestrator]
|
||
+-- read state file
|
||
+-- find ready tasks
|
||
+-- spawn agent(s)
|
||
+-- wait(agent_ids, timeout)
|
||
+-- process results (consensus routing, artifacts)
|
||
+-- update state file
|
||
+-- close completed agents
|
||
+-- fast-advance: immediately spawn next if linear successor
|
||
+-- yield (wait for next event or user command)
|
||
```
|
||
|
||
**Fast-Advance 决策表**:
|
||
| 条件 | 动作 |
|
||
|------|------|
|
||
| 1 个就绪任务、简单线性后继、无检查点 | 立即 `spawn_agent` 下一个任务（fast-advance） |
|
||
| 多个就绪任务（并行窗口） | 批量派生所有就绪任务，然后 `wait` 所有 |
|
||
| 无就绪任务、其他代理正在运行 | Yield，等待这些代理完成 |
|
||
| 无就绪任务、无运行中 | 流水线完成，进入 Phase 5 |
|
||
| 检查点任务完成（如 QUALITY-001） | 暂停，输出检查点消息，等待用户 |
|
||
|
||
**共识严重程度路由**:
|
||
| 判定 | 严重程度 | 编排器动作 |
|
||
|------|----------|-----------|
|
||
| consensus_reached | - | 正常进行，fast-advance 到下一个任务 |
|
||
| consensus_blocked | LOW | 带 notes 视为 reached，正常进行 |
|
||
| consensus_blocked | MEDIUM | 记录警告到 `wisdom/issues.md`，在下个任务上下文中包含分歧，继续 |
|
||
| consensus_blocked | HIGH | 创建修订任务 或暂停等待用户 |
|
||
| consensus_blocked | HIGH (DISCUSS-006) | 始终暂停等待用户决策（最终签署门） |
|
||
|
||
**修订任务创建** (HIGH 严重程度，非 DISCUSS-006):
|
||
```javascript
|
||
const revisionTask = {
|
||
id: "<original-task-id>-R1",
|
||
owner: "<same-agent-role>",
|
||
blocked_by: [],
|
||
description: "Revision of <original-task-id>: address consensus-blocked divergences.\n"
|
||
+ "Session: <session-dir>\n"
|
||
+ "Original artifact: <artifact-path>\n"
|
||
+ "Divergences: <divergence-details>\n"
|
||
+ "Action items: <action-items-from-discuss>\n"
|
||
+ "InlineDiscuss: <same-round-id>",
|
||
status: "pending",
|
||
is_revision: true
|
||
}
|
||
```
|
||
|
||
**会话目录结构**:
|
||
```
|
||
.workflow/.team/TLS-<slug>-<date>/
|
||
├── team-session.json # 流水线状态（替换 TaskCreate/TaskList）
|
||
├── spec/ # 规范产物
|
||
│ ├── spec-config.json
|
||
│ ├── discovery-context.json
|
||
│ ├── product-brief.md
|
||
│ ├── requirements/
|
||
│ ├── architecture/
|
||
│ ├── epics/
|
||
│ ├── readiness-report.md
|
||
│ └── spec-summary.md
|
||
├── discussions/ # 讨论记录（由 discuss 子代理写入）
|
||
├── plan/ # 计划产物
|
||
│ ├── plan.json
|
||
│ └── tasks/ # 详细任务规范
|
||
├── explorations/ # 共享探索缓存
|
||
│ ├── cache-index.json # { angle -> file_path }
|
||
│ └── explore-<angle>.json
|
||
├── architecture/ # 架构师评估 + design-tokens.json
|
||
├── analysis/ # 分析师 design-intelligence.json（UI 模式）
|
||
├── qa/ # QA 审计报告
|
||
├── wisdom/ # 跨任务知识积累
|
||
│ ├── learnings.md # 模式和洞察
|
||
│ ├── decisions.md # 架构和设计决策
|
||
│ ├── conventions.md # 代码库约定
|
||
│ └── issues.md # 已知风险和问题
|
||
└── shared-memory.json # 跨代理状态
|
||
```
|
||
|
||
**状态文件模式** (team-session.json):
|
||
```json
|
||
{
|
||
"session_id": "TLS-<slug>-<date>",
|
||
"mode": "<spec-only | impl-only | full-lifecycle | fe-only | fullstack | full-lifecycle-fe>",
|
||
"scope": "<project description>",
|
||
"status": "<active | paused | completed>",
|
||
"started_at": "<ISO8601>",
|
||
"updated_at": "<ISO8601>",
|
||
"tasks_total": 0,
|
||
"tasks_completed": 0,
|
||
"pipeline": [
|
||
{
|
||
"id": "RESEARCH-001",
|
||
"owner": "analyst",
|
||
"status": "pending | in_progress | completed | failed",
|
||
"blocked_by": [],
|
||
"description": "...",
|
||
"inline_discuss": "DISCUSS-001",
|
||
"agent_id": null,
|
||
"artifact_path": null,
|
||
"discuss_verdict": null,
|
||
"discuss_severity": null,
|
||
"started_at": null,
|
||
"completed_at": null,
|
||
"revision_of": null,
|
||
"revision_count": 0
|
||
}
|
||
],
|
||
"active_agents": [],
|
||
"completed_tasks": [],
|
||
"revision_chains": {},
|
||
"wisdom_entries": [],
|
||
"checkpoints_hit": [],
|
||
"gc_loop_count": 0
|
||
}
|
||
```
|
||
|
||
**用户命令**:
|
||
| 命令 | 动作 |
|
||
|------|------|
|
||
| `check` / `status` | 输出执行状态图（只读，无推进） |
|
||
| `resume` / `continue` | 检查代理状态，推进流水线 |
|
||
| 新会话请求 | Phase 0 检测，进入正常 Phase 1-5 流程 |
|
||
|
||
**状态图输出格式**:
|
||
```
|
||
[orchestrator] Pipeline Status
|
||
[orchestrator] Mode: <mode> | Progress: <completed>/<total> (<percent>%)
|
||
|
||
[orchestrator] Execution Graph:
|
||
Spec Phase:
|
||
[V RESEARCH-001(+D1)] -> [V DRAFT-001(+D2)] -> [>>> DRAFT-002(+D3)]
|
||
-> [o DRAFT-003(+D4)] -> [o DRAFT-004(+D5)] -> [o QUALITY-001(+D6)]
|
||
|
||
V=completed >>>=running o=pending .=not created
|
||
|
||
[orchestrator] Active Agents:
|
||
> <task-id> (<agent-role>) - running <elapsed>
|
||
|
||
[orchestrator] Commands: 'resume' to advance | 'check' to refresh
|
||
```
|
||
|
||
---
|
||
|
||
### parallel-dev-cycle
|
||
|
||
**一句话定位**: 多代理并行开发循环 — 需求分析、探索规划、代码开发、验证
|
||
|
||
**架构概览**:
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ User Input (Task) │
|
||
└────────────────────────────┬────────────────────────────────┘
|
||
│
|
||
v
|
||
┌──────────────────────────────┐
|
||
│ Main Flow (Inline Orchestration) │
|
||
│ Phase 1 → 2 → 3 → 4 │
|
||
└──────────────────────────────┘
|
||
│
|
||
┌────────────────────┼────────────────────┐
|
||
│ │ │
|
||
v v v
|
||
┌────────┐ ┌────────┐ ┌────────┐
|
||
│ RA │ │ EP │ │ CD │
|
||
│Agent │ │Agent │ │Agent │
|
||
└────────┘ └────────┘ └────────┘
|
||
│ │ │
|
||
└────────────────────┼────────────────────┘
|
||
│
|
||
v
|
||
┌────────┐
|
||
│ VAS │
|
||
│ Agent │
|
||
└────────┘
|
||
│
|
||
v
|
||
┌──────────────────────────────┐
|
||
│ Summary Report │
|
||
│ & Markdown Docs │
|
||
└──────────────────────────────┘
|
||
```
|
||
|
||
**关键设计原则**:
|
||
|
||
1. **主文档 + 辅助日志**: 每个代理维护一个主文档（每次迭代完全重写）和辅助日志（追加）
|
||
2. **基于版本的覆盖**: 主文档每次迭代完全重写；日志仅追加
|
||
3. **自动归档**: 旧主文档版本自动归档到 `history/` 目录
|
||
4. **完整审计跟踪**: Changes.log (NDJSON) 保留所有更改历史
|
||
5. **并行协调**: 四个代理同时启动；通过共享状态和内联主流程协调
|
||
6. **文件引用**: 使用短文件路径而非内容传递
|
||
7. **自我增强**: RA 代理基于上下文主动扩展需求
|
||
8. **共享发现板**: 所有代理通过 `discoveries.ndjson` 共享探索发现
|
||
|
||
**工作者**:
|
||
| 工作者 | 主文档（每次迭代重写） | 追加日志 |
|
||
|--------|------------------------|----------|
|
||
| **RA** | requirements.md | changes.log |
|
||
| **EP** | exploration.md, architecture.md, plan.json | changes.log |
|
||
| **CD** | implementation.md, issues.md | changes.log, debug-log.ndjson |
|
||
| **VAS** | summary.md, test-results.json | changes.log |
|
||
|
||
**共享发现板**:
|
||
- 所有代理共享实时发现板 `coordination/discoveries.ndjson`
|
||
- 代理在开始时读取，工作时追加发现
|
||
- 消除冗余代码库探索
|
||
|
||
**发现类型**:
|
||
| 类型 | 去重键 | 写入者 | 读取者 |
|
||
|------|--------|--------|--------|
|
||
| `tech_stack` | singleton | RA | EP, CD, VAS |
|
||
| `project_config` | `data.path` | RA | EP, CD |
|
||
| `existing_feature` | `data.name` | RA, EP | CD |
|
||
| `architecture` | singleton | EP | CD, VAS |
|
||
| `code_pattern` | `data.name` | EP, CD | CD, VAS |
|
||
| `integration_point` | `data.file` | EP | CD |
|
||
| `test_command` | singleton | CD, VAS | VAS, CD |
|
||
| `blocker` | `data.issue` | 任意 | 全部 |
|
||
|
||
**执行流程**:
|
||
```
|
||
Phase 1: 会话初始化
|
||
├─ 创建新循环 OR 恢复现有循环
|
||
├─ 初始化状态文件和目录结构
|
||
└─ 输出: cycleId, state, progressDir
|
||
|
||
Phase 2: 代理执行（并行）
|
||
├─ 附加任务: 派生 RA → 派生 EP → 派生 CD → 派生 VAS → 等待所有
|
||
├─ 并行派生 RA, EP, CD, VAS 代理
|
||
├─ 等待所有代理完成（带超时处理）
|
||
└─ 输出: agentOutputs (4 个代理结果)
|
||
|
||
Phase 3: 结果聚合 & 迭代
|
||
├─ 从每个代理解析 PHASE_RESULT
|
||
├─ 检测问题（测试失败、阻塞）
|
||
├─ 决策: 发现问题 AND 迭代 < 最大值？
|
||
│ ├─ 是 → 通过 send_input 发送反馈，循环回 Phase 2
|
||
│ └─ 否 → 进入 Phase 4
|
||
└─ 输出: parsedResults, 迭代状态
|
||
|
||
Phase 4: 完成和摘要
|
||
├─ 生成统一摘要报告
|
||
├─ 更新最终状态
|
||
├─ 关闭所有代理
|
||
└─ 输出: 最终循环报告和继续说明
|
||
```
|
||
|
||
**会话结构**:
|
||
```
|
||
{projectRoot}/.workflow/.cycle/
|
||
├── {cycleId}.json # 主状态文件
|
||
├── {cycleId}.progress/
|
||
│ ├── ra/ # RA 代理产物
|
||
│ │ ├── requirements.md # 当前版本（完全重写）
|
||
│ │ ├── changes.log # NDJSON 完整历史（追加）
|
||
│ │ └── history/ # 归档快照
|
||
│ ├── ep/ # EP 代理产物
|
||
│ │ ├── exploration.md # 代码库探索报告
|
||
│ │ ├── architecture.md # 架构设计
|
||
│ │ ├── plan.json # 结构化任务列表（当前版本）
|
||
│ │ ├── changes.log # NDJSON 完整历史
|
||
│ │ └── history/
|
||
│ ├── cd/ # CD 代理产物
|
||
│ │ ├── implementation.md # 当前版本
|
||
│ │ ├── debug-log.ndjson # 调试假设跟踪
|
||
│ │ ├── changes.log # NDJSON 完整历史
|
||
│ │ └── history/
|
||
│ ├── vas/ # VAS 代理产物
|
||
│ │ ├── summary.md # 当前版本
|
||
│ │ ├── changes.log # NDJSON 完整历史
|
||
│ │ └── history/
|
||
│ └── coordination/ # 协调数据
|
||
│ ├── discoveries.ndjson # 共享发现板（所有代理追加）
|
||
│ ├── timeline.md # 执行时间线
|
||
│ └── decisions.log # 决策日志
|
||
```
|
||
|
||
**版本控制**:
|
||
- 1.0.0: 初始循环 → 1.x.0: 每次迭代（次要版本递增）
|
||
- 每次迭代: 归档旧版本 → 完全重写 → 追加 changes.log
|
||
|
||
## 相关命令
|
||
|
||
- [Codex Skills - 工作流](./codex-workflow.md)
|
||
- [Codex Skills - 专项](./codex-specialized.md)
|
||
- [Claude Skills - 团队协作](./claude-collaboration.md)
|
||
|
||
## 最佳实践
|
||
|
||
1. **选择合适的团队类型**:
|
||
- 完整功能开发 → `team-lifecycle`
|
||
- 并行开发循环 → `parallel-dev-cycle`
|
||
|
||
2. **利用 Inline Discuss**: 生产角色内联调用 discuss 子代理，减少编排开销
|
||
|
||
3. **共享缓存**: 利用共享探索缓存，避免重复代码库探索
|
||
|
||
4. **Fast-Advance**: 线性后继任务自动跳过编排器，提高效率
|
||
|
||
5. **共识路由**: 理解不同严重程度的共识路由行为
|
||
|
||
## 使用示例
|
||
|
||
```bash
|
||
# 全生命周期开发
|
||
/team-lifecycle "Build user authentication API"
|
||
|
||
# 规范流水线
|
||
/team-lifecycle --mode=spec-only "Design payment system"
|
||
|
||
# 并行开发
|
||
/parallel-dev-cycle TASK="Implement notifications"
|
||
|
||
# 继续循环
|
||
/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123
|
||
|
||
# 自动模式
|
||
/parallel-dev-cycle --auto TASK="Add OAuth"
|
||
```
|