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
17 KiB
17 KiB
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)
关键设计原则:
- Inline discuss subagent: 生产角色（analyst, writer, reviewer）内联调用 discuss 子代理，将规范流水线从 12 拍减少到 6 拍
- Shared explore cache: 所有代理共享集中式
explorations/目录，消除重复代码库探索 - Fast-advance spawning: 代理完成后立即派生下一个线性后继者
- Consensus severity routing: 讨论结果通过 HIGH/MEDIUM/LOW 严重程度路由
- 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):
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):
{
"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 │
└──────────────────────────────┘
关键设计原则:
- 主文档 + 辅助日志: 每个代理维护一个主文档（每次迭代完全重写）和辅助日志（追加）
- 基于版本的覆盖: 主文档每次迭代完全重写；日志仅追加
- 自动归档: 旧主文档版本自动归档到
history/目录 - 完整审计跟踪: Changes.log (NDJSON) 保留所有更改历史
- 并行协调: 四个代理同时启动；通过共享状态和内联主流程协调
- 文件引用: 使用短文件路径而非内容传递
- 自我增强: RA 代理基于上下文主动扩展需求
- 共享发现板: 所有代理通过
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
相关命令
最佳实践
-
选择合适的团队类型:
- 完整功能开发 →
team-lifecycle - 并行开发循环 →
parallel-dev-cycle
- 完整功能开发 →
-
利用 Inline Discuss: 生产角色内联调用 discuss 子代理，减少编排开销
-
共享缓存: 利用共享探索缓存，避免重复代码库探索
-
Fast-Advance: 线性后继任务自动跳过编排器，提高效率
-
共识路由: 理解不同严重程度的共识路由行为
使用示例
# 全生命周期开发
/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"