ruflo 中 sparc-coder 实现专家 Agent：从规范到可测试代码的 TDD 工作流与技能落地实践

ruflo 的 .agents/skills/ 目录承载了大量可被 $ 语法调用的 Agent 技能，其中 agent-implementer-sparc-coder/SKILL.md 定义了 SPARC 方法论中“实现阶段”的专家 Agent：它负责把上游产出的规范（Specification）与设计（Architecture）转化为高质量、带测试的代码。本文完整解读该技能的 YAML 元数据与 pre/post 钩子、Red-Green-Refactor 三阶段 TDD 工作流、服务/路由/测试三类代码模式，并结合仓库中的 MCP Agent 注册表、SPARC 协调器技能与初始化模板，说明该 Agent 在 ruflo 多智能体体系中的真实落位与调用方式。

一、sparc-coder 在 ruflo Agent 体系中的定位

ruflo 的技能目录结构在 .agents/README.md 中有明确约定：每个技能是一个目录，核心是 SKILL.md（含 YAML frontmatter 元数据、触发/跳过条件、命令与示例），并可附带 scripts/ 与 docs/ 子目录；技能通过 $skill-name 语法调用。sparc-coder 正是遵循该约定的一个开发类（type: development）技能。

从源码结构看，它并不是孤立存在的。ruflo 的 MCP 工具层在 agent-tools.ts 中维护了一份 ALLOWED_AGENT_TYPES 白名单，用于校验 spawn 请求、防止任意类型注入，其中明确列出了 SPARC 方法论一族的 6 个 Agent 类型：

// SPARC Methodology
'sparc-coord', 'sparc-coder', 'specification', 'pseudocode',
'architecture', 'refinement',

这意味着 sparc-coder 是一个受约束的、可被 MCP agent/spawn 工具合法拉起的一等 Agent 类型；同样的类型列表也出现在 CLI 初始化模板生成的文档中（见 executor.ts 中 “SPARC Methodology (6)” 分组）。在 SPARC 五阶段（Specification → Pseudocode → Architecture → Refinement → Completion）中，sparc-coder 的职责聚焦在 Refinement 阶段的落地执行，而跨阶段编排则由姊妹技能 agent-sparc-coordinator/SKILL.md 负责。

二、技能元数据与生命周期钩子解剖

SKILL.md 由两层 YAML frontmatter 组成：外层是技能包装（name: agent-implementer-sparc-coder，声明“通过 $agent-implementer-sparc-coder 调用”），内层才是 Agent 本体定义：

字段	取值	含义
name	sparc-coder	Agent 类型名，与 MCP 白名单中的类型对应
type	development	开发类 Agent
color	blue	标识色（可视化/展示用途）
description	Transform specifications into working code with TDD practices	一句话职责
capabilities	code-generation / test-implementation / refactoring / optimization / documentation / parallel-execution	六项能力
priority	high	高优先级

hooks 字段定义了两段 shell 生命周期脚本，是该技能最具工程细节的部分：

pre 钩子（进入实现前）：打印启动横幅、预告 TDD 流程（Red → Green → Refactor），并检查工程测试目录约定——若 tests、test、__tests__ 三者均不存在，则记录“实现过程中将创建测试目录”。这相当于在 Agent 开始写码前先做一次项目测试基建的探测。

post 钩子（实现完成后）：按项目类型自适应地验证实现——

if [ -f "package.json" ]; then
  npm test --if-present
elif [ -f "pytest.ini" ] || [ -f "setup.py" ]; then
  python -m pytest --version > $dev$null 2>&1 && python -m pytest -v || echo "pytest not available"
fi

即 Node 项目走 npm test --if-present，Python 项目走 pytest -v，并在末尾声明“实现指标已写入 memory”。从这段钩子可以看出该技能的设计取向：把“测试通过”作为实现完成的机器可验证判据，而不是仅凭 Agent 自述。

三、核心实现原则

原文档定义了三大原则，构成该 Agent 的行为约束：

1. 测试驱动开发（TDD）：先写失败测试（Red）→ 写最小实现使其通过（Green）→ 重构提升质量（Refactor），并要求维持高于 80% 的测试覆盖率；
2. 并行实现：同时创建多个测试文件、并行实现相关特性、批量文件操作、协调多组件变更；
3. 代码质量标准：整洁可读、命名一致、完善的错误处理、完备的文档、性能优化。

这三条原则与仓库全局配置是呼应的：.agents/config.toml 的 [performance] 段开启了 parallel_execution = true 并设置 max_agents = 8，[swarm] 段默认 default_topology = "hierarchical"——这正是 sparc-coder “并行实现 + 层级协调”原则的运行环境前提。

四、三阶段实现工作流（Red → Green → Refactor）

技能正文将实现工作流组织为三个阶段，每个阶段都强调并行文件操作。原文档使用 $ 作为路径分隔符的伪代码语法（如 tests$unit$auth.test.js），表达“并行写多个文件后再统一验证”的批次语义，这里完整保留：

Phase 1：测试创建（Red）

[Parallel Test Creation]:
  - Write("tests$unit$auth.test.js", authTestSuite)
  - Write("tests$unit$user.test.js", userTestSuite)
  - Write("tests$integration$api.test.js", apiTestSuite)
  - Bash("npm test")  // Verify all fail

要点：同一批写入单元、集成多层级测试，然后运行测试套件确认全部失败——这是 TDD 的 Red 判据，确保测试不是“测空气”而是真实锁定了尚未实现的行为。

Phase 2：实现（Green）

[Parallel Implementation]:
  - Write("src$auth$service.js", authImplementation)
  - Write("src$user$model.js", userModel)
  - Write("src$api$routes.js", apiRoutes)
  - Bash("npm test")  // Verify all pass

实现文件按组件切分（service / model / routes）并行产出，再次全量跑测试，目标是全部通过。

Phase 3：精炼（Refactor）

[Parallel Refactoring]:
  - MultiEdit("src$auth$service.js", optimizations)
  - MultiEdit("src$user$model.js", improvements)
  - Edit("src$api$routes.js", cleanup)
  - Bash("npm test && npm run lint")

在测试与 lint 双重守护下做重构，npm test && npm run lint 是退出门。值得注意的是，Phase 3 使用 MultiEdit/Edit 而非 Write，从操作动词上区分了“新建”与“原地修改”两类文件操作，这也呼应了 capabilities 中单列的 parallel-execution 与 refactoring 能力。

这套流程的上游输入来自 SPARC 协调器：agent-sparc-coordinator/SKILL.md 定义了“Architecture → Quality Gate 3 → Refinement”的阶段迁移，以及 5 个专业化 Agent（Researcher / Designer / Coder / Tester / Documenter）的分工——sparc-coder 对应的就是其中的 “SPARC Coder: Implementation and refinement”，其交付物（tested code）会经过 “Quality Gate 4：Tests pass, coverage adequate” 才能进入 Completion 阶段。

五、内置代码模式

技能内置了三类可直接套用的代码模式，这是该文档从“方法论描述”走向“可复制实现”的关键部分。

1. 服务实现模式：依赖注入 + 错误处理

// Pattern: Dependency Injection + Error Handling
class AuthService {
  constructor(userRepo, tokenService, logger) {
    this.userRepo = userRepo;
    this.tokenService = tokenService;
    this.logger = logger;
  }

  async authenticate(credentials) {
    try {
      // Implementation
    } catch (error) {
      this.logger.error('Authentication failed', error);
      throw new AuthError('Invalid credentials');
    }
  }
}

构造器注入（userRepo、tokenService、logger）使依赖可被 mock，这正是 Phase 1 能“先写测试”的前提；捕获后先记录日志、再抛出领域错误（AuthError），保证调用方拿到的是语义化异常而非底层堆栈。

2. API 路由模式：校验 + 限流 + 统一错误出口

// Pattern: Validation + Error Handling
router.post('$auth$login',
  validateRequest(loginSchema),
  rateLimiter,
  async (req, res, next) => {
    try {
      const result = await authService.authenticate(req.body);
      res.json({ success: true, data: result });
    } catch (error) {
      next(error);
    }
  }
);

中间件顺序（schema 校验 → 限流 → 业务处理）体现了“防御前置”；成功响应固定为 { success, data } 包裹结构；失败一律 next(error) 交给全局错误处理，避免在路由层吞掉异常。

3. 测试模式：完整覆盖 Arrange/Act/Assert

// Pattern: Comprehensive Test Coverage
describe('AuthService', () => {
  let authService;

  beforeEach(() => {
    // Setup with mocks
  });

  describe('authenticate', () => {
    it('should authenticate valid user', async () => {
      // Arrange, Act, Assert
    });

    it('should handle invalid credentials', async () => {
      // Error case testing
    });
  });
});

模式要求同一被测面同时覆盖正常路径与错误路径（对应上面服务的 AuthError 分支），beforeEach 统一装配 mock，保证每个用例隔离。

六、代码组织与实现守则

技能规定实现侧的目录结构按特性（feature）划分，并附共享层与基础设施层：

src/
  ├── features/        # Feature-based structure
  │   ├── auth/
  │   │   ├── service.js
  │   │   ├── controller.js
  │   │   └── auth.test.js
  │   └── user/
  ├── shared/          # Shared utilities
  └── infrastructure/  # Technical concerns

测试文件与实现文件同目录共存（auth.test.js 在 auth/ 内），降低了 Red 阶段新建测试文件时的路径决策成本。

实现守则归纳为五条经典原则：单一职责（每个函数/类只做一件事）、DRY（不重复自己）、YAGNI（不提前造用不上的东西）、KISS（保持简单）、SOLID。这五条与 TDD 覆盖率 >80% 的要求共同构成 Phase 3 重构时判断“值得改 / 不值得改”的准绳。

七、集成模式：sparc-coder 与协作 Agent 的边界

原文档明确列出了三组集成关系，划清了 Agent 之间的职责边界：

• 与 SPARC Coordinator：接收规范与设计、上报实现进度、需要时请求澄清、交付带测试的代码——即 sparc-coder 不自己决定“做什么”，只负责“做出来并证明做对了”；
• 与 Testing Agents：协调测试策略、保证覆盖率要求、处理测试自动化、校验质量指标；
• 与 Code Review Agents：准备可评审代码、处理反馈、落实建议、维持标准。

这与协调器技能中的 “Parallel Execution Patterns”（为独立组件 spawn 多个 Agent、在阶段边界同步）互相印证：实现并行发生在组件粒度，同步发生在阶段边界。

八、性能优化与错误处理模式

性能优化三板斧

技能将性能优化拆为算法、数据库、API 三层：算法层关注高效数据结构、时间/空间复杂度、适时缓存；数据库层关注查询效率、索引、连接池；API 层关注响应压缩、分页、缓存策略、限流。

优雅降级（Graceful Degradation）

// Fallback mechanisms
try {
  return await primaryService.getData();
} catch (error) {
  logger.warn('Primary service failed, using cache');
  return await cacheService.getData();
}

主链路失败时显式降级到缓存，并留下 warn 级日志——降级本身是“被记录的”，而不是静默的。

指数退避重试（Error Recovery）

// Retry with exponential backoff
async function retryOperation(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

默认 3 次重试、间隔 2^i × 1000ms（1s → 2s → 4s），最后一次失败直接上抛。这是典型的瞬态错误处理模板，适用于调用 LLM、向量库等不稳定的外部依赖场景。

文档标准

代码级要求 JSDoc 式注释覆盖参数、返回与抛错（原文档给出的 authenticate 注释示例列出了 credentials.email、credentials.password、@returns {Promise<Object>} 与 @throws {AuthError}）；项目级要求 README 同步更新 API 文档、安装说明、配置项与使用示例。文档不是实现后的“可选附件”，而是 Completion 判据的一部分。

九、仓库级实操：如何驱动 SPARC 流程与验证该 Agent

通过 SPARC 技能命令进入 Refinement 阶段

配套的 sparc-methodology/SKILL.md 给出了五阶段的统一入口——通过 hooks route 将带阶段前缀的任务路由给对应 Agent。与 sparc-coder 最直接相关的两条命令是：

# Refinement 阶段：迭代设计（进入实现前的最后一道规划）
npx @claude-flow/cli hooks route --task "refinement: add rate limiting and brute force protection"

# Completion 阶段：测试 + 文档收尾
npx @claude-flow/cli hooks route --task "completion: verify all tests pass, update API docs, security review"

也可以显式拉起 SPARC 协调器来统筹整个循环：

npx @claude-flow/cli agent spawn --type sparc-coord --name sparc-lead

该技能在 .agents/config.toml 中已被注册启用（[[skills.config]] 段中 path = ".agents/skills/sparc-methodology"，enabled = true）。

用官方脚本初始化与审查 SPARC 工件

sparc-methodology 技能自带两个 shell 脚本，为 TDD 工作流提供了工件骨架与检查清单：

sparc-init.sh 接收特性名（默认 new-feature），在 ./docs/sparc/<feature>/ 下创建五个阶段占位文件：

1-specification.md  2-pseudocode.md  3-architecture.md  4-refinement.md  5-completion.md

sparc-review.sh 则对给定目录做五阶段清单检查，逐项输出 [x] found / [ ] missing。也就是说，sparc-coder 开工前可以用 sparc-init 建立文档骨架、收工后用 sparc-review 验证 4-refinement 阶段工件齐备——这与其“Documentation Standards”章节形成闭环。

回归测试中对 Agent 可加载性的验证

仓库的 Docker 回归脚本 test-agents.sh 中包含统一的 test_agent() 函数，通过 npx claude-flow agent info <name> 验证每个 Agent 是否存在且可加载，并对 V3 专业化 Agent 批量执行同类检查。从该脚本结构可以推断，sparc-coder 这类注册在 ALLOWED_AGENT_TYPES 中的类型同样落在“必须可被 info 查询”的验收范围内。

十、小结

agent-implementer-sparc-coder/SKILL.md 是 ruflo SPARC 方法论中把“设计”变成“可运行、可测试代码”的执行层：它用 pre/post 钩子把测试目录探测与“测试通过”判据固化进 Agent 生命周期，用三阶段并行 TDD 工作流规范文件操作批次，用服务/路由/测试三类模式保证产出代码的结构质量，并通过与 SPARC 协调器、测试 Agent、评审 Agent 的边界划分融入多智能体流水线。仓库中 v3/mcp/tools/agent-tools.ts 的类型白名单、sparc-methodology 技能的路由命令与 init/review 脚本、以及 docker 回归中的 Agent 可加载性测试，共同构成了该技能从定义、调用到验证的完整证据链。