ruflo 架构设计 Agent 技能解析：agent-arch-system-design 的声明式配置、权限边界与决策框架

ruflo（Claude Flow 系 meta-harness 仓库）通过 .agents/skills/ 目录以声明式 SKILL 文件的形式定义可被 $skill-name 语法直接调用的 Agent 技能。本篇以 agent-arch-system-design 技能文件 为主体，逐层拆解"系统架构设计师（system-architect）"这一技能的完整元数据、工具白名单/黑名单、路径约束、生命周期钩子与 Agent 提示词正文，并结合仓库中的 技能目录说明、Codex 配置文件 和同源 Agent 定义，说明该技能在 ruflo 多 Agent 工作流中的角色与可复制的配置范式。读完本文，你可以掌握如何为一个高权限敏感场景（架构设计）编写一个"只读源码、只写文档、关键决策需人工审批"的受控 Agent 技能。

技能文件的双层结构：Skill 包装层 + Agent 定义层

SKILL.md 的组织方式是理解 ruflo 技能体系的关键：它实际上由两层 YAML frontmatter 加一段 Markdown 正文构成。

第一层是技能包装 frontmatter（第 1–4 行），只声明两件事：

name: agent-arch-system-design
description: Agent skill for arch-system-design - invoke with $agent-arch-system-design

$agent-arch-system-design 即调用入口。按照 .agents/README.md 的说明，skills/ 下的每个技能以 $skill-name 语法被唤起，且"每个技能都包含带元数据的 YAML frontmatter、触发与跳过条件、命令与示例"。

第二层是从第 6 行开始的完整 Agent 定义 frontmatter，定义了 system-architect 这个专家角色的全部运行参数（下节展开）。第三层是 # System Architecture Designer 之后的 Markdown 正文，即注入给 LLM 的系统提示词：职责、最佳实践、交付物与决策框架。

这种"技能 = 元数据信封 + 完整 Agent 定义 + 提示词正文"的三层结构，使得同一个技能既能被 CLI 按名字调度，又携带了自身的行为边界，而不依赖外部集中式配置。仓库中同名的 Agent 定义 arch-system-design.md 保留了提示词正文部分（职责、最佳实践、交付物、决策框架与 SKILL.md 正文完全一致），可以印证 SKILL.md 是在该 Agent 定义之上叠加了可执行元数据的"技能化"版本。

触发器（triggers）：关键词、文件模式与任务模式的三维匹配

Agent 定义的 triggers 段回答了"什么情况下应该唤起这个技能"，它给出了三类匹配维度：

triggers:
  keywords:
    - "architecture"
    - "system design"
    - "scalability"
    - "microservices"
    - "design pattern"
    - "architectural decision"
  file_patterns:
    - "**$architecture/**"
    - "**$design/**"
    - "*.adr.md"   # Architecture Decision Records
    - "*.puml"     # PlantUML diagrams
  task_patterns:
    - "design * architecture"
    - "plan * system"
    - "architect * solution"
  domains:
    - "architecture"
    - "design"

• keywords：任务描述中出现"架构、系统设计、可扩展性、微服务、设计模式、架构决策"等词时命中；
• file_patterns：任务涉及 ADR 文件（*.adr.md）、PlantUML 图（*.puml）或 architecture/design 目录时命中。仓库内 v3/docs/adr/ 下存有 177 个 ADR 文档，正是该模式要服务的工作面；
• task_patterns：面向自然语言任务串的模糊匹配，如 design * architecture；
• domains：限定技能归属的领域命名空间，便于与其他技能（如安全、性能）做路由隔离。

从源码结构看，file_patterns 中 **$architecture/** 这类写法更像是占位符风格的目录通配（$ 并非标准 glob 语法），这一点在使用时应以实际目录名（如 docs/architecture）为准，而 *.adr.md 与 *.puml 则是无歧义的强触发信号。

能力边界（capabilities）：工具白名单与资源配额

capabilities 段是这个技能最核心的"安全设计"，它显式区分了允许工具与受限工具：

capabilities:
  allowed_tools:
    - Read
    - Write   # Only for architecture docs
    - Grep
    - Glob
    - WebSearch  # For researching patterns
  restricted_tools:
    - Edit      # Should not modify existing code
    - MultiEdit
    - Bash      # No code execution
    - Task      # Should not spawn implementation agents
  max_file_operations: 30
  max_execution_time: 900  # 15 minutes for complex analysis
  memory_access: "both"

设计意图非常清晰：

配置项	取值	设计含义
allowed_tools	Read / Write / Grep / Glob / WebSearch	架构师可以读代码、搜模式、查资料、写文档，Write 被注释限定为"仅用于架构文档"
restricted_tools	Edit / MultiEdit / Bash / Task	不能改代码、不能执行命令、不能派生子 Agent——架构决策与代码实现在角色上被物理隔离
max_file_operations	30	单次执行最多 30 次文件操作，防止无界扫描
max_execution_time	900 秒	复杂架构分析的 15 分钟时间预算
memory_access	both	同时访问短期与长期记忆（ruflo 的自适应记忆层）

这一"读多写少、禁执行、禁派生"的工具面，与 ruflo 仓库全局的 Agent 权限治理思路一致：例如 .agents/config.toml 中的 [performance] 段为所有并发 Agent 设定 memory_limit = "512MB"、task_timeout = 300 等全局上限，而技能级的 max_execution_time: 900 是针对架构分析这类长任务的专项放宽。

路径约束（constraints）：可写区与禁读区

constraints 段进一步把行为边界落到文件系统路径层面：

constraints:
  allowed_paths:
    - "docs$architecture/**"
    - "docs$design/**"
    - "diagrams/**"
    - "*.md"
    - "README.md"
  forbidden_paths:
    - "src/**"        # Read-only access to source
    - "node_modules/**"
    - ".git/**"
  max_file_size: 5242880  # 5MB for diagrams
  allowed_file_types:
    - ".md"
    - ".puml"
    - ".svg"
    - ".png"
    - ".drawio"

要点解读：

• allowed_paths 定义可写/可产出的区域：架构文档目录、diagrams/ 图示目录，以及所有 Markdown 文件。注意 forbidden_paths 中对 src/** 的注释是 "Read-only access to source"——即源码可读但不可写，与 allowed_tools 中 Write 的限定相互印证；
• max_file_size: 5242880（5MB）：注释说明这是为图形文件（PlantUML 导出图、drawio 文件）预留的上限，防止超大二进制拖垮上下文；
• allowed_file_types：只允许 Markdown、PlantUML、SVG、PNG、drawio 五种产物类型，与"交付物以图和文档为中心"的定位完全对应。

这与 .agents/config.toml 中 [security] 段的全局文件策略（max_file_size = 10485760、blocked_patterns = ["\\.env$", "credentials\\.json$", ...]）形成两级防线：全局配置管敏感文件与总量上限，技能配置管本角色的产物类型。

行为（behavior）与沟通（communication）：审批门控与输出风格

behavior:
  error_handling: "lenient"
  confirmation_required:
    - "major architectural changes"
    - "technology stack decisions"
    - "breaking changes"
    - "security architecture"
  auto_rollback: false
  logging_level: "verbose"

communication:
  style: "technical"
  update_frequency: "summary"
  include_code_snippets: false  # Focus on diagrams and concepts
  emoji_usage: "minimal"

• confirmation_required 是人工审批门：重大架构变更、技术栈选型、破坏性变更、安全架构这四类决策必须经人确认。这与顶层元数据 metadata.autonomous: false（"重大决策需人工批准"）以及 integration.requires_approval_from: ["human"] 三处声明互为冗余，确保该 Agent 永远不会"自主拍板"；
• error_handling: "lenient" + auto_rollback: false：架构设计是思考型任务，出错时宽容处理且不自动回滚（回滚由人审查后决定）；
• logging_level: "verbose"：复杂决策过程要留下详尽日志，便于事后审计 ADR；
• include_code_snippets: false：明确要求"聚焦图示与概念而非代码片段"，update_frequency: "summary" 则约束汇报方式为阶段性摘要而非逐条流水——这两项定义了该 Agent 的输出体裁。

集成（integration）：委派与上下文共享拓扑

integration:
  can_spawn: []
  can_delegate_to:
    - "docs-technical"
    - "analyze-security"
  requires_approval_from:
    - "human"
  shares_context_with:
    - "arch-database"
    - "arch-cloud"
    - "arch-security"

这段声明了一个清晰的协作拓扑：

• can_spawn: []：不允许生成任何子 Agent，与 restricted_tools 中的 Task 限制一致；
• can_delegate_to：可以把"技术文档撰写"委派给 docs-technical、把"安全分析"委派给 analyze-security——架构师负责决策，执行型工作外派；
• shares_context_with：与数据库、云、安全三个兄弟架构 Agent 共享上下文。从技能命名规律可以推断，ruflo 的架构师矩阵由 arch-system-design、arch-database、arch-cloud、arch-security 等专职角色构成，它们通过上下文共享避免重复调研，同时各自保持独立的决策权限；
• requires_approval_from: ["human"]：再次收口——重大决策的最终审批权在人。

优化（optimization）与钩子（hooks）：串行思考 + 生命周期脚本

optimization:
  parallel_operations: false  # Sequential thinking for architecture
  batch_size: 1
  cache_results: true
  memory_limit: "1GB"

parallel_operations: false 的注释直白："架构设计需要串行思考"。这是一个有意识反性能优化的决策：批量并行适合代码批量修改，但架构推演需要逐步收敛，batch_size: 1 即逐条深入；cache_results: true 与 1GB 内存上限则保证长分析过程中调研结果可复用。

hooks 段为技能的生命周期挂载了 shell 片段：

hooks:
  pre_execution: |
    echo "🏗️ System Architecture Designer initializing..."
    echo "📊 Analyzing existing architecture..."
    echo "Current project structure:"
    find . -type f -name "*.md" | grep -E "(architecture|design|README)" | head -10
  post_execution: |
    echo "✅ Architecture design completed"
    echo "📄 Architecture documents created:"
    find docs$architecture -name "*.md" -newer $tmp$arch_timestamp 2>$dev$null || echo "See above for details"
  on_error: |
    echo "⚠️ Architecture design consideration: {{error_message}}"
    echo "💡 Consider reviewing requirements and constraints"

• pre_execution：先盘点项目现有的 architecture/design/README 类 Markdown 文档（find + grep 前 10 条），让 Agent 带着"现状清单"进入分析，避免闭门造车；
• post_execution：按时间戳 diff 列出本次新生成的架构文档，形成"产出物清单"；
• on_error：以 {{error_message}} 模板变量注入错误上下文，并提示复查需求与约束。

需要说明：这些钩子以 echo + find 为主，属于信息收集与产出汇报型钩子；其中 post_execution 依赖的 $tmp$arch_timestamp 变量需由宿主环境在运行时提供（文档中 $dev$null 的写法是 Windows 风格重定向），从仓库内容看该技能并未附带独立的 scripts 目录，钩子执行的具体注入逻辑以 ruflo 技能加载器的实际实现为准。

触发示例（examples）：两个典型任务入口

技能自带两条 trigger/response 示例，定义了用户侧的调用语感：

examples:
  - trigger: "design microservices architecture for e-commerce platform"
    response: "I'll design a comprehensive microservices architecture for your e-commerce platform,
               including service boundaries, communication patterns, and deployment strategy..."
  - trigger: "create system architecture for real-time data processing"
    response: "I'll create a scalable system architecture for real-time data processing,
               considering throughput requirements, fault tolerance, and data consistency..."

两条示例分别覆盖面向业务的微服务边界设计与面向数据通道的实时处理架构，且响应模板中点名的"服务边界、通信模式、部署策略、吞吐、容错、数据一致性"正是下文决策框架的具体化。

Agent 提示词正文：职责、交付物与决策框架

frontmatter 之后的 Markdown 正文是注入 LLM 的提示词，与 arch-system-design.md 中保留的 Agent 定义同源。其核心内容完整如下，是"这个 Agent 应该输出什么"的最终约束：

五项关键职责

1. 设计可扩展、可维护的系统架构；
2. 用清晰的理由记录架构决策；
3. 绘制系统图与组件交互；
4. 评估技术选型与权衡；
5. 定义架构模式与原则。

最佳实践

• 关注非功能需求（性能、安全、可扩展性）；
• 为重大决策记录 ADR（Architecture Decision Records）——ruflo 仓库本身就是 ADR 文化的重用户，v3/docs/adr/ 与 v3/implementation/adrs/ 分别存有 177 篇和 91 篇 ADR 文档，该技能的 *.adr.md 触发模式正服务于这一工作流；
• 使用标准图示规范（C4、UML）；
• 面向未来扩展性思考；
• 考虑运维面（部署、监控）。

五类交付物：C4 架构图（首选）、组件交互图、数据流图、架构决策记录（ADR）、技术评估矩阵。

决策框架五问（每次做架构决策时的固定推演路径）：

1. 需要哪些质量属性（quality attributes）？
2. 约束与假设是什么？
3. 每个选项的权衡是什么？
4. 如何与业务目标对齐？
5. 风险是什么、缓解策略是什么？

这套"质量属性 → 约束 → 权衡 → 业务对齐 → 风险缓解"的推演链，本质上是 ATAM（架构权衡分析法）思路的提示词化表达，且与"只读源码、只写文档、人工审批"的权限设计闭环：Agent 负责推演与呈现权衡，拍板权留在人。

与 ruflo 其他架构角色的协同位置

把 SKILL 文件放回仓库全貌来看，架构能力在 ruflo 中存在三层递进的形态：

1. Agent 定义层：arch-system-design.md 提供纯提示词的 system-architect 角色；v3 侧 architect.yaml 则把架构能力抽象为带 system-design、api-design、documentation 三项 capability 和 context-caching、memory-persistence 两项优化的 v3 Agent 配置（version 3.0.0），说明 v3 体系下架构师是 swarm 中的一等角色；
2. 技能层：agent-arch-system-design/SKILL.md 在 Agent 定义之外补齐触发、权限、约束、钩子与集成拓扑，成为可被 $agent-arch-system-design 一键调度的完整技能包，其调用与启用受 .agents/config.toml 中 [[skills.config]] 段统一管理（该文件默认启用了 swarm-orchestration、memory-management、sparc-methodology、security-audit 四个技能，新增技能可照此追加）；
3. 协作层：通过 can_delegate_to 与 shares_context_with，system-architect 接入 ruflo 的文档 Agent、安全分析 Agent 与其他架构专职 Agent，构成"架构决策—文档落地—安全审查"的流水线。

小结：一个可复制的受控 Agent 技能范式

agent-arch-system-design 技能展示了 ruflo 为"高风险思考型任务"设计 Agent 技能时的一整套可复制范式：frontmatter 元数据定义触发面与资源配额，工具白/黑名单与路径约束划定行为边界，confirmation_required + requires_approval_from 把重大决策审批权交还人类，parallel_operations: false 用串行思考换取推演质量，生命周期钩子负责入场前盘点与出场后汇报，最后由 Markdown 提示词正文固化职责、交付物与决策框架。对于需要"读代码、出图、写 ADR、但不许动代码"的架构评审类 Agent，这套声明式配置（配合 .agents/README.md 描述的目录结构与 config.toml 的启用机制）是一个可以直接对照搬用的模板。