ruflo agent-repo-architect 技能解析：用 Swarm 协调与 GitHub MCP 工具实现仓库结构分析与多仓架构治理

本文以 ruflo 仓库中的 agent-repo-architect 技能定义 为主体，完整讲解这一"仓库架构师"（GitHub Repository Architect）Agent 技能的元数据规范、生命周期 Hooks、三大核心使用模式（结构分析、模板创建、跨仓同步）、批量架构操作编排，以及 Monorepo / 命令结构 / 集成三类架构模式。读完本文，你将掌握如何基于 Claude Flow 的 swarm MCP 工具（swarm_init、agent_spawn、task_orchestrate、memory_usage）与 GitHub MCP 工具，为一组关联仓库建立统一的架构治理与标准化流程，并能对照 ruflo 仓库的真实目录结构理解这些模式如何落地。

技能定位：面向仓库架构治理的 Agent Skill

SKILL.md 定义的核心目标是"仓库结构优化与多仓库管理"（repository structure optimization and multi-repo management），并借助 ruv-swarm 协调机制支撑可扩展的项目架构与开发工作流。该技能声明了五项能力：

• 仓库结构优化：基于最佳实践对目录、配置与文档布局进行优化；
• 多仓库协调与同步：跨关联仓库保持结构一致；
• 模板管理：为一致的项目初始化提供可复用模板；
• 架构分析与改进建议：产出可落地的优化建议；
• 跨仓工作流协调：管理横跨多个仓库的任务流。

值得注意的是，同一能力在仓库中存在两份镜像定义：一份位于 Codex CLI 技能目录 .agents/skills/agent-repo-architect/SKILL.md，另一份位于 Claude Code 命令目录 repo-architect.md。两者正文几乎逐行一致，差异仅在封装层——前者带双层 YAML frontmatter（外层是 agent-repo-architect 技能包装，内层是 repo-architect 角色定义），后者是纯命令文档。这说明 ruflo 采用"一份技能内容、两个宿主入口"的复用策略：OpenAI Codex CLI 通过 .agents 目录 的 $skill-name 语法调用，Claude Code 则通过命令文件加载。

元数据规范：frontmatter 中声明工具与 Hooks

技能文件内层的 frontmatter 是整个技能的"契约"，关键字段如下：

name: repo-architect
description: Repository structure optimization and multi-repo management
  with ruv-swarm coordination for scalable project architecture and development workflows
type: architecture
color: "#9B59B6"
tools:
  - Bash
  - Read
  - Write
  - Edit
  - LS
  - Glob
  - TodoWrite
  - TodoRead
  - Task
  - WebFetch
  - mcp__github__create_repository
  - mcp__github__fork_repository
  - mcp__github__search_repositories
  - mcp__github__push_files
  - mcp__github__create_or_update_file
  - mcp__claude-flow__swarm_init
  - mcp__claude-flow__agent_spawn
  - mcp__claude-flow__task_orchestrate
  - mcp__claude-flow__memory_usage
hooks:
  pre_task: |
    echo "🏗️ Initializing repository architecture analysis..."
    npx ruv-swarm hook pre-task --mode repo-architect --analyze-structure
  post_edit: |
    echo "📐 Validating architecture changes and updating structure documentation..."
    npx ruv-swarm hook post-edit --mode repo-architect --validate-structure
  post_task: |
    echo "🏛️ Architecture task completed. Generating structure recommendations..."
    npx ruv-swarm hook post-task --mode repo-architect --generate-recommendations
  notification: |
    echo "📋 Notifying stakeholders of architecture improvements..."
    npx ruv-swarm hook notification --mode repo-architect

从工具清单可以看出该技能的执行边界分三层：

1. 本地文件系统工具（Bash、Read、Write、Edit、LS、Glob）：直接操作工作区中的仓库文件，是结构分析与修改的执行层；
2. GitHub MCP 工具（mcp__github__* 五个工具）：负责远端仓库的创建、搜索、fork 与文件推送，让技能可以直接产出远端仓库变更；
3. Claude Flow swarm MCP 工具（mcp__claude-flow__* 四个工具）：负责多智能体编队初始化、个体代理生成、任务编排与持久化记忆写入，是"swarm 协调"的底座。

Hooks 定义了四个生命周期挂点：pre_task 在进入任务时触发结构分析（--analyze-structure）；post_edit 在每次编辑后做架构校验并更新结构文档（--validate-structure）；post_task 在任务结束时生成结构建议（--generate-recommendations）；notification 负责向相关方通报架构改进。这四个挂点统一通过 npx ruv-swarm hook 命令执行，并以 --mode repo-architect 区分子模式。这套"编辑即校验、结束即建议"的机制，把架构合规检查从人工审查变成了自动化闭环。

使用模式一：仓库结构分析与优化 Swarm

第一个模式启动一个 mesh 拓扑的四代理分析集群，再编排结构优化任务：

// Initialize architecture analysis swarm
mcp__claude-flow__swarm_init { topology: "mesh", maxAgents: 4 }
mcp__claude-flow__agent_spawn { type: "analyst", name: "Structure Analyzer" }
mcp__claude-flow__agent_spawn { type: "architect", name: "Repository Architect" }
mcp__claude-flow__agent_spawn { type: "optimizer", name: "Structure Optimizer" }
mcp__claude-flow__agent_spawn { type: "coordinator", name: "Multi-Repo Coordinator" }

// Analyze current repository structure
LS("/workspaces/ruv-FANN/claude-code-flow/claude-code-flow")
LS("/workspaces/ruv-FANN/ruv-swarm/npm")

// Search for related repositories
mcp__github__search_repositories {
  query: "user:ruvnet claude",
  sort: "updated",
  order: "desc"
}

// Orchestrate structure optimization
mcp__claude-flow__task_orchestrate {
  task: "Analyze and optimize repository structure for scalability and maintainability",
  strategy: "adaptive",
  priority: "medium"
}

调用链拆解如下：

• swarm_init 以 topology: "mesh" 初始化集群，maxAgents: 4 设定并发上限。从源码结构看，swarm_init 是 V2 兼容层暴露的工具名，在 v2-compat-tools.ts 中被映射到 v3 的 swarm/init 动作，即 V2 命名空间的旧工具调用会转发到 V3 MCP 工具集执行；
• agent_spawn 按 type/name 生成四个角色：analyst（结构分析）、architect（架构决策）、optimizer（结构优化）、coordinator（多仓协调），各司其职；
• 随后用 LS 遍历两个工作区的目录树、mcp__github__search_repositories 按 user:ruvnet claude 检索关联远端仓库；
• 最后 task_orchestrate 以 strategy: "adaptive"（自适应策略）和 priority: "medium" 接管编排。

这套模式的关键点是"先建集群、再喂数据、后下任务"：分析所需的目录信息（LS 结果）与远端仓库清单（search 结果）作为上下文注入，再让编排器在集群内分配优化子任务。

使用模式二：多仓库模板创建

第二个模式演示如何一键生成标准化项目模板仓库，包含完整的配置文件推送：

// Create standardized repository template
mcp__github__create_repository {
  name: "claude-project-template",
  description: "Standardized template for Claude Code projects with ruv-swarm integration",
  private: false,
  autoInit: true
}

// Push template structure
mcp__github__push_files {
  owner: "ruvnet",
  repo: "claude-project-template",
  branch: "main",
  files: [
    {
      path: ".claude/commands/github/github-modes.md",
      content: "[GitHub modes template]"
    },
    {
      path: ".claude/commands/sparc/sparc-modes.md",
      content: "[SPARC modes template]"
    },
    {
      path: ".claude/config.json",
      content: JSON.stringify({
        version: "1.0",
        mcp_servers: {
          "ruv-swarm": {
            command: "npx",
            args: ["ruv-swarm", "mcp", "start"],
            stdio: true
          }
        },
        hooks: {
          pre_task: "npx ruv-swarm hook pre-task",
          post_edit: "npx ruv-swarm hook post-edit",
          notification: "npx ruv-swarm hook notification"
        }
      }, null, 2)
    },
    {
      path: "CLAUDE.md",
      content: "[Standardized CLAUDE.md template]"
    },
    {
      path: "package.json",
      content: JSON.stringify({
        name: "claude-project-template",
        version: "1.0.0",
        description: "Claude Code project with ruv-swarm integration",
        engines: { node: ">=20.0.0" },
        dependencies: {
          "ruv-swarm": "^1.0.11"
        }
      }, null, 2)
    },
    {
      path: "README.md",
      content: `# Claude Project Template

## Quick Start
\`\`\`bash
npx claude-flow init --sparc
npm install
npx claude-flow start --ui
\`\`\`

## Features
- ruv-swarm integration
- SPARC development modes
- GitHub workflow automation
- Advanced coordination capabilities

## Documentation
See CLAUDE.md for complete integration instructions.`
    }
  ],
  message: "feat: Create standardized Claude project template with ruv-swarm integration"
}

模板中每个文件都有明确职责，值得逐一说清：

模板文件	作用
.claude/commands/github/github-modes.md	注入 GitHub 工作流命令集（与仓库内 github-modes.md 同源）
.claude/commands/sparc/sparc-modes.md	注入 SPARC 开发模式（对应 sparc-modes.md）
.claude/config.json	声明 ruv-swarm MCP server 的启动方式（npx ruv-swarm mcp start，stdio 传输）与三个生命周期 hooks
CLAUDE.md	项目级 AI 协作约定，作为后续 Agent 会话的行为基线
package.json	锁定 Node >=20.0.0 运行环境与 ruv-swarm ^1.0.11 依赖
README.md	提供三步 Quick Start：npx claude-flow init --sparc → npm install → npx claude-flow start --ui

push_files 将六个文件作为单个提交推送到 main，提交信息遵循 Conventional Commits 风格（feat: ...），保证模板仓库从首个提交起就是完整、可运行的。

使用模式三：跨仓库结构同步

第三个模式针对一组关联仓库批量下发相同的 CI 工作流，消除结构漂移：

// Synchronize structure across related repositories
const repositories = [
  "claude-code-flow",
  "ruv-swarm",
  "claude-extensions"
]

// Update common files across repositories
repositories.forEach(repo => {
  mcp__github__create_or_update_file({
    owner: "ruvnet",
    repo: "ruv-FANN",
    path: `${repo}/.github/workflows/integration.yml`,
    content: `name: Integration Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm install && npm test`,
    message: "ci: Standardize integration workflow across repositories",
    branch: "structure/standardization"
  })
})

该模式有四个工程要点：一是使用 create_or_update_file 的幂等语义（存在则更新、不存在则创建），使同一脚本可重复执行；二是统一走独立分支 structure/standardization，同步变更先以 PR 形式评审，不直接改主干；三是同步的内容是 CI 集成测试工作流（Node 20 + npm install && npm test），这是多仓中最容易漂移的"一致性锚点"；四是提交信息以 ci: 前缀标记，方便在仓库历史中检索此类自动同步提交。

批量架构操作：单消息完成完整架构评审

技能文档中的"Batch Architecture Operations"展示了把所有操作压缩进单条消息的批量编排，这是该技能区别于单步命令的关键：

[Single Message - Repository Architecture Review]:
  // 1. 初始化 6 代理层级集群
  mcp__claude-flow__swarm_init { topology: "hierarchical", maxAgents: 6 }
  mcp__claude-flow__agent_spawn { type: "architect", name: "Senior Architect" }
  mcp__claude-flow__agent_spawn { type: "analyst", name: "Structure Analyst" }
  mcp__claude-flow__agent_spawn { type: "optimizer", name: "Performance Optimizer" }
  mcp__claude-flow__agent_spawn { type: "researcher", name: "Best Practices Researcher" }
  mcp__claude-flow__agent_spawn { type: "coordinator", name: "Multi-Repo Coordinator" }

  // 2. 读取两个仓库的目录树与 package.json
  LS("/workspaces/ruv-FANN/claude-code-flow/claude-code-flow")
  Read("/workspaces/ruv-FANN/claude-code-flow/claude-code-flow/package.json")

  // 3. 用 gh CLI 检索架构模式参考
  ARCH_PATTERNS=$(Bash(`gh search repos "language:javascript template architecture" \
    --limit 10 \
    --json fullName,description,stargazersCount \
    --sort stars \
    --order desc`))

  // 4. 推送优化后的结构文件
  mcp__github__push_files {
    branch: "architecture/optimization",
    files: [
      { path: ".../.github/ISSUE_TEMPLATE/integration.yml", content: "[Integration issue template]" },
      { path: ".../.github/PULL_REQUEST_TEMPLATE.md", content: "[Standardized PR template]" },
      { path: ".../docs/ARCHITECTURE.md", content: "[Architecture documentation]" },
      { path: ".../.github/workflows/cross-package-test.yml", content: "[Cross-package testing workflow]" }
    ],
    message: "feat: Optimize repository architecture for scalability and maintainability"
  }

  // 5. TodoWrite 跟踪进度
  // 6. memory_usage 持久化分析结果
  mcp__claude-flow__memory_usage {
    action: "store",
    key: "architecture/analysis/results",
    value: {
      timestamp: Date.now(),
      repositories_analyzed: ["claude-code-flow", "ruv-swarm"],
      optimization_areas: ["structure", "workflows", "templates", "documentation"],
      recommendations: ["standardize_structure", "improve_workflows", "enhance_templates"],
      implementation_status: "in_progress"
    }
  }

与使用模式一相比，批量操作有三处升级：拓扑从 mesh 换成 hierarchical（层级制更适合"一个总架构师 + 专业分析员"的评审结构），代理数从 4 增至 6（新增 Senior Architect 与 Best Practices Researcher），并引入两个收尾动作——TodoWrite 用带 id/status/priority 的清单跟踪五个子任务（分析、调研、模板、工作流、文档），memory_usage 把分析结论以 architecture/analysis/results 为键写入持久记忆，包含时间戳、已分析仓库、优化领域、建议清单与实施状态。这样后续会话可以凭记忆键直接恢复上下文，避免重复分析。

三类架构模式参考

技能文档给出了三个可照抄的架构模式骨架。

1. Monorepo 结构模式

ruv-FANN/
├── packages/
│   ├── claude-code-flow/
│   │   ├── src/
│   │   ├── .claude/
│   │   └── package.json
│   ├── ruv-swarm/
│   │   ├── src/
│   │   ├── wasm/
│   │   └── package.json
│   └── shared/
│       ├── types/
│       ├── utils/
│       └── config/
├── tools/
│   ├── build/
│   ├── test/
│   └── deploy/
├── docs/
│   ├── architecture/
│   ├── integration/
│   └── examples/
└── .github/
    ├── workflows/
    ├── templates/
    └── actions/

核心思想是"packages 按领域分包、shared 收口公共类型/工具/配置、tools 集中构建与部署脚本、docs 与 .github 模板化"。从源码结构看，ruflo 仓库本身就是一个多包工程：顶层 Cargo.toml 管理 Rust 工作区，crates 下有 ruflo-agntcy、ruflo-federation-peer、ruflo-watermark 三个 crate，v3 目录下 @claude-flow/ 聚合了 cli、mcp、memory、swarm、security、guidance 等数十个 TS 子包，加上 plugins 下的插件生态——与文档中 packages/tools/docs/.github 的分层思路相互印证，只是 ruflo 同时横跨 TS 与 Rust 两个包管理域。

2. 命令结构模式

.claude/
├── commands/
│   ├── github/
│   │   ├── github-modes.md
│   │   ├── pr-manager.md
│   │   ├── issue-tracker.md
│   │   └── sync-coordinator.md
│   ├── sparc/
│   │   ├── sparc-modes.md
│   │   ├── coder.md
│   │   └── tester.md
│   └── swarm/
│       ├── coordination.md
│       └── orchestration.md
├── templates/
│   ├── issue.md
│   ├── pr.md
│   └── project.md
└── config.json

该模式规定 AI 命令必须按领域（github/sparc/swarm）分目录组织，且与模板、配置并列。ruflo 仓库的 plugin/commands 目录正是这一模式的实例化：github/ 下含 pr-manager.md、issue-tracker.md、sync-coordinator.md、release-manager.md 等文件，sparc/ 下含 architect.md、coder.md、tester.md，swarm/ 下含 swarm-init.md、swarm-strategies.md 等，目录层级与文档中的模式完全对应。

3. 集成模式

const integrationPattern = {
  packages: {
    "claude-code-flow": {
      role: "orchestration_layer",
      dependencies: ["ruv-swarm"],
      provides: ["CLI", "workflows", "commands"]
    },
    "ruv-swarm": {
      role: "coordination_engine",
      dependencies: [],
      provides: ["MCP_tools", "neural_networks", "memory"]
    }
  },
  communication: "MCP_protocol",
  coordination: "swarm_based",
  state_management: "persistent_memory"
}

该模式把多包集成显式化为三个维度：包间角色与依赖（编排层依赖协调引擎，方向单向）、通信协议（MCP）、状态管理（持久记忆）。对应到 ruflo 的实现：MCP 工具层位于 v3/mcp（server 入口、工具注册表、按领域拆分的 tools 模块），swarm 协调实现位于 v3/@claude-flow/swarm，持久记忆位于 v3/@claude-flow/memory——分层与文档中的角色划分一致。

最佳实践与架构健康度监控

文档将最佳实践归纳为四组检查项：

1. 结构优化：跨仓库目录组织一致、配置文件与格式标准化、关注点分离清晰、为未来增长预留可扩展架构；
2. 模板管理：可复用项目模板、标准化 issue/PR 模板、常见操作的 workflow 模板、清晰的文档模板；
3. 多仓协调：跨仓依赖管理、版本与发布同步、编码标准统一、自动化的跨仓校验；
4. 文档架构：完整的架构文档、清晰的集成指南与示例、可持续维护的文档、面向新人的 onboarding 材料。

监控层面定义了四类架构健康指标：仓库结构一致性得分、文档覆盖率、跨仓集成成功率、模板采用与使用统计；以及四类自动化分析能力：结构漂移检测（structure drift detection）、最佳实践合规检查、性能影响分析、可扩展性评估与建议。这套指标体系可以理解为把"架构腐化"量化为可观测信号，配合 post_edit 钩子的 --validate-structure 校验形成"检测—告警—修正"回路。

与工作流的集成点

技能文档最后声明了四个协作入口：

集成命令	用途
$github sync-coordinator（定义）	跨仓库同步
$github release-manager（定义）	协同发布
$sparc architect（定义）	深度架构设计
$sparc optimizer（定义）	性能优化

工作流增强方面则承诺四项持续能力：自动化结构校验、持续架构改进、最佳实践强制执行、文档生成与维护。需要说明的是，ruflo 生态中还存在分工互补的技能：agent-github-modes 覆盖 GitHub 工作流编排与 PR/Issue 管理，agent-multi-repo-swarm 专注跨仓库 swarm 的初始化、依赖发现与同步策略（eventual/strong/hybrid 一致性）——repo-architect 聚焦"结构与模板"，multi-repo-swarm 聚焦"运行时协调"，二者组合即覆盖多仓治理的静态与动态两个侧面。

适用前提与落地建议

使用该技能时需注意以下前提与限制：

• 宿主环境：技能面向支持 MCP 的 Agent 宿主运行。Codex CLI 侧需要 .agents/config.toml 完成配置——其中 [mcp_servers.claude-flow] 以 npx -y @claude-flow/cli@latest 启动 MCP server（tool_timeout_sec = 120），[swarm] 段定义了默认拓扑（hierarchical）、共识算法（raft）与反漂移开关，这些正是 swarm_init/task_orchestrate 的默认行为来源；Claude Code 侧则通过 plugin/commands/github 的命令文件加载同一套流程。
• 工具依赖：模式一/二/三均依赖 mcp__github__* 与 mcp__claude-flow__* 两组 MCP 工具可用，gh CLI 需完成认证（参考 agent-multi-repo-swarm 中 gh auth status 的前置检查写法）。
• 变更安全：所有远端写入（push_files、create_or_update_file）都应走独立分支（如 architecture/optimization、structure/standardization），以 PR 评审为落地闸门，与文档示例的分支约定保持一致。
• 示例路径：文档示例中的 ruvnet、ruv-FANN 等为作者环境的工作区与账号标识，实际使用时应替换为自己的组织名、仓库路径与模板名。

综合来看，agent-repo-architect 技能的价值在于把"仓库架构治理"拆成了可编排的原语：swarm 集群负责分工，LS/Read 负责取证，GitHub MCP 负责落地，TodoWrite/memory_usage 负责状态与记忆，hooks 负责前后置校验。掌握这套组合后，无论是单仓结构体检还是多仓模板统一，都可以按"初始化集群 → 注入上下文 → 编排任务 → 分支推送 → 记忆归档"的固定节奏执行。