Qoder 从入门到精通
大规模工程 Harness 实践

Agent 系统详解 ​

内置 Agent ​

Qoder 开箱即带一组内置 Agent，覆盖常见开发场景：

Agent用途
代码审查 (CodeReview)审查代码变更，发现逻辑缺陷和安全漏洞
浏览器 (Browser)打开浏览器预览页面，截图并交互操作
通用编码 (Default)默认编码 Agent，处理大多数开发任务

这些内置 Agent 覆盖了 80% 的日常场景，安装完就能用。

自定义 SubAgent ​

当你的项目有独特的任务模式时，可以创建自定义 SubAgent。在 .qoder/agents/ 目录下定义即可：

yaml
# .qoder/agents/architecture-review.yaml
name: 架构审查
description: 审查模块架构设计，检查分层合规性和依赖方向
model: claude-sonnet
instructions: |
  你是一名架构师，负责审查模块设计的合规性。
  1. 检查模块依赖方向是否符合分层约束
  2. 识别循环依赖和跨层调用
  3. 验证接口抽象是否合理

除了 IDE 中的 YAML 定义方式，Growth AIOS 产品也提供了可视化的 Agent 管理界面，支持通过表单配置系统提示词和工具选择，还可以通过 AI 对话自动生成 Agent 定义：

在 Growth 产品矩阵中，我们实际构建了两类 SubAgent，覆盖不同粒度的自动化场景：

第一类：节点级嵌入式 Agent（AiAgent.Embedded）

每个封装一个特定领域能力，自带系统提示词和工具，不依赖工作流上下文，可独立执行：

  • AHK Agent：Windows GUI 自动化，通过 AutoHotkey 脚本实现桌面操作自动执行
  • Browser Agent：浏览器自动化，支持导航、点击、输入、读取、等待等完整交互
  • FFmpeg Agent：视频处理，根据需求自动生成并执行 FFmpeg 命令

这类 Agent 的特点是"小、专、独立"，像一块块乐高积木，可以在工作流的任意节点即插即用。

第二类：工作流编排集成 Agent（AiAgent.Integration）

以流水线方式协作，将一个复杂任务拆解为多个阶段，每个阶段由一个 Agent 负责：

  • 需求解析 Agent：将用户自然语言需求解析为结构化描述
  • 骨架选择 Agent：根据需求选择合适的工作流控制骨架
  • 节点选型 Agent：为骨架中的每个位置匹配合适的具体节点
  • 参数填充 Agent：填充节点参数与参数间的引用链
  • 拓扑组装 Agent：组装节点间的连接关系和执行顺序
  • 画布构建 Agent：最终生成可执行的工作流画布

两类 SubAgent 分工模式

与嵌入式 Agent 不同，集成类 Agent 是流水线式的——前一个 Agent 的输出是后一个 Agent 的输入，共同完成从需求到可执行工作流的完整转换。

何时创建 SubAgent ​

不是每个任务都需要一个 SubAgent。经验法则：

  • 频率：该任务每周至少出现一次 → 值得创建
  • 专业化：需要特定领域知识和指令模板 → 适合封装为 Agent
  • 一致性：多人执行时输出质量参差不齐 → Agent 可以标准化

AGENTS.md 机制：大模型如何知道何时加载 SubAgent ​

前面介绍了如何定义 SubAgent，但有一个关键问题没回答：大模型怎么知道什么时候该用哪个 SubAgent？

这个问题的答案是 Qoder 的 AGENTS.md 机制。

AGENTS.md 是什么 ​

每个 Qoder 工作区的根目录下都有一个 .qoder/AGENTS.md 文件。它是一份项目上下文说明书，每次对话一开始就会被加载到大模型的上下文中，告诉模型：

  • 这个项目是做什么的
  • 有哪些可用的 SubAgent 和 Skill
  • 每个 Agent 在什么场景下使用

以 Client 项目的 AGENTS.md 为例，它只有 120 行左右的篇幅，却能完整描述一个包含后端五层架构、前端 Rush Monorepo、集成测试体系的复杂项目。模型读完就知道有哪些 Skill 可用（如 /requirement、/web-server-requirement）、项目有哪些模块、各层之间的依赖原则是什么。

为什么每次对话都要加载 ​

AGENTS.md 不是"读一次就够了"的参考文档。每次对话开始的时候，模型对项目一无所知。AGENTS.md 起到的作用，类似于一个新同事入职时拿到的项目简介——它告诉模型当前工作区里有什么、能做什么、怎么做。

没有这份上下文，模型就不知道你的项目结构、不知道有哪些可用的 Agent 和 Skill、也不知道编码规范该从哪里查。

理解"渐进式披露" ​

渐进式披露四层架构

既然 AGENTS.md 每次对话都会加载，它必须保持精炼。这引出了 Qoder 的一个核心设计原则：渐进式披露。

模型的上下文窗口是有限的。如果把所有信息都塞进 AGENTS.md，一方面会让模型在简单任务上浪费大量 token，另一方面会因为信息过载，导致模型对关键内容"视而不见"。

Qoder 的分层策略：

AGENTS.md（精炼，每次加载）
  → Rules（按需触发，由 AGENTS.md 索引）
    → Skills（按需调用，由用户或模型显式触发）
      → Agent 定义文件（按需加载，由模型判断后调用）
  • 第一层（AGENTS.md）：只写项目的骨架信息——定位、模块结构、可用的 Agent 和 Skill 的索引。让模型知道"有什么"，不展开细节。
  • 第二层（Rules）：具体的编码规范和约束条件。当模型需要修改代码时，AGENTS.md 会告诉它去读哪些 Rules。
  • 第三层（Skills）：完整的操作流程和模板。当需要执行特定任务时，通过斜杠命令触发。
  • 第四层（Agent 定义文件）：SubAgent 的完整提示词和指令。当模型判断当前任务匹配某个 Agent 时，才会加载对应的 YAML 文件。

每一层都比上一层更详细，但只在需要的时候才会被加载。这就是"渐进式披露"的含义。

模型是如何做"路由决策"的 ​

渐进式上下文加载流程

每次用户提出一个需求，模型会做这样几个判断：

  1. 读 AGENTS.md：了解项目全貌，知道有哪些可用的 Agent 和 Skill
  2. 匹配任务类型：通过技能名或 Agent 名中的 description 字段，判断当前任务是否匹配
  3. 触发加载：如果是匹配的 Agent/Skill，模型会加载对应的详细定义文件
  4. 执行：按照定义文件中的 instructions 执行任务

这个决策链中，最关键的是 AGENTS.md 中的描述写得够不够精准。描述越具体，模型的匹配越准确。这也是为什么我们强调每条 description 必须写清楚"什么场景下用"，而不是抽象的功能描述。

保持简单的原则 ​

在实践中，使用 AGENTS.md 有几条经验：

  • 控制在 200 行以内，超过这个长度就该考虑把内容拆到 Rules 或 Skills 里
  • description 是核心，花时间把一句话描述写好，比写长篇说明更有价值
  • 索引优先于内容，AGENTS.md 只做索引和指引，具体内容放到下层文件
  • 每周审视一次，项目变化后及时更新，避免模型读到过时的上下文

Growth AIOS 产品参考 ​

以下为 Growth AIOS 产品中对应的 Agent 管理界面截图：

自定义 Agent 创建表单