为什么需要 agentflow？

Claude Code 可以处理复杂任务，但更大的改动通常需要清晰的角色边界、验证门禁和评审门禁。

agentflow 会把这些边界显式化：

• Developer 负责实现。
• Tester 负责验证。
• Reviewer 负责批准。
• 失败检查会路由回正确角色。
• Blocked 角色会报告缺少什么，以及应该从哪里继续。

快速开始

需要支持 skill 的 Claude Code。agentflow 最适合在 git 仓库中使用，尤其是涉及代码修改或 Claude Code worktree isolation 的 workflow。非 git 项目也可以通过 Claude Code 的 WorktreeCreate / WorktreeRemove hooks 自定义隔离方式，但推荐路径仍然是 git。

安装 skill：

npx @leokon3/agentflow@latest install

选择 Claude Code，然后选择安装到当前项目或全局目录。

如果不能使用 npm，也可以在本仓库 checkout 中手动安装：

mkdir -p ~/.claude/skills
cp -R skills/agentflow ~/.claude/skills/

然后在任意项目中启动 Claude Code：

/agentflow list
/agentflow show feature
/agentflow run feature "add a settings page with save validation"
/agentflow run bugfix "fix login redirect after OAuth callback"
/agentflow run refactor "split the billing service without changing behavior"
/agentflow role reviewer "review the current diff"

任务字符串用来描述你想完成的结果。AgentFlow 会把这个任务传给每个角色，所以写得越具体越好。

运行自定义 workflow YAML 文件：

/agentflow validate ./skills/agentflow/examples/workflow-templates/strict-bugfix.yaml
/agentflow run ./skills/agentflow/examples/workflow-templates/strict-bugfix.yaml "fix login redirect bug"

或者把项目模板放到 .agentflow/templates/strict-bugfix.yaml，然后按名字运行：

/agentflow run strict-bugfix "fix login redirect bug"

内置 workflows

| 模板 | 流程 | 适合场景 | | ---------- | -------------------------------------------------------- | -------------------------------------- | | bugfix | Investigator → Developer → Tester → Reviewer | 诊断、修复、验证并 review 一个缺陷。 | | feature | Architect → Developer → Tester → Reviewer | 设计、实现、验证并 review 一个新行为。 | | refactor | Architect → Developer → Regression Tester → Reviewer | 调整结构，同时证明行为保持不变。 | | security | Developer → Security Reviewer → Tester → Senior Reviewer | 修改安全敏感代码，并进行额外 review。 | | quick | Developer → Tester | 完成一个小实现，并做聚焦验证。 |

命令

| 命令 | 作用 | | ----------------------------------------- | -------------------------- | | /agentflow list | 查看内置和项目 workflows。 | | /agentflow show <template> | 查看 workflow 细节。 | | /agentflow validate <template> | 校验 workflow 模板。 | | /agentflow role <role> "<task>" | 只运行一个内置角色。 | | /agentflow run <template> "<task>" | 按名称运行 workflow。 | | /agentflow run <template.yaml> "<task>" | 按路径运行 workflow 文件。 |

Single-role mode 适合单独做调查、设计、实现、测试或 review。它只返回该角色的 decision，不会把整个 workflow 标记为 passed，也不会绕过测试或 review gates。

可用的内置 role slugs：investigator、architect、developer、tester、regression-tester、reviewer、security-reviewer、senior-reviewer。v0.1 的 /agentflow role 不解析自定义或项目 role templates。

模板解析顺序：

1. 显式 YAML 路径会按原路径加载。
2. 项目模板从 .agentflow/templates/<name>.yaml 加载。
3. 内置模板从已安装 skill 的 templates/<name>.yaml 加载。

同名时，项目模板优先于内置模板。

.agentflow/templates/ 是项目里的 agentflow workflow 配置目录，适合提交到仓库共享；.claude/skills/agentflow/ 是 Claude Code skill 的安装目录，不建议放用户自定义模板。

Workflow 决策

每个角色都会返回用于路由的结构化 decision。

| 角色类型 | 决策 | | -------------------------- | ------------------------------------------ | | Developer | implemented, blocked | | Tester / Regression Tester | passed, failed, blocked | | Reviewer roles | approved, changes_requested, blocked |

failed 和 changes_requested 会路由到配置的 fail_to 角色。

blocked 会带着 resume point 停止，用户补充缺失信息后可以从 blocked 角色继续。

自定义 workflows

自定义 workflow 是 YAML 文件，包含 roles、routes、start role 和 rules。可以先复制 examples 里的模板，也可以在项目里创建 .agentflow/templates/<name>.yaml。

name: strict-bugfix

roles:
  developer:
    uses: builtin/developer
    can_edit: true
    can_run_commands: true
    pass_to: tester

  tester:
    uses: builtin/tester
    can_edit: true
    can_run_commands: true
    pass_to: reviewer
    fail_to: developer

  reviewer:
    uses: builtin/reviewer
    can_edit: false
    can_run_commands: true
    pass_to: done
    fail_to: developer

flow:
  start: developer

rules:
  max_loops: 2
  require_tests: true
  require_final_review: true

关键字段：

• uses：复用内置 role prompt，例如 builtin/developer、builtin/tester 或 builtin/reviewer。
• prompt：在内置 prompt 之上追加这个 role 的额外说明。
• can_edit：这个 workflow contract 是否允许该角色编辑文件。
• can_run_commands：这个 workflow contract 是否允许该角色运行 shell 命令。
• pass_to：角色成功后的下一个角色，或者用 done 结束。
• fail_to：角色失败或请求修改后的下一个角色。
• flow.start：第一个运行的角色。
• rules.max_loops：最多允许多少轮修复循环。
• rules.require_tests / rules.require_final_review：成功完成时必须经过的测试和 review gates。

可复用的项目模板可以保存到：

.agentflow/templates/<name>.yaml

然后校验并按名称运行：

/agentflow validate <name>
/agentflow run <name> "add export to CSV for the reports table"

更多 workflow 示例：

skills/agentflow/examples/workflow-templates/

can_edit 和 can_run_commands 这类角色权限是 prompt 层面的 workflow 约束。Claude Code 原本的工具确认和权限设置仍然生效。

自定义角色 prompts

使用 uses: builtin/<role> 可以复用内置角色 prompt。角色需要额外说明时，可以添加 prompt:。

docs-reviewer:
  title: Docs Reviewer
  uses: builtin/reviewer
  prompt: |
    Review only documentation changes.
    Check clarity, accuracy, broken links, and whether examples still match the workflow.
  can_edit: false
  can_run_commands: true
  pass_to: done
  fail_to: docs-writer

上面的 YAML 是在 workflow 里配置 role。可复用的 role template 本身是一个 Markdown prompt contract。如果不使用 uses、完全自定义 role prompt，请包含：

• 角色职责
• 允许的动作和限制
• decision vocabulary
• 必须输出的结构
• pass/fail/block 条件
• 交接目标

保持 role prompt 小而明确：workflow 应该清楚说明这个角色能做什么、如何判断、下一步交给谁。

一个最小 custom role prompt 可以这样写：

# Docs Reviewer

You are responsible for reviewing documentation changes for clarity and accuracy.

You must:
- Check changed docs, examples, command names, links, and terminology.
- Request changes when docs are misleading, incomplete, or unsupported.

You must not:
- Edit files unless the workflow role allows editing.
- Approve docs that contradict the current code or workflow.

Return:
- `Decision: approved | changes_requested | blocked`
- issues found
- required changes
- handoff target

角色 prompt 示例在：

skills/agentflow/examples/role-templates/

包含示例：

• product-reviewer.md
• api-reviewer.md
• docs-reviewer.md
• migration-reviewer.md

验证边界

Developer handoff 会说明哪些内容能在当前代码环境验证、哪些需要运行时或外部环境、哪些不属于本次改动范围。Tester 和 Regression Tester 会基于这些边界判断当前证据是否足够 pass、fail 或 block。

仓库结构

package.json                             # npx 安装用的 npm package 元数据
bin/agentflow.js                         # 交互式安装 CLI
skills/agentflow/                        # 可发布的 skill 源码
  SKILL.md                               # 命令行为和 workflow runner 规则
  templates/                             # 内置 workflow 模板
  roles/                                 # 内置角色 prompts
  examples/                              # 可复制的 workflow 和 role 示例