从子代理定义到多智能体落地：Ruflo system-architect 架构设计师 Agent 设计指南

ruflo 仓库把"系统架构设计师"沉淀成了一个可复用的 Claude Code 子代理定义文件（arch-system-design.md）。本文以这份定义为骨架，逐段解读其职责、最佳实践、交付物与决策框架，并结合仓库中真实的编排方式（Task 子代理调度、命名 Agent 团队、SPARC 质量门、ADR 记录体系）说明该角色如何嵌入 ruflo 的多智能体流水线，帮助你在自己的项目里编写、加载并调度同类的"架构师角色"。

这份文档到底是什么：一个被 Claude Code 加载的 Agent 定义

打开 .claude/agents/architecture/system-design/arch-system-design.md，你会发现它并不长，结构分两层：

YAML frontmatter（元数据契约）：

---
name: system-architect
description: Expert agent for system architecture design, patterns, and high-level technical decisions
---

• name：Agent 的唯一标识。在 ruflo 中它会被当作 subagent_type 引用（详见下文"接入编排"），等价于一个可寻址的"工种"。
• description：供上层调度（模型路由 / 自动触发）判断"什么任务该派给谁"的说明，因此写得足够宽泛：系统架构设计、架构模式、高层技术决策。

Markdown 正文：定义角色的自述、关键职责、最佳实践、交付物与决策框架。它是一份"人设 + 工作准则"指令，加载后即成为负责高层技术决策的专职 Agent（You are a System Architecture Designer responsible for high-level technical decisions and system design.）。

在仓库中，同一定义存在两处：

• 运行时目录 .claude/agents/architecture/system-design/arch-system-design.md；
• 插件镜像 plugin/agents/architecture/system-design/arch-system-design.md，说明该 Agent 会随插件/分发形态同步发布（v3/@claude-flow 下亦有同构副本）。

这与 ruflo v3 对整个 Agent 系统的描述一致：Agent 定义统一放在 .claude/agents/ 下、以 Markdown + frontmatter 承载，配合 Skills、Commands、Hooks 形成可扩展的协作底座（详见 AGENTS-SKILLS-COMMANDS-HOOKS.md）。

角色的五项核心职责与仓库中的对应物

原文档定义了五条关键职责（Key responsibilities），它们共同刻画了"架构师 Agent"在团队中的边界：

#	职责	在 ruflo 仓库中的对应体现
1	设计可扩展、可维护的系统架构	ruflo 全局约定采用领域驱动设计（DDD）与有界上下文，并要求"文件保持在 500 行内、公开 API 全部使用类型化接口"，见 CLAUDE.md
2	用清晰的论证记录架构决策（ADR）	仓库沉淀了大量 ADR：v3/docs/adr/ 下约 177 个决策记录、ruflo/docs/adr/ 下 16 个，如 ADR-095-architectural-gaps-from-april-audit.md，是"以文档承载决策"的直接证据
3	创建系统图与组件交互图	交付物要求（见下节）规定必须产出 C4/UML 组件交互与数据流图
4	评估技术选型与权衡	决策框架中的"trade-offs / 与业务目标对齐"即为其执行工具
5	定义架构模式与原则	仓库顶层约定"事件溯源记录状态变更、系统边界处做输入校验"，可视为该 Agent 需落地的全局原则，见 CLAUDE.md

值得注意的是，职责 2（ADR）在 ruflo 中不是口号而是强约束：v3/docs/adr/ 的近两百条记录覆盖了从检索、记忆、安全到联邦传输的各个子系统，说明"架构决策必须文档化"是整个团队——包括架构师 Agent——的一等公民实践。

最佳实践清单：原文六条与源码印证

原文档的 Best practices 部分提出：

1. 考虑非功能需求（性能、安全、可扩展性）。ruflo 的实测印证分布在 docs/benchmarks/、verification/ 等目录；v3 还专门配置了性能目标（如 .claude/config/v3-performance-targets.json），架构评审须对照此类质量属性。
2. 为重大决策记录 ADR。前文已述，v3/docs/adr/、ruflo/docs/adr/ 与 v3/implementation/adrs/ 三处都是 ADR 的现实归档。
3. 使用标准绘图符号（C4、UML）。对应交付物要求中的"C4 model preferred"。
4. 前瞻可扩展性。ruflo 以插件体系作答：plugins/ 下数十个 ruflo-* 插件 + plugin/ 中的技能/命令/Agent 模板，架构师在设计时必须给"未来新增能力"留出扩展点。
5. 考虑运维层面（部署、监控）。仓库配套了 tests/docker-regression/、ruflo/docker-compose*.yml 与可观测性插件（plugins/ruflo-observability），架构交付物应说明部署与监控方案。

这几条最佳实践本质上回答了："架构师 Agent 不只画图，还要对上线后能不能跑、安不安全、好不好扩展负责。"

交付物要求：架构师的产出清单

原文档规定架构师应产出五类交付物，这份清单可直接用作任务的验收标准：

交付物	说明
1. 架构图	以 C4 模型为优先（context → container → component → code 逐层下钻）
2. 组件交互图	描述模块间调用/消息关系，供 coder/tester 依图实现与测试
3. 数据流图	明确数据从边界输入到存储/检索的完整路径
4. 架构决策记录（ADR）	每个重大决策附理由与备选方案
5. 技术选型评估矩阵	按质量属性对各候选方案横向打分对比

仓库中可观察到的同类产物包括 DDD 架构文档目录 v3/docs/ddd、release 文档 v3/docs/releases，以及大量 ADR 正文中"背景—决策—后果"的结构化写法。这也提示：给架构师 Agent 下任务时，应明确要求"设计结果写入哪个命名空间/目录"，例如 ruflo 常见做法是让设计稿落入 collaboration 记忆命名空间（见下文示例）。

决策框架：每次设计前必答的五个问题

原文把决策过程收敛为五个问题，可直接嵌入 Agent 的 prompt 或作为评审检查项：

1. 需要哪些质量属性？（What are the quality attributes required?）——如吞吐、时延、一致性、安全性，先排序再设计；
2. 约束与假设是什么？（What are the constraints and assumptions?）——包括技术栈、团队、预算、合规边界；
3. 每个选项的权衡是什么？（What are the trade-offs of each option?）——没有免费的午餐，方案必须列出代价；
4. 与业务目标如何对齐？（How does this align with business goals?）——防止"技术上优雅但业务上无价值"；
5. 风险与缓解策略？（What are the risks and mitigation strategies?）——给出回滚与降级路径。

这五个问题既可以在任务 prompt 末尾要求架构师"逐条作答"，也可以作为 PR / 评审时评审者向架构产出提问的清单。结合上文"architecture 阶段"（见下节）把"决策框架 + 可验证门槛"绑定后，架构环节就有了可判定的完成标准。

接入 ruflo 编排：把 system-architect 真正调度起来

定义文件只有在被加载并调度时才有价值。在 ruflo 中，system-architect 至少有四种典型接入形态，仓库 CLAUDE.md 中均有可直接复制的调用范式。

形态一：按 subagent_type 直接孵化

最简单的方式是在消息中直接指定工种（对应 CLAUDE.md）：

Task("Architect", "Design the implementation. Store design in memory namespace 'collaboration'.", "system-architect")

要点：任务文本会说明产物去向（写入 collaboration 命名空间），以便下游 coder/tester 读取同一上下文。

形态二：命名 Agent + SendMessage 组队

ruflo 的 Agent Teams 机制要求每个 Agent 拥有 name，并通过 SendMessage 互相通信而非轮询。以下片段出自 CLAUDE.md，展示后台运行、流水线衔接的写法：

Task({
  prompt: "Wait for research from 'researcher'. Design implementation. SendMessage design to 'coder'.",
  subagent_type: "system-architect", name: "architect", run_in_background: true
})
Task({
  prompt: "Wait for design from 'architect'. Implement the solution. SendMessage code paths to 'tester'.",
  subagent_type: "coder", name: "coder", run_in_background: true
})

更完整的"通信感知"prompt 模板见 CLAUDE.md：它要求架构师设计完成后经 SendMessage 把"文件路径 + 关键决策"发给 developer，需要澄清时直接输出文本给 team lead——这就是把原文档"文档化决策"落到了 Agent 协作层。

形态三：双平台（dual-mode）协作流水线

ruflo 的 dual-mode 让 Claude 侧 Worker（architecture/security/testing）与 Codex 侧 Worker（implementation/optimization）协同，feature 模板的流水线为 Architect → Coder → Tester → Reviewer，其中架构师仍由 system-architect 担任（CLAUDE.md）。

形态四：作为 SPARC 方法论的"架构质量门"

ruflo-sparc 插件把开发拆为 Specification → Pseudocode → Architecture → Refinement → Completion 五阶段，每阶段设质量门。其中第 3 阶段（Architecture）专门孵化 system-architect，门槛是硬性的三条：所有约束已处理、类型化 API 契约、无循环依赖（见 plugins/ruflo-sparc/README.md）。

claude --plugin-dir plugins/ruflo-sparc   # 安装插件后即可按 SPARC 流程推进

这意味着：原文档中的"职责与最佳实践"在 SPARC 语境下被翻译成了可机器校验的 gate 条件——从"应该怎么设计"变成"怎么算设计合格"。

如何查询与验证 Agent 是否就绪

ruflo 提供了面向 Agent 能力的自省命令。按 agent-capabilities.md 的记录，架构类角色的能力矩阵是：

Agent Type	Primary Skills	Best For
architect / system-architect	Design, planning	System architecture

# 列出全部 Agent 能力
npx claude-flow agents capabilities

# 查看指定工种
npx claude-flow agents capabilities --type system-architect

也可以在 Agent 清单（CLAUDE.md）中确认 system-architect 与 backend-dev、api-docs 等同列于 Specialized Development 类别。

扩展与自定义建议

如果你要在自己的项目复刻这样一个架构师 Agent，可参考 ruflo v3 的 Agent 模板约定（见 AGENTS-SKILLS-COMMANDS-HOOKS.md 第 1.3 节）对 arch-system-design.md 做增强：

---
name: system-architect
version: 3.0.0
category: specialized
description: Expert agent for system architecture design, patterns, and high-level technical decisions
capabilities:
  - system-design
  - architecture-patterns
  - technology-evaluation
tools:
  - Read
  - Grep
  - Glob
triggers:
  - "architecture"
  - "system design"
  - "component diagram"
  - "ADR"
---

几点实操建议：

• 保持正文是"准则"而非"实现"：原文档只给职责/最佳实践/交付物/决策框架，把具体编码规则（如 DDD、500 行限制、类型化接口）留给全局约定（本项目写在 CLAUDE.md），这样 Agent 定义在不同代码库间可移植；
• 绑定产物位置：调度时始终写明设计文档归档到哪个记忆命名空间（如 collaboration、sparc-phases），保证下游 coder/tester/reviewer 有据可依；
• 把交付物变成门槛：像 ruflo-sparc 那样为架构阶段定义可校验的 gate（约束覆盖、API 契约、无循环依赖），否则"架构师已产出"无法被客观判定；
• 与角色生态复用：仓库中还有 repo-architect.md（面向代码仓库结构）、v3 系列的 v3-integration-architect、v3-security-architect（.claude/agents/v3）等相近工种，可按领域拆分，避免让单个 system-architect 定义承载过多职责。

小结

arch-system-design.md 虽然只有数十行，但它是 ruflo"把架构能力人格化"的最小契约：frontmatter 决定"能被谁调度"，正文决定"被调度后如何行事"。结合仓库真实的四种调度形态——subagent_type 直接孵化、命名 Agent + SendMessage 组队、dual-mode 跨平台流水线、SPARC 质量门——这份定义便从静态文本升级为可运行、可验证、可持续沉淀 ADR 的组织级能力。你在自己的多智能体工程中复制这套"职责—实践—交付物—决策框架"四段式结构，即可获得一个行为稳定、产出可验收的架构师角色。