ruflo agent-coder 技能实战：从 YAML 钩子到 TDD 与 MCP 记忆协调，构建多智能体蜂群中的 Coder 角色

本篇以 ruflo 仓库中的 agent-coder 技能文件 为主体，完整拆解这个「代码实现专家」Agent 技能的结构与用法：你会掌握技能文件的双层 YAML 元数据（外层 skill 包装 + 内层 agent 角色定义）、pre/post 生命周期钩子的写法、TDD 与性能优化的实现规范，以及如何通过 MCP 记忆工具在多 Agent 蜂群中共享实现状态，并结合 MCP 工具兼容层源码 验证文档中每个工具调用的真实落点。

技能定位与调用方式

在 ruflo 中，Agent 技能统一放在 .agents 目录下，该目录面向 OpenAI Codex CLI 提供配置与技能定义。按照 .agents/README.md 的说明，技能通过 $skill-name 语法调用，每个技能目录包含一份 SKILL.md 指令文件，并可选地附带 scripts/ 与 docs/ 子目录。agent-coder 就是其中代表「实现专家」角色的一个技能，通过 $agent-coder 触发，其技能元数据描述为 "Agent skill for coder - invoke with $agent-coder"。

技能是否生效由 config.toml 控制。其中 [[skills.config]] 表数组按路径启用技能，例如仓库当前启用的是 swarm-orchestration、memory-management、sparc-methodology、security-audit 四个技能路径；如果要启用 agent-coder，可以参照同样的格式添加：

[[skills.config]]
path = ".agents/skills/agent-coder"
enabled = true

同一份配置还定义了技能运行时的整体环境，对理解 coder 技能的工作前提很重要：

• MCP 服务器接入：[mcp_servers.claude-flow] 通过 npx -y @claude-flow/cli@latest 启动 Claude Flow CLI 作为 MCP server，tool_timeout_sec = 120。技能文档中所有 mcp__claude-flow__* 工具调用都依赖这个通道。
• 审批与沙箱策略：approval_policy = "on-request"、sandbox_mode = "workspace-write"，即 coder 在请求重大变更时才会请求人工审批，文件写入被限制在工作区内。
• 蜂群编排参数：[swarm] 段配置了 default_topology = "hierarchical"、consensus = "raft"、anti_drift = true、checkpoint_interval = 10，这些决定了 coder 在分层拓扑蜂群中的协作环境。
• 性能与资源约束：[performance] 段限制 max_agents = 8、task_timeout = 300 秒、每个 agent 内存上限 512MB，coder 的产出需要落在这些运行时约束之内。

技能文件结构：双层 YAML 元数据 + 角色指令正文

SKILL.md 的开头连续出现两段 YAML frontmatter，这是该技能的关键结构，逐字段解读如下。

第一段（技能包装层）：

---
name: agent-coder
description: Agent skill for coder - invoke with $agent-coder
---

这是技能在技能注册体系中的身份：技能名为 agent-coder，调用入口为 $agent-coder。

第二段（Agent 角色定义层）：

---
name: coder
type: developer
color: "#FF6B35"
description: Implementation specialist for writing clean, efficient code
capabilities:
  - code_generation
  - refactoring
  - optimization
  - api_design
  - error_handling
priority: high
hooks:
  pre: |
    echo "💻 Coder agent implementing: $TASK"
    # Check for existing tests
    if grep -q "test\|spec" <<< "$TASK"; then
      echo "⚠️  Remember: Write tests first (TDD)"
    fi
  post: |
    echo "✨ Implementation complete"
    # Run basic validation
    if [ -f "package.json" ]; then
      npm run lint --if-present
    fi
---

各字段的含义与作用：

字段	取值	说明
name	coder	Agent 在蜂群中的角色名，与技能名 agent-coder 分离
type	developer	角色类型，用于蜂群按类型路由任务
color	#FF6B35	角色的标识色，多 agent 编排时用于可视化区分
description	实现专家定位	一句话说明该角色职责
capabilities	5 项能力	code_generation、refactoring、optimization、api_design、error_handling，调度器据此匹配任务
priority	high	角色优先级，高优先级角色会优先被分配到任务

hooks 字段是这份技能最有实操价值的部分。它声明了两段 shell 生命周期脚本：

• pre 钩子在任务开始前执行：打印当前任务（$TASK 环境变量由调度层注入），并检测任务描述中是否出现 "test" 或 "spec" 字样——如果出现，就提示"先写测试（TDD）"。这是一个轻量级的流程约束：把 TDD 纪律从「靠自觉」变成「钩子里的硬检查」。
• post 钩子在任务完成后执行：打印完成提示，并在项目存在 package.json 时运行 npm run lint --if-present。--if-present 保证脚本在缺少 lint script 的项目里不会报错退出，属于典型的防御性写法。

这两段钩子对应了 config.toml 中 [hooks] 段开启的 pre_task / post_task 生命周期机制——全局开关打开后，各技能自带的 pre/post 脚本才会被真正执行。

核心职责与实现规范

技能正文以角色设定开头：coder 是一名「编写干净、可维护、高效代码的资深软件工程师」。它声明了五项核心职责：

1. 代码实现：编写满足需求的生产级代码；
2. API 设计：创建直观且有完善文档的接口；
3. 重构：在不改变功能的前提下改进既有代码；
4. 优化：在保持可读性的前提下提升性能；
5. 错误处理：实现健壮的错误处理与恢复机制。

代码质量标准

文档给出了四条「必须遵循」的 TypeScript 范式，这里完整保留并逐条说明：

// 清晰的命名
const calculateUserDiscount = (user: User): number => {
  // Implementation
};

// 单一职责
class UserService {
  // Only user-related operations
}

// 依赖注入
constructor(private readonly database: Database) {}

// 错误处理
try {
  const result = await riskyOperation();
  return result;
} catch (error) {
  logger.error('Operation failed', { error, context });
  throw new OperationError('User-friendly message', error);
}

四条范式分别对应：动词 + 业务对象的函数命名（calculateUserDiscount 而非 doCalc）；类只做一件事（UserService 只承载用户相关操作）；通过构造函数注入依赖并保持 readonly（便于替换为 mock 做测试）；异常路径先记录带上下文的日志，再抛出携带用户友好信息的自定义错误（OperationError 包装原始 error 作为 cause），保证日志可追溯、调用方可读。

设计原则

• SOLID：设计类时始终应用五条原则；
• DRY：通过抽象消除重复；
• KISS：实现保持简单、聚焦；
• YAGNI：需要之前不添加功能。

性能考量

// 优化热路径
const memoizedExpensiveOperation = memoize(expensiveOperation);

// 使用高效数据结构
const lookupMap = new Map<string, User>();

// 批量操作
const results = await Promise.all(items.map(processItem));

// 懒加载
const heavyModule = () => import('./heavy-module');

四条技术分别针对不同瓶颈：昂贵操作的记忆化、字符串键查找用 Map 的 O(1) 哈希结构、用 Promise.all 把串行等待变为并发批量、用动态 import 实现模块懒加载以减小首屏体积。这四条是 coder 角色在"优化"能力项下被要求默认执行的检查清单。

实现流程：从需求到增量交付

技能正文把实现过程固定为四个阶段，这也是它区别于"随手写代码"的关键。

阶段一：理解需求

通读规格说明、编码前先澄清歧义、预先考虑边界情况与错误场景。

阶段二：设计先行

先规划架构、定义接口与契约、考虑可扩展性——即"design first"，避免边写边改接口。

阶段三：测试驱动开发

文档给出了一对「先测试、后实现」的最小完整示例：

// 先写测试
describe('UserService', () => {
  it('should calculate discount correctly', () => {
    const user = createMockUser({ purchases: 10 });
    const discount = service.calculateDiscount(user);
    expect(discount).toBe(0.1);
  });
});

// 再实现
calculateDiscount(user: User): number {
  return user.purchases >= 10 ? 0.1 : 0;
}

测试里用 createMockUser 隔离了数据依赖（对应后文"mock 外部依赖"的实践），断言钉死了业务规则（10 次购买 → 10% 折扣），实现则是让测试通过的最小逻辑。这与 pre 钩子里的 TDD 提示形成呼应：钩子在流程层提醒，本节在规范层落地。

阶段四：增量实现

从核心功能起步，增量添加功能，持续重构。

代码风格与文件组织

TypeScript/JavaScript 风格

// 使用现代语法
const processItems = async (items: Item[]): Promise<Result[]> => {
  return items.map(({ id, name }) => ({
    id,
    processedName: name.toUpperCase(),
  }));
};

// 正确的类型标注
interface UserConfig {
  name: string;
  email: string;
  preferences?: UserPreferences;
}

// 错误边界
class ServiceError extends Error {
  constructor(message: string, public code: string, public details?: unknown) {
    super(message);
    this.name = 'ServiceError';
  }
}

要点有三：箭头函数 + 解构的现代写法、可选字段显式用 ? 标注、以及统一的 ServiceError 错误边界——它扩展 Error，携带机器可读的 code 和任意 details，让上层可以按 code 分支处理而不是解析错误消息字符串。

文件组织

src/
  modules/
    user/
      user.service.ts      # 业务逻辑
      user.controller.ts   # HTTP 处理
      user.repository.ts   # 数据访问
      user.types.ts        # 类型定义
      user.test.ts         # 测试

按模块（user/）聚合，模块内按职责分层：service 装业务逻辑、controller 装 HTTP 处理、repository 装数据访问、types 装类型定义，测试文件与实现文件同名并置（user.test.ts）。这种"一个模块一个目录、一层一个文件"的组织方式，与前面依赖注入、单一职责的规范是配套的——分层清晰才能让依赖方向可控。

最佳实践清单

技能把最佳实践归纳为四组可核查的条目：

安全

• 绝不硬编码密钥；
• 验证所有输入；
• 净化输出；
• 使用参数化查询；
• 实现正确的身份认证与授权。

对照 config.toml 的 [security] 段可以看到平台层的配套实现：input_validation = true 开启输入校验、secret_scanning = true 扫描硬编码密钥、blocked_patterns 正则屏蔽 .env、credentials.json、.pem、.key 等敏感文件。也就是说，文档中"绝不硬编码密钥"的要求在配置层有扫描兜底。

可维护性

编写自文档化代码；复杂逻辑加注释；函数保持短小（少于 20 行）；使用有意义的变量名；保持风格一致。

测试

追求 80% 以上覆盖率；覆盖边界情况；mock 外部依赖；编写集成测试；保持测试快速且相互隔离。

文档

/**
 * 根据用户的购买历史计算折扣率
 * @param user - 包含购买信息的用户对象
 * @returns 折扣率小数（0.1 = 10%）
 * @throws {ValidationError} 当用户数据无效时
 * @example
 * const discount = calculateUserDiscount(user);
 * const finalPrice = originalPrice * (1 - discount);
 */

JSDoc 模板要求覆盖 @param、@returns、@throws 与 @example 四要素，保证 API 文档与实现同步可验证。

MCP 工具集成：源码级验证

技能文档的最后一块是「MCP Tool Integration」，定义了 coder 在蜂群中的三类 MCP 调用。逐条对照 v2-compat-tools.ts 的实现，可以确认其真实行为与演进状态。

记忆协调（memory_usage）

技能文档中的用法是三类调用：

// 上报实现状态
mcp__claude-flow__memory_usage {
  action: "store",
  key: "swarm$coder$status",
  namespace: "coordination",
  value: JSON.stringify({
    agent: "coder",
    status: "implementing",
    feature: "user authentication",
    files: ["auth.service.ts", "auth.controller.ts"],
    timestamp: Date.now()
  })
}

// 共享代码决策
mcp__claude-flow__memory_usage {
  action: "store",
  key: "swarm$shared$implementation",
  namespace: "coordination",
  value: JSON.stringify({
    type: "code",
    patterns: ["singleton", "factory"],
    dependencies: ["express", "jwt"],
    api_endpoints: ["$auth$login", "$auth$logout"]
  })
}

// 查询依赖
mcp__claude-flow__memory_usage {
  action: "retrieve",
  key: "swarm$shared$dependencies",
  namespace: "coordination"
}

从 v2-compat-tools.ts 的 memory_usage 工具定义 可以看到，这是一个 V2 兼容工具（deprecated: true），其输入参数与行为如下：

• action：枚举 store / retrieve / delete / list，必填；
• key：记忆键；value：store 时写入的值；namespace：记忆命名空间，默认 coordination；
• store 会转发给 storeMemoryTool，且实际存储键被改写为 ${namespace}/${key} 形式（即 coordination/swarm$coder$status），并附带 metadata: { namespace }；
• retrieve 转发给 searchMemoryTool，以 key 作为查询、limit: 1 取第一条命中，返回 { found, value, key } 三元组；
• delete 通过写入 null 值并打上 deleted: true 元数据实现软删除；
• list 转发给 listMemoryTool，detail: "detailed" 时取 100 条，否则 20 条。

文件头的映射注释明确写着 memory_usage -> memory/store or memory/search，并且 mapV2ToV3ToolName 中 'memory_usage': 'memory/store'。也就是说，技能文档中的 V2 风格调用在运行时会被兼容层透明地转译为 V3 的 memory/store、memory/search、memory/list 工具——旧技能文档无需改动即可在新版本上运行，这是该兼容层存在的意义。

性能监控（benchmark_run 与 bottleneck_analyze）

文档中的调用示例：

// 跟踪实现指标
mcp__claude-flow__benchmark_run {
  type: "code",
  iterations: 10
}

// 分析瓶颈
mcp__claude-flow__bottleneck_analyze {
  component: "api-endpoint",
  metrics: ["response-time", "memory-usage"]
}

对照 benchmark_run 工具的 V2 兼容实现，有几点值得注意：

1. benchmark_run 同样是 deprecated 的 V2 兼容工具，映射目标是 V3 的 system/metrics（见 文件头映射注释 与 mapV2ToV3ToolName 中 'benchmark_run': 'system/metrics'）。
2. 当前工具 schema 的 type 枚举为 all / wasm / swarm / agent / task（默认 all），iterations 取值 1–100（默认 10）。技能文档示例中的 type: "code" 不在当前枚举内——从源码结构看，文档示例对应的是更早版本的工具参数集，迁移到新 MCP 层时建议改用 swarm、agent 或 task 等枚举值。
3. 关于 bottleneck_analyze：在当前 v3/mcp 工具目录中检索不到同名工具实现，可以推断它属于文档沿用下来的旧版性能工具名，其职能在当前版本由 system/metrics 承担。这一点在使用文档示例时应以仓库当前工具集为准。

蜂群协作：coder 在整体编队中的位置

技能文档的 Collaboration 一节规定了 coder 与其他角色的协作契约：

• 与 researcher 协调获取上下文；
• 遵循 planner 的任务分解；
• 向 tester 提供清晰的交接；
• 把假设与决策记录到记忆中；
• 不确定时请求评审；
• 所有实现决策通过 MCP 记忆工具共享。

最后那句收尾原则值得单独强调："Good code is written for humans to read, and only incidentally for machines to execute."——代码首先是写给人读的，机器执行只是附带结果。

从仓库结构看，这份协作约定是有落地支撑的：.agents/skills 目录下并列存在 agent-researcher、agent-planner、agent-tester、agent-reviewer 等约百个角色技能，coder 是这条 researcher → planner → coder → tester 流水线中的实现环节；而 config.toml 的 [swarm] 段（分层拓扑 + Raft 共识 + 反漂移检查点）与 [workers] 段（audit/optimize/consolidate 三个后台工作器）则提供了这条流水线运行的编排与后台维护环境。

小结与使用前提

把 agent-coder 技能 串起来看，它由四层构成：

1. 元数据层（双层 YAML）：$agent-coder 调用入口 + coder 角色的能力、优先级声明；
2. 钩子层（pre/post shell 脚本）：TDD 提醒与 lint 校验，把流程纪律自动化；
3. 规范层（正文指令）：代码质量范式、SOLID/DRY/KISS/YAGNI、性能手段、四阶段实现流程、TS 风格与文件组织、安全/可维护性/测试/文档清单；
4. 集成层（MCP 调用）：通过 memory_usage（V2 兼容，实际落到 memory/store、memory/search）在蜂群内共享实现状态与代码决策，通过性能工具跟踪指标。

使用前提与限制：技能运行依赖 Codex CLI 读取 .agents/config.toml 完成配置，且 [mcp_servers.claude-flow] 的 MCP 通道可用；文档中的 memory_usage、benchmark_run 属于 V2 兼容工具，当前版本已标记 deprecated，新代码应优先使用 V3 的 memory/store、memory/search、system/metrics 等工具名，参数取值以 v2-compat-tools.ts 中的 schema 为准。