企业官网建设流程全解析

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是 Ruflo（Claude 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/status）；
• description：供编排器理解角色能力边界，即“编写整洁、高效代码的实现专家”。

在仓库中，coder 不是孤立存在，而是核心角色组的一员。.claude/agents/core/ 目录下按“单一职责”拆分了五类核心 Agent：

同时，仓库v3子树中还存放着结构化版本化配置（如 v3/agents/tester.yaml 声明type: tester、version: "3.0.0"与capabilities）。也就是说，从源码结构看，Agent 角色存在“Markdown 行为规范”与“YAML 结构化配置”双层表达：前者约束模型行为，后者声明类型与能力元数据，二者共同构成可编排的角色契约。

二、动手前的硬性约束：先读 SPEC 与 ADR

角色规范最重要的纪律在于“先读文档，再写代码”。凡是会影响架构、范围或行为的改动，coder 必须先读两类权威文档：

1. docs/SPEC.md（及docs/下的同级文件）—— 回答系统“应该做什么”：功能需求、范围、验收标准；
2. 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. 理解需求（Understand Requirements）：透彻阅读规格、编码前澄清歧义、考虑边界与错误场景；
2. 先设计后编码（Design First）：规划架构、定义接口与契约、预留可扩展性；
3. 测试驱动开发（Test-Driven Development）：先写测试、再实现；
4. 增量实现（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 Map<string, 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; }

该示例同时示范了三条隐性纪律：行为先于实现被固化、外部依赖被 Mock（createMockUser）、测试断言与业务规则一一对应。这与 Ruflo 架构约束中“新代码优先采用 TDD London School（mock-first）”的原则吻合（见仓库根 CLAUDE.md），也从仓库的测试布局得到印证——例如v3/__tests__、.claude/agents/core同层的 tester 角色以及大量*.test.ts文件的存在，说明“测试与实现同构存放、Mock 隔离外部依赖”是仓库惯例。

六、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; } // 错误边界：可携带 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.md）：

1. 安全（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" }

记忆工具的参数模型为action（store/retrieve 等）+ key（唯一键）+ namespace（命名空间）+ value（JSON 序列化负载）。这套调用范式与仓库中的真实 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