Agent Workflow Setup：多智能体协作开发工作流的最佳实践

Agent Workflow Setup是一个可移植的多智能体开发工作流框架，支持Codex和Claude Code双引擎，通过定义标准化角色、共享记忆和严格的质量门禁，实现AI辅助软件开发的标准化和可控化。

• 原作者/维护者: Niko4417
• 来源平台: GitHub
• 原始标题: Agent-Workflow-Setup
• 原始链接: https://github.com/Niko4417/Agent-Workflow-Setup
• 发布时间: 2026年6月14日

随着GitHub Copilot、Claude Code、Codex等AI编程助手的普及，开发者开始探索如何让AI更深入地参与软件开发流程。然而，在实际应用中面临诸多挑战：

1. 缺乏标准化：不同开发者使用AI的方式各异，难以保证输出质量的一致性
2. 上下文管理困难：AI助手难以在多次会话间保持上下文连续性
3. 质量门禁缺失：AI生成的代码缺乏系统性的审查机制
4. 多智能体协调复杂：当多个AI角色协作时，任务分配和沟通变得混乱

Agent Workflow Setup正是为解决这些问题而设计的系统化方案。

Agent Workflow Setup是一个可移植的多智能体开发工作流框架，专为Keiko代码库设计（但可适配其他项目）。它支持双引擎架构：

• 主引擎: GitHub Copilot + Codex
• 备用引擎: Claude Code

通过符号链接（symlink）安装到目标代码库，保持目标仓库的git历史干净，同时实现工作流的版本控制和团队协作。

1. 单一协调者（Orchestrator）：人类只与一个主导智能体交互，由它负责规划、委派和报告
2. 标准化角色：16个预定义的规范角色，根据任务规模灵活组合
3. 神圣的主分支（dev）：所有issue都以PR形式提交，只有issue合并到epic分支是自动的，合并到dev需要人工审查
4. 分层质量门禁：从本地钩子到审计门的多层防护

docs/                    # 文档
  workflow-contract.md   # 工作流契约（规则）
  workflow-blueprint.md  # 架构设计文档
  example-workflow.md    # 示例工作流

.agents/                 # 智能体配置
  roles.yaml             # 角色定义
  aliases.yaml           # 别名配置
  memory/<role>/         # 各角色的共享记忆

codex/                   # Codex引擎配置（主引擎）
  config.toml            # 主配置
  RUNBOOK.md             # 运行手册
  agents/*.toml          # 智能体配置
  playbooks/             # 剧本
  hooks/                 # Git钩子

claude/                  # Claude引擎配置（备用）
  settings.json          # 设置
  agents/*.md            # 智能体定义
  teams/                 # 团队配置
  skills/<name>/SKILL.md # 技能定义

scripts/                 # 工具脚本
  install.sh             # 安装脚本
  verify.sh              # 本地CI镜像
  keiko-watch            # 实时监控
  consolidate-memory     # 记忆预算检查

templates/               # 模板
  target-side gate snippets  # husky / lint-staged / PR证据模板

角色（Roles）

工作流定义了16个规范角色，存储在 .agents/roles.yaml 中。角色根据任务规模灵活组合：

• 小型任务：单个角色独立完成
• 中型任务：3-5个角色协作
• 史诗级任务（Epic）：完整角色集群

两个引擎共享相同的角色词汇和记忆树，确保切换引擎时上下文不丢失。

记忆管理（Memory）

• 学习成果保存在 .agents/memory/<role>/ 中
• 记忆预算限制：每个角色 < 25 KB
• 定期运行 consolidate-memory 脚本检查预算

技能（Skills）

技能定义在 claude/skills/<name>/SKILL.md，同时镜像到 ~/.codex/skills/，使Codex和Claude都能使用。

每个issue都通过以下流程完成：

issue创建 → 智能体分析 → 代码实现 → 自评（2轮） → verify.sh → keiko-issue-audit → PR创建 → CI检查 → 人工审查 → 合并