第 14 期 | 工作流自动化：Workflow 定义与 Skill 流水线

14.1 Workflow 工作流定义

Workflows 定义在 .agents/workflows/ 目录中，是 Skill 流水线的具体步骤描述。每个 workflow 文件是一个 markdown 文档，按阶段列出 agent 应遵循的操作序列。

14.1.1 Workflow 目录结构

.agents/workflows/
├── feature-development.md   # 新功能开发（8 阶段，27 步）
├── bug-fix.md               # Bug 修复（4 阶段，13 步）
├── plan-and-research.md     # 规划与调研（4 阶段，13 步）
└── session-archive.md       # 会话归档（3 阶段，10 步）

14.1.2 Workflow 加载机制

Agent 执行 Skill（如 /planning-with-files）
  → Skill 读取 .agents/workflows/ 下对应的 workflow 文件
  → 将 workflow 步骤注入到 agent 上下文中
  → Agent 按步骤执行

Workflow 文件不是自动加载的——它们通过 Skill 调用链间接使用。Agent 需要调用对应 Skill 才会读取 workflow 内容。

14.1.3 功能开发工作流（feature-development.md）

这是最完整的 workflow，覆盖从规划到归档的全过程：

flowchart TD
    S1["阶段 1: 规划
planning-with-files"] --> S2["阶段 2: 设计
brainstorming → writing-plans"]
    S2 --> S3["阶段 3: 准备执行
plan 写入 task_plan.md"]
    S3 --> S4["阶段 4: TDD 执行
test-driven-development"]
    S4 --> S5{"测试通过?"}
    S5 -->|No| S6["阶段 5: 调试
systematic-debugging"]
    S6 --> S4
    S5 -->|Yes| S7["阶段 6: 验证
verification-before-completion"]
    S7 --> S8["阶段 7: 审查
requesting-code-review"]
    S8 --> S9["阶段 8: 归档
更新所有 plan 文件"]

    style S4 fill:#c8e6c9
    style S6 fill:#ffcdd2
    style S7 fill:#bbdefb

27 步详解：

14.1.4 Bug 修复工作流（bug-fix.md）

# Bug 修复工作流

## 阶段 1：诊断
1. 使用 planning-with-files
2. 恢复 task_plan.md、findings.md、progress.md、bugs.md
3. 使用 systematic-debugging
4. 在 bugs.md 中记录症状、可能根因和复现路径

## 阶段 2：复现与修复
5. 使用 test-driven-development
6. 先创建或运行一个失败的复现检查
7. 实现最小修复

## 阶段 3：回归验证
8. 重新运行目标检查
9. 运行相关回归检查
10. 使用 verification-before-completion

## 阶段 4：归档
11. 在 bugs.md 中更新修复和时间戳
12. 在 progress.md 中更新修复摘要
13. 在 task_plan.md 中更新相关任务状态

14.1.5 规划与调研工作流（plan-and-research.md）

# 规划与调研工作流

## 阶段 1：计划文件
1. 使用 planning-with-files
2. 恢复或创建根目录计划文件
3. 在 task_plan.md 中记录当前问题定义

## 阶段 2：发现
4. 阅读 requirement.md
5. 探索本地文件、参考材料和当前约束
6. 在 findings.md 中记录发现、风险与开放问题

## 阶段 3：设计
7. 使用 brainstorming
8. 明确范围、权衡、成功标准和接口边界
9. 产出设计 spec

## 阶段 4：实施计划
10. 使用 writing-plans
11. 将 spec 转为分阶段实现计划
12. 使用 planning-with-files 写入 task_plan.md
13. 在 progress.md 中记录下一步动作

14.1.6 会话归档工作流（session-archive.md）

# 会话归档工作流

## 阶段 1：文档归档
1. 检查 task_plan.md：已完成 [x]、进行中 [/]、阻塞 [!]
2. 更新 progress.md：追加本次会话摘要
3. 如有新发现更新 findings.md
4. 如有新失败更新 bugs.md

## 阶段 2：验证
5. 确认最新验证证据已写入 progress.md
6. 确认下一活动阶段在 task_plan.md 中可见
7. 确认未解决风险对下一次会话可见

## 阶段 3：交接
8. 总结本轮完成了什么
9. 总结还剩下什么
10. 如需最终集成，按 CLAUDE.md 中 Git 规则处理

14.1.7 如何创建自定义 Workflow

# 1. 创建目录
mkdir -p .agents/workflows

# 2. 创建 workflow 文件
cat > .agents/workflows/feature-development.md << 'EOF'
# 功能开发工作流

## 阶段 1：规划
1. 使用 planning-with-files
2. 恢复或创建计划文件
...

## 阶段 2：设计
...
EOF

# 3. 在 CLAUDE.md 中引用
echo "## Skill 使用规则" >> CLAUDE.md
echo "功能开发使用 feature-development workflow" >> CLAUDE.md

Workflow 设计原则：

1. 每步一个明确动作 — "使用 X skill" 或 "更新 Y 文件"
2. 有明确的产出 — 每个阶段结束时有可验证的输出
3. 步骤编号 — 方便 agent 跟踪进度
4. 引用 Skill 名 — agent 知道何时调用哪个 Skill
5. 引用文件名 — 明确写入哪个文件

14.2 Skill 流水线

Skill 是 Claude Code 的可复用指令模板。每个 Skill 定义一个特定的工作方法（如 TDD、调试、规划），通过 /skill-name 调用。

14.2.1 本项目使用的 Skill 全景

flowchart LR
    subgraph "规划阶段"
        PWF[planning-with-files]
        BS[brainstorming]
        WP[writing-plans]
    end
    
    subgraph "执行阶段"
        TDD[test-driven-development]
        SD[systematic-debugging]
    end
    
    subgraph "交付阶段"
        VBC[verification-before-completion]
        RCR[requesting-code-review]
        FDB[finishing-a-development-branch]
    end
    
    subgraph "并行/委派"
        DPA[dispatching-parallel-agents]
        SDD[subagent-driven-development]
        EP[executing-plans]
    end
    
    subgraph "Plugin Skill"
        MS[mem-search]
        KA[knowledge-agent]
        SE[smart-explore]
        CV[caveman]
    end
    
    PWF --> BS --> WP --> TDD --> SD --> VBC --> RCR --> FDB
    
    style PWF fill:#e1f5fe
    style TDD fill:#c8e6c9
    style VBC fill:#fff9c4
    style MS fill:#f3e5f5

14.2.2 核心 Skill 详解

14.2.3 Skill 的分类来源

Skill 来源：
├── User Skills（~/.claude/skills/）
│   ├── planning-with-files
│   ├── brainstorming
│   ├── writing-plans
│   ├── test-driven-development
│   ├── systematic-debugging
│   ├── verification-before-completion
│   ├── requesting-code-review
│   ├── dispatching-parallel-agents
│   ├── subagent-driven-development
│   ├── executing-plans
│   └── finishing-a-development-branch
│
└── Plugin Skills
    ├── caveman（caveman plugin）
    │   ├── /caveman
    │   ├── /caveman-commit
    │   └── /caveman-review
    └── claude-mem（claude-mem plugin）
        ├── /mem-search
        ├── /knowledge-agent
        └── /smart-explore

14.2.4 Skill 在 Teams 模式下的限制

flowchart TD
    TL["team-lead 会话"] -->|"✅ 可调用所有 Skill"| SK["Skill 执行"]
    AG["子 Agent
(ui-dev / logic-dev / qa)"] -->|"❌ 建议不调用"| X["权限弹窗 → Agent 停止"]
    
    TL -->|"替代方案"| P["在 prompt 中
内联 Skill 的规则"]
    P --> AG2["Agent 直接按规则工作
不调用 Skill 工具"]
    
    style X fill:#ffcdd2
    style P fill:#c8e6c9
    style AG2 fill:#c8e6c9

为什么子 Agent 不应调用 Skill：

1. Skill 是工具调用 — 需要在 settings.json allow 列表中
2. Skill 内部有嵌套操作 — bypassPermissions 不覆盖嵌套层
3. Skill 执行消耗上下文 — 子 agent 的 200k token 窗口会被 Skill 输出占满
4. 不必要 — 规划工作在 team-lead 完成，子 agent 只需执行

替代方案：把 Skill 规则内联到 Agent prompt

Agent({
  name: "logic-dev",
  prompt: `你是 logic-dev。

// 直接把 TDD 规则写在 prompt 里，替代 /test-driven-development Skill
// 替代 /systematic-debugging Skill
工作规则：
1. 先写失败测试（RED）
2. 实现最小通过代码（GREEN）
3. 重构（REFACTOR）
4. 测试失败时：诊断→修复→重跑，不盲目重试
5. 最多 5 次自修复，超过后停止

...`
})

14.2.5 Skill 与 Workflow 的关系

Skill（工具）    →    Workflow（步骤指南）    →    文件（状态持久化）

/brainstorming         feature-development.md       findings.md
/planning-with-files   的第 6-8 步                  task_plan.md
                                                  progress.md

• Skill 是可调用的工具（/skill-name），定义做什么
• Workflow 是步骤指南（.agents/workflows/*.md），定义按什么顺序做
• CLAUDE.md 是项目宪法，定义规则和边界
• 规划文件（task_plan.md 等）是持久化状态

14.2.6 在 CLAUDE.md 中引用 Skill 和 Workflow

CLAUDE.md 中的 Skill 使用规则 章节告诉 agent：

1. 哪些 Skill 必须用（planning-with-files 开始复杂任务）
2. 按什么顺序用（流水线：brainstorming → writing-plans → TDD → verification）
3. 哪些不能跳（设计不跳 brainstorming，完成不跳 verification）
4. 失败时用什么（测试失败用 systematic-debugging，不随意重试）

这套规则确保了即使在 Teams 并行开发中，每个 agent 都遵循统一的工作方法论。