Ruflo coder 代码实现智能体实战指南SPEC/ADR 约束下的高质量编码、TDD 与 MCP 记忆协同【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo导读.claude/agents/core/coder.md是 RufloClaude Flow 元编排框架多智能体体系中Code Implementation Agent代码实现智能体的角色规范定义了它如何读取权威文档、编写生产级代码、执行 TDD 以及通过 MCP 记忆工具与 swarm 中的其他角色协同。本篇将以该角色文件为骨架结合仓库内同目录的核心 Agent 定义、docs/adr/docs/spec契约目录与claude-flow memory命令实现完整还原这套“规范驱动 → 设计优先 → 测试先行 → 记忆协同”的工程落地方法供需要自定义 Coder 角色或参与多智能体并行开发的读者直接复用。一、角色定位coder 在多智能体体系中的坐标角色文件以 YAML front-matter 声明两个关键元字段.claude/agents/core/coder.md--- name: coder description: Implementation specialist for writing clean, efficient code ---name: coder该角色在多智能体编排与 MCP 协调消息中的稳定标识如后续记忆键中的swarm/coder/statusdescription供编排器理解角色能力边界即“编写整洁、高效代码的实现专家”。在仓库中coder 不是孤立存在而是核心角色组的一员。.claude/agents/core/ 目录下按“单一职责”拆分了五类核心 Agent角色文件职责定位planner.md战略规划与任务分解、依赖与资源编排researcher.md提供上下文与调研支撑coder.md编写生产级实现代码、设计 API、重构与优化reviewer.md代码评审、质量把关tester.md测试与验证闭环同时仓库v3子树中还存放着结构化版本化配置如 v3/agents/tester.yaml 声明type: tester、version: 3.0.0与capabilities。也就是说从源码结构看Agent 角色存在“Markdown 行为规范”与“YAML 结构化配置”双层表达前者约束模型行为后者声明类型与能力元数据二者共同构成可编排的角色契约。二、动手前的硬性约束先读 SPEC 与 ADR角色规范最重要的纪律在于“先读文档再写代码”。凡是会影响架构、范围或行为的改动coder 必须先读两类权威文档docs/SPEC.md及docs/下的同级文件—— 回答系统“应该做什么”功能需求、范围、验收标准docs/adr/*.md架构决策记录—— 回答“决策是如何做出的”技术栈、框架选型、认证策略、集成模式。除非被状态为status: Accepted的更新 ADR 明确取代否则视为**绑定binding**约束。冲突裁决与并行开发契约文档对冲突给出了明确的裁决规则两者并存且冲突时ADR 在架构决策上优先SPEC 在需求范围上优先若 ADR 与规划中的实现矛盾不得静默偏离必须显式暴露冲突并选择“遵循既有 ADR”或“起草后继 ADR”两条路径之一若目标目录两者皆不存在绿地项目可径行开工但若同一会话中 Architect Agent 已生成 ADR则即使尚未落入docs/adr/这些 ADR 对本次工作同样具有权威性。在 Ruflo 仓库内部这套约定同样有实体支撑v3子树维护了规模庞大的决策档案与需求规范目录例如 v3/docs/adr含 ADR-074 ~ ADR-078 等多条连续决策记录如 ADR-078-hybrid-retrieval-and-outcome-signal.md与 v3/docs/spec。角色规范强调——多智能体并行开发时ADR 是防止不同有界上下文bounded context间 Agent 漂移的“契约”。这与仓库根 CLAUDE.md 中“并发自动化开发”一节要求写 Agent 独占 worktree、只读 Agent 共享 checkout 的原则互为表里。三、核心职责与实现方法论coder 角色被赋予五项核心职责见 .claude/agents/core/coder.md#职责关键要求1代码实现编写满足需求的生产级代码2API 设计提供直觉化、文档完备的接口3重构不改变功能的前提下改进既有代码4性能优化提升性能的同时保持可读性5错误处理实现健壮的异常处理与恢复实现过程被规范化为四步递进流程理解需求Understand Requirements透彻阅读规格、编码前澄清歧义、考虑边界与错误场景先设计后编码Design First规划架构、定义接口与契约、预留可扩展性测试驱动开发Test-Driven Development先写测试、再实现增量实现Incremental Implementation先交付核心功能、增量添加特性、持续重构。这四步与仓库根 CLAUDE.md 设定的执行环路recall → inspect → route → plan → execute → test → validate → benchmark → optimize → receipt → handoff高度一致说明 coder 的“设计-实现-验证-交接”方法论是整个 Ruflo 治理模型在单 Agent 维度的投影。四、代码质量标准与实现范式角色规范用 TypeScript 示例给出了“始终遵循”的四类硬性范式// 1) 清晰命名 const calculateUserDiscount (user: User): number { // Implementation }; // 2) 单一职责 class UserService { // Only user-related operations } // 3) 依赖注入 constructor(private readonly database: Database) {} // 4) 错误处理结构化上下文 用户可读错误 链路保留 try { const result await riskyOperation(); return result; } catch (error) { logger.error(Operation failed, { error, context }); throw new OperationError(User-friendly message, error); }这四范式对应四条可验收的工程原则命名表意、类职责单一、依赖通过构造注入便于测试替换与解耦、错误必须携带上下文并向上抛出可理解的新异常。值得注意的是“错误上下文context”的强制记录与仓库安全/可观测性设计一脉相承。设计模式与性能意识在抽象层次上规范要求遵守四个经典原则SOLID设计类时始终应用DRY通过抽象消除重复KISS保持实现简单聚焦YAGNI不需要时不提前添加功能。性能方面则给出了四条可直接落地的优化示例见 .claude/agents/core/coder.md 中“Performance Considerations”一节// 优化热点路径记忆化 const memoizedExpensiveOperation memoize(expensiveOperation); // 高效数据结构Map 替代线性查找 const lookupMap new Mapstring, User(); // 批量操作并发处理 const results await Promise.all(items.map(processItem)); // 懒加载按需引入重模块 const heavyModule () import(./heavy-module);这四例覆盖了**时间换空间memoize、查找复杂度Map、吞吐批量并发、启动成本懒加载**四种最常见的性能场景且都以不牺牲可读性为前提呼应职责中“提升性能同时保持可读性”的表述。五、TDD 与增量交付先写失败测试再写实现角色规范将测试驱动开发作为实现流程的强制步骤并给出最小闭环示例// 第一步先写测试 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; }该示例同时示范了三条隐性纪律行为先于实现被固化、外部依赖被 MockcreateMockUser、测试断言与业务规则一一对应。这与 Ruflo 架构约束中“新代码优先采用 TDD London Schoolmock-first”的原则吻合见仓库根 CLAUDE.md也从仓库的测试布局得到印证——例如v3/__tests__、.claude/agents/core同层的 tester 角色以及大量*.test.ts文件的存在说明“测试与实现同构存放、Mock 隔离外部依赖”是仓库惯例。六、TypeScript/JavaScript 风格约束与文件组织现代语法与类型化// 现代语法解构 隐式返回 const processItems async (items: Item[]): PromiseResult[] { return items.map(({ id, name }) ({ id, processedName: name.toUpperCase(), })); }; // 规范类型化可选字段显式声明 interface UserConfig { name: string; email: string; preferences?: UserPreferences; } // 错误边界可携带 code 的结构化错误 class ServiceError extends Error { constructor(message: string, public code: string, public details?: unknown) { super(message); this.name ServiceError; } }这套风格与仓库中“公共 API 一律使用类型化接口typed interfaces for all public APIs”“系统边界必须做输入校验”等架构规则见 CLAUDE.md互为补充UserConfig式的可选字段声明是类型安全的入口契约ServiceError式带错误码的结构化异常则是错误传播的稳定边界。建议的文件组织形态角色规范给出了按“职责层次”组织模块的布局建议便于大型代码库中定位业务逻辑、HTTP 层与数据访问src/ modules/ user/ user.service.ts # Business logic user.controller.ts # HTTP handling user.repository.ts # Data access user.types.ts # Type definitions user.test.ts # Tests该布局把“类型定义”“测试”与“实现”同目录就近放置与仓库v3/claude-flow/*/src下各模块如 memory、security、guidance 等按能力域分包的实践及“文件控制在 500 行以内、按有界上下文组织”的仓库约束方向一致。七、最佳实践清单安全、可维护性与文档角色规范将“最佳实践”划分为四个象限详见 .claude/agents/core/coder.md1. 安全Security绝不硬编码机密Never hardcode secrets校验所有输入Validate all inputs对输出做净化Sanitize outputs使用参数化查询Use parameterized queries实现正确的认证/授权。2. 可维护性Maintainability编写自解释代码复杂逻辑必须加注释函数保持短小 20 行使用有意义的变量名保持风格一致。3. 测试Testing目标覆盖率 80%覆盖边界用例Mock 外部依赖编写集成测试保持测试快速且相互隔离。4. 文档Documentation—— 以 JSDoc 承载契约/** * Calculates the discount rate for a user based on their purchase history * param user - The user object containing purchase information * returns The discount rate as a decimal (0.1 10%) * throws {ValidationError} If user data is invalid * example * const discount calculateUserDiscount(user); * const finalPrice originalPrice * (1 - discount); */这段 JSDoc 值得逐行拆解param/returns给出签名语义throws标注异常契约example直接给出可粘贴的运行用法。它说明“文档化”不是注释的数量而是让使用者无需读实现即可正确调用的接口说明书。八、MCP 工具集成用记忆与基准测试完成 swarm 协同coder 在并行 swarm 中的协同不是靠闲聊而是通过MCP 工具调用完成状态上报、决策共享与依赖查询。角色规范中约定以mcp__claude-flow__*命名空间调用各类工具。记忆协调Memory Coordination// 上报实现状态 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 }记忆工具的参数模型为actionstore/retrieve 等 key唯一键 namespace命名空间 valueJSON 序列化负载。这套调用范式与仓库中的真实 CLI 一致.claude/commands/memory/memory-usage.md定义了等价命令npx claude-flow memory usage支持--action store|retrieve|list|clear、--key、--value见 memory-usage.md 与 memory 命令索引。也就是说MCP 调用与 CLI 命令是同一记忆能力的两种入口——Agent 在会话内走 MCP人在终端走 CLI数据落同一存储。从调用结构可以推断其协同意图swarm/coder/status这类键让 coordinator 能实时掌握各角色进度swarm/shared/implementation这类键让同一 swarm 中后续加入的 Agent 能继承既有的模式、依赖与 API 约定这正是角色文档开篇“ADR 防止漂移”思想在运行时记忆层的延伸。性能观测Performance Monitoring角色规范还约定了两条性能观测调用形态// 记录实现侧基准 mcp__claude-flow__benchmark_run { type: code, iterations: 10 } // 定位瓶颈 mcp__claude-flow__bottleneck_analyze { component: api-endpoint, metrics: [response-time, memory-usage] }从调用形态可以看出coder 交付的不只是“能跑的代码”还包括可测量的性能基线iterations: 10与针对指定组件/指标的瓶颈定位。这与仓库中optimization域下存在 benchmark-suite 类 Agent 以及 .claude/commands/analysis/bottleneck-detect.md 等命令互为呼应说明“实现即基准、基准即交接物”是该体系对 coder 产出质量的一条隐性验收标准。九、协作契约向 researcher 要上下文、向 tester 交接、向记忆汇报角色文件最后用一段“Collaboration”收束了 coder 的社交协议与researcher协调获取上下文遵循planner的任务分解向tester提供清晰的交接clear handoffs将假设与决策记录到记忆中不确定时主动请求评审所有实现决策都通过 MCP 记忆工具共享。结合第八节可拼出完整闭环planner 拆分 → researcher 补上下文 → coder 实现并上报状态/共享决策 → reviewer 评审 → tester 验证而每一步的状态都沉淀在coordination命名空间的记忆键中形成对全 swarm 可见的“活档案”。这也是为什么角色文档反复强调 “Always coordinate through memory始终通过记忆协同”。十、给自定义 Coder 角色读者的落地建议把角色文件当作可执行的“行为宪法”而非散文coder.md 中的每一条先读 ADR、先写测试、函数 20 行、覆盖 80%、记忆共享都应能转化为 reviewer 的检查项若你想派生出例如“安全编码员”“性能实现员”等特化角色可在.claude/agents/core/同目录新建角色文件并继承本文的 SPEC/ADR 约束与记忆协同范式同时到v3/agents/补充结构化版本化配置。使用前先确认权威文档存在本文第二节约定的docs/SPEC.md与docs/adr/是“文档驱动仓库”的通用约定在 Ruflo 仓库中对应v3/docs/spec与v3/docs/adr等实体在绿地项目中可由 Architect Agent 先产出 ADR 再开工保证并行 Agent 不漂移。让记忆成为唯一事实源建议把所有实现决策文件清单、设计模式、依赖选型、API 端点写入coordination命名空间而非散落在各 Agent 的上下文中——这既支持中途加入的 Agent 快速对齐也便于事后审计与回溯。结尾原则角色规范原句好代码是为人类阅读而写只是顺带被机器执行——“Good code is written for humans to read, and only incidentally for machines to execute.” coder 角色的全部纪律——规范先行、设计优先、测试驱动、记忆协同——最终都服务于清晰clarity、可维护maintainability与正确correctness这三个字这也是整个 Ruflo 多智能体体系对“实现者”角色的最终期待。【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考