Ruflo 长时运行测试智能体（test-long-runner）实战：Claude Code 自定义 Agent 的编写范式与仓库级落地指南

导读：本文以 ruflo 仓库中 test-long-runner.md 这份自定义 Agent 定义文档为核心骨架，讲解在 Claude Code / 智能体元框架（meta-harness）生态下，如何编写一个面向「30 分钟以上复杂长任务」的专业测试子智能体。读完本文，你将掌握 Agent 定义文件的 Frontmatter 规范、正文各区块（Capabilities / Instructions / Output Format / Example Use Cases）的编写意图，以及该 Agent 如何与 ruflo 的 .claude/agents 目录体系、初始化分发、Codex 模板迁移等工程设施协同工作。

一、文档定位：一份 Claude Code 自定义 Agent 的「系统提示词」定义

在 ruflo 的智能体体系中，每一个可被调度的子 Agent 都是一份结构固定的 Markdown 文件，存放在约定目录下，例如本文主角位于 .claude/agents/custom/test-long-runner.md。

从文件结构上可以看到该目录具有清晰的分类语义（category）：.claude/agents 下并列着 analysis/、architecture/、consensus/、core/、custom/、data/、devops/、documentation/、dual-mode/、flow-nexus/、github/、goal/、hive-mind/、v3/ 等大量子目录，test-long-runner.md 正位于 custom/ 之下。所谓「custom」目录，从命名惯例看即用于放置团队或开发者自定义、非内置通用的私有智能体；而与它同级的 core/ 目录中则是 coder.md、planner.md、researcher.md、reviewer.md、tester.md 这类基础角色智能体。

值得注意的是，同一份 Agent 定义在仓库中被多处镜像分发：除根目录外，v3/@claude-flow/cli/.claude/agents/custom/test-long-runner.md 与 v3/@claude-flow/mcp/.claude/agents/custom/test-long-runner.md 中也有同名文件。结合仓库包描述（v3/@claude-flow/cli 的 package.json 中写明该 CLI 提供 "60+ specialized agents ... for Claude Code"），可以推断这份定义会随 ruflo CLI / MCP 等发行包同步分发到用户工程中。

Agent 文件结构本质上是两部分：

1. 三段式 YAML Frontmatter（--- 包裹）声明元信息；
2. Frontmatter 之后的 Markdown 正文，即该 Agent 的「系统提示词 / 行为规范」，被主控 Agent 选中后注入其上下文。

二、Frontmatter 解析：name 与 description 的调度语义

---
name: test-long-runner
description: Test agent that can run for 30+ minutes on complex tasks
---

该定义文件只有两个 Frontmatter 字段，其语义是：

• name：Agent 的唯一标识符，即调度方（主控 Agent / orchestrator）按名称引用该子 Agent 时使用的键。本文件的标识为 test-long-runner，强调其角色是「测试执行者」、专长是「长时间运行」。
• description：一份面向调度器的能力摘要。在 Claude Code 的子 Agent 机制中，主 Agent 正是通过读取各候选 Agent 的 description 来决定何时把任务委派给谁——它不是给人看的注释，而是「路由提示词」。这里的 Test agent that can run for 30+ minutes on complex tasks 精准声明了两个约束维度：可运行时长预期（30+ 分钟）与任务复杂度（complex tasks），从而让调度器在遇到需要深度持续工作的测试型任务时优先考虑委派给它。

在 ruflo 的 Agent 体系里，Frontmatter 采用同样的 YAML 约定。对比同仓库 .claude/agents/core/tester.md 的 description: Comprehensive testing and quality assurance specialist，可以发现角色职责越宽泛、description 越概括；而 test-long-runner 越专门、description 越需要突出时间预算这一稀缺约束。这一点对编写自定义 Agent 有直接借鉴意义：如果你的 Agent 是面向超长任务设计的，务必把「时间/深度/范围」这类运行特征写进 description，否则调度器无法感知它的特殊性。

三、正文结构：从 H1 系统提示到六大行为区块

Frontmatter 之后以一级标题 # Test Long-Running Agent 开头，紧接一句角色总述：

You are a specialized test agent designed to handle long-running tasks that may take 30 minutes or more to complete.

这句话定义了 Agent 的身份锚点，并在角色中再次重复了 30 minutes or more 这一时间预算，与 description 首尾呼应。随后正文被组织为四个二级区块，分别从能力、行为准则、产出格式、适用场景四个维度约束 Agent：

3.1 Capabilities：声明能力边界

原文声明的五项能力如下，本质上给出了该 Agent 在超长任务中「被允许且被期待」做的工作类型：

• Complex Analysis：深入分析代码库、文档与系统（Deep dive into codebases, documentation, and systems）
• Thorough Research：跨多来源的全面研究（Comprehensive research across multiple sources）
• Detailed Reporting：生成详尽的报告与文档（Generate extensive reports and documentation）
• Long-Form Content：编写长篇指南、教程与文档（Create comprehensive guides, tutorials, and documentation）
• System Design：设计复杂分布式系统与架构（Design complex distributed systems and architectures）

这五项均指向产出重、耗时长、需要跨多轮上下文持续推理的任务类型，与常规 QA 测试智能体的「写测试→跑测试→报结果」短任务模型形成互补。

3.2 Instructions：行为准则（质量优先的节奏控制）

Instructions 是该 Agent 的核心「操作守则」，原文给出五条，每一条都对应长任务治理的一个关键点：

1. Take Your Time — Don't rush, quality over speed：明确时间预算充裕，无需为尽早交付牺牲质量；
2. Be Thorough — Cover all aspects comprehensively：要求覆盖所有方面，避免长任务中常见的「越做越窄」；
3. Document Everything — Provide detailed explanations and reasoning：对每一步产出都保留推理过程，保证长流程可追溯；
4. Iterate — Continuously improve and refine：鼓励迭代式改进，而非一次性交付；
5. Communicate Progress — Keep the user informed：在长达数十分钟的执行周期中持续向用户同步进度。

其中第 5 条尤其值得展开：长任务最大的风险不是「做得慢」而是「像死锁一样失去反馈」。在 ruflo 这类会驱动长任务的框架中，进度同步是硬性要求——仓库 .claude/agents/core/tester.md 的 Best Practices 中同样要求 "Report Results: Always share test results via memory"，并展示了通过 mcp__claude-flow__memory_usage 这类工具以 action: "store" + namespace: "coordination" 上报测试状态、共享测试结果的写法。也就是说，长任务 Agent 的进度沟通既可以通过对话文本，也可以写入集群共享的内存命名空间，供 swarm 中其他智能体读取。

3.3 Output Format：长文本产出的结构化约束

原文对产出格式提出明确要求——详细且结构良好（detailed, well-structured），并列举五个组成要素：

• Clear section headers（清晰的分节标题）
• Code examples where applicable（适用处给出代码示例）
• Diagrams and visualizations in text format（以文本形式呈现图示，例如 ASCII 结构图）
• References and citations（引用与出处）
• Action items and next steps（后续行动项）

这套输出契约与 ruflo 仓库中其他长文档型 Agent 的定义一脉相承，例如 .claude/agents/core/tester.md 会输出测试金字塔 ASCII 图与 @test/@description/@steps/@expected 形式的测试文档块。因此「以文本形式绘图」是仓库 Agent 体系的通用约定——因为纯文本图示在任意终端与上下文中都可解析，不依赖图片渲染。

3.4 Example Use Cases：场景锚点

原文给出五类典型任务，用于在委派时帮助调度器做模式匹配：

• Comprehensive codebase analysis and refactoring plans（全量代码库分析与重构计划）
• Detailed system architecture design documents（详尽系统架构设计文档）
• In-depth research reports on complex topics（复杂主题深度研究报告）
• Complete implementation guides for complex features（复杂功能的完整实施指南）
• Thorough security audits and vulnerability assessments（彻底的安全审计与漏洞评估）

在 ruflo 的实际工作负载中可以找到大量对应场景的证据：scripts/ 目录下有 audit-supply-chain.mjs、audit-exit-bypass-antipattern.mjs、audit-neural-trader-safety.mjs、audit-cli-mcp-tools.mjs 等安全/质量审计脚本，.claude/commands/ 下还有成体系的子命令，说明「深度代码审计、安全评估、复杂实现」正是需要长时运行智能体承载的高频任务形态。

文档以一句收束性的记忆强化语句结尾：

Remember: You have plenty of time to do thorough, high-quality work!

这句话看似「鼓励语」，实则是系统提示词中常见的**行为锚点（anchoring）**技巧——在长上下文执行的尾声再次强调时间预算，防止 Agent 因为上下文过长而在收尾阶段仓促降质。

四、仓库证据：这份 Agent 如何在 ruflo 中被分发、迁移与落地

test-long-runner 并非孤立文件，ruflo 为这类 Agent 定义提供了完整的生命周期工程：

4.1 初始化分发：agents 作为 init 组件被复制到目标工程

在 init/executor.ts 中可以看到，CLI 初始化流程把 .claude/skills、.claude/agents、.claude-flow/agents 等目录作为组件处理（相关代码约在 L155-L157、L221-L222），并在 L781-L839 附近执行「补齐缺失文件」的逻辑：它扫描目标工程 .claude/skills、.claude/agents、.claude/commands 三个目录（L782-L785），以「仅新增、不覆盖已有文件」的幂等方式把缺失的 skill、agent 按类别（agentCategory）复制进去（L834-L839）。这意味着 custom/test-long-runner.md 这类 Agent 会随 ruflo 初始化/升级被安装进用户的 .claude/agents 树中，且不会覆盖用户本地同名的自定义修改。

4.2 镜像存在：cli 与 mcp 双包分发

同一份 custom/test-long-runner.md 出现在 v3/@claude-flow/cli/.claude/agents/custom/ 与 v3/@claude-flow/mcp/.claude/agents/custom/ 两个发行包中，说明 CLI 侧与 MCP 服务侧都可以消费这份 Agent 定义。从源码结构可以推断，ruflo 将 Agent 定义文件当作可打包分发的资源而非运行时生成的临时文件，便于让不同入口（命令行 Agent 会话 / MCP 桥接）共享同一套角色定义。

4.3 Codex 模板转换：agent-test-long-runner 被声明为可安装 Skill

仓库 v3/@claude-flow/codex/src/templates/index.ts 中维护了「将 Claude Code Agent 转换/安装为 Codex Skill」的模板清单。其 ALL_AVAILABLE_SKILLS 列表（L93-L206）中显式列出了 agent-test-long-runner（L176，即本 Agent 的 skill 化命名），与 agent-tester、agent-coder、agent-reviewer 等并列；文件注释同时说明这些技能在初始化时会被复制到 .agents/skills/ 目录。这印证了两点：

1. ruflo 生态中存在 Claude Code ↔ Codex 的双平台适配层（PLATFORM_MAPPING 中明确列出了 claudeCode 用 CLAUDE.md+settings.json、codex 用 AGENTS.md+config.toml 的映射规则）；
2. 一个「长时运行测试 Agent」的角色定义，通过模板机制可以降级/转换为一枚可在 Codex 会话中按 $skill-name 调用的技能，实现一次编写、双平台复用。

4.4 市场插件形态：Agent 恢复路径中的分类约定

commands/migrate-agent-restore.ts 展示了 Agent 定义的另一套载体：plugins/<plugin>/agents/<basename>。其解析顺序是「用户本地 Claude Code marketplace 克隆 → 仓库根目录插件 → GitHub raw 回退」（L6-L13），且恢复时会按原分类目录放置（RESTORE_CATEGORY 映射表，如 coder.md → core、tester.md → core），以维持基于 --agents=<cat> 的分类过滤工具正常工作。由此可反推：Agent 文件的目录名就是分类属性，从 custom/ 目录取出的文件理应落回 custom/，分类是路由与筛选的一等公民。

五、实践模板：照此范式编写你自己的长时运行 Agent

结合原文结构、Claude Code 子 Agent 的文件约定与 ruflo 仓库的分发机制，编写一个长时运行型自定义 Agent 的完整步骤为：

1. 选择分类目录：私有/团队自定义角色放入 .claude/agents/custom/；若是想随插件分发，则放到 plugins/<plugin>/agents/ 下对应分类。文件名即技能标识，建议 kebab-case（如 test-long-runner.md）。
2. 编写 Frontmatter：至少提供 name 与 description；description 务必写明「可运行时长 + 任务复杂度 + 角色专长」，这是调度路由的依据。
3. 编写 H1 系统提示：用一句话确立身份，可重复关键约束（如时间预算）以形成行为锚点。
4. 按四区块组织正文：
   • ## Capabilities——声明被允许承担的能力范围；
   • ## Instructions——逐条给出长任务行为准则，至少包含「质量优先、全面覆盖、保留推理、持续迭代、沟通进度」五要素，其中进度沟通建议写明落点（如对话汇报 + 写入 mcp__claude-flow__memory_usage 协调命名空间）；
   • ## Output Format——强制结构化产出（分节标题、代码示例、文本图示、引用、后续行动项）；
   • ## Example Use Cases——给出 3~5 个具体场景，帮助调度器模式匹配。
5. 验证可用性：对按插件分发的 Agent，可参照 migrate-agent-restore 的解析链路确认文件可被 marketplace 克隆或仓库 checkout 命中；对通过 CLI 初始化的场景，可确认 init 的补齐逻辑只做增量同步，不会覆盖本地同名文件。
6. 需要双平台支持时：确认 agent-<name> 已登记进 Codex 模板的 ALL_AVAILABLE_SKILLS，以便 Claude Code 与 Codex 两侧都能安装该角色。

六、结论

.claude/agents/custom/test-long-runner.md 是一份小而完整的 Claude Code 自定义 Agent 规范文档：它以「30 分钟以上复杂任务」为唯一主题，用 Frontmatter（name/description）解决调度可发现性，用 Capabilities / Instructions / Output Format / Example Use Cases 四个区块解决执行质量与产出契约，并把「时间充裕」这一差异化约束从 description 贯穿到结尾的行为锚点，构成首尾自洽的提示词设计。在 ruflo 仓库中，它并非孤例文档，而是接入了一整套工程化链路——随 CLI init 增量分发到目标工程、以 cli/mcp 双包形式镜像存在、可经 Codex 模板 转换为 agent-test-long-runner 技能跨平台复用、并遵守按目录分类的路由约定。对希望在团队中落地「深度、长时、高质量」测试型 AI 角色的开发者而言，这份文件同时提供了可直接复用的提示词蓝本与一套可参考的分发治理范式。