Medusa 仓库的 Claude Agent 体系：四个代码库探索代理的选择、约束与编排

本文介绍 Medusa 开源电商仓库 .claude/agents/ 目录下的专项 Agent 体系：一套为大型 TypeScript monorepo 量身设计的代码库探索与研究代理，涵盖 codebase-locator（找代码在哪）、codebase-analyzer（讲代码怎么工作）、codebase-pattern-finder（找可模仿的范例）和 web-search-researcher（检索仓库之外的信息）。读完本文，你将掌握每个代理的适用场景、工具边界、输出格式，以及它们在 Medusa 仓库命令工作流中的组合编排方式，从而能照此思路为自己的大型仓库设计分层 Agent 体系。

目录结构与设计定位

Medusa 是一个包含 30 多个模块化 commerce 包的大型 TypeScript monorepo（见 CLAUDE.md 中对 packages/core/、packages/modules/、packages/admin/ 等目录的说明）。在这种规模下，"代码在哪里、怎么实现的、有没有现成范例"是最常见的三类探索问题。Medusa 团队在 .claude/agents/ 下定义了四个职责单一的专项代理，并用一份 Agent Selection Guide（即 README.md）说明选择逻辑：

文件	职责
codebase-locator.md	定位与某功能/任务相关的文件、目录和组件
codebase-analyzer.md	分析实现细节，追踪数据流，解释技术原理
codebase-pattern-finder.md	寻找相似实现、用法示例和既有模式作为模板
web-search-researcher.md	检索代码库之外的外部信息

四个 Agent 逐一解析

codebase-locator：当你需要知道代码"在哪里"

适用场景（来自 README.md）：

• 定位与某个功能或模块相关的文件
• 找出与某项功能相关的所有组件
• 发现测试文件、配置文件或文档
• 获得"什么内容存在于何处"的结构化概览

典型查询示例：

• "订单取消功能在哪里？"（Where is the order cancellation functionality?）
• "找出所有与 product variants 相关的文件"
• "定位认证中间件"

输出：按类别（实现、测试、配置、文档、类型定义）分组的文件路径列表。

从 codebase-locator.md 的定义文件看，其 frontmatter 声明为：

name: codebase-locator
tools: Grep, Glob, LS
model: sonnet

几个关键实现细节值得注意：

• 刻意不授予 Read 工具。定义文件中明确要求"不读取文件内容，只报告位置"（Don't read file contents - Just report locations），把它定位为"Super Grep/Glob/LS 工具"——当你发现自己想连续使用多次搜索工具时就该调它。
• 搜索策略分两层：先做广度搜索（基于命名约定、目录结构、同义词选择 grep 模式），再按语言/框架收敛（TypeScript 项目看 src/、lib/、components/、api/ 等目录）。
• 常用文件名模式：*service*、*handler*、*controller* 对应业务逻辑，*test*/*spec* 对应测试，*.config.*/*rc* 对应配置，*.d.ts 对应类型定义。
• 输出格式固定为 ## File Locations for [Feature/Topic] 结构，分 Implementation Files、Test Files、Configuration、Type Definitions、Related Directories、Entry Points 六类，要求提供自仓库根目录起的完整路径、目录内文件数量，以及入口点引用（如"src/index.js 在第 23 行导入该模块"）。

codebase-analyzer：当你需要理解代码"怎么工作"

适用场景：

• 追踪系统中的数据流
• 理解某个功能是如何实现的
• 解释技术实现细节
• 跟随执行路径和调用链
• 理解复杂逻辑或算法

典型查询示例：

• "订单创建工作流如何处理支付？"
• "追踪商品价格是如何计算的"
• "解释从登录到令牌生成的认证流程"

输出：带 文件:行号 引用的详细技术解释。

codebase-analyzer.md 的 frontmatter 与 locator 相比只多了一个工具：

tools: Read, Grep, Glob, LS
model: sonnet

其分析策略被固化为三步：

1. 读入口点：从请求中提到的主文件开始，找导出、公共方法或路由处理器，确定组件的"表面积"；
2. 沿代码路径跟进：逐函数追踪调用、读取流程中涉及的每个文件、标注数据被转换的位置、识别外部依赖；
3. 记录关键逻辑：如实记录验证、转换、错误处理、所用配置与 feature flag，但明确"不评估逻辑是否正确或最优"。

输出模板固定为 ## Analysis: [Feature/Component Name]，依次包含 Overview、Entry Points、Core Implementation（按步骤编号并带 文件:行号 范围）、Data Flow（编号步骤链）、Key Patterns、Configuration、Error Handling 七部分。其硬性要求是"任何结论都必须有 file:line 引用"，且"追踪实际代码路径，不要假设"。

codebase-pattern-finder：当你需要可模仿的范例

适用场景：

• 寻找相似的实现作为模板
• 发现某个库或模式的使用示例
• 基于既有代码理解如何实现某事
• 识别整个代码库中保持一致的模式

典型查询示例：

• "给我看带校验的 API 路由示例"
• "找类似的 workflow 实现"
• "其他模块是如何处理软删除的？"

输出：带上下文和用法模式的真实代码示例。

从 codebase-pattern-finder.md 的定义看，它自我描述为"和 codebase-locator 类似，但不仅告诉你文件位置，还给出代码细节"。其 frontmatter 为：

tools: Grep, Glob, Read, LS
model: sonnet

它的搜索策略按模式类型分类：

• 功能模式：其他地方是否有相似功能
• 结构模式：组件/类如何组织
• 集成模式：系统之间如何连接
• 测试模式：类似功能是如何被测试的

输出模板要求展示"能工作的代码"而非零碎片段：每个模式给出 Found in: 文件:行号、用途说明、完整代码块和 Key aspects 摘要；随后给出 Testing Patterns（既有测试写法）、Pattern Usage in Codebase（该模式在代码库中的分布）和 Related Utilities（相关共享工具）。定义中还列举了四类值得搜索的模式清单：API 模式（路由结构、中间件、错误处理、认证、校验、分页）、数据模式（数据库查询、缓存、转换、迁移）、组件模式（文件组织、状态管理、事件处理、生命周期、Hooks）、测试模式（单测结构、集成测试 setup、Mock 策略、断言模式）。

web-search-researcher：当你需要仓库之外的信息

适用场景：

• 调研库、框架或工具
• 查找第三方包的文档
• 了解行业标准或最佳实践
• 获取代码库中不存在的信息

典型查询示例：

• "Stripe API 最新支持哪些支付方式？"
• "查找 TypeScript 依赖注入的最佳实践"
• "调研 OAuth 2.0 PKCE 流程的实现"

输出：带来源引用的综合研究结果。

从 web-search-researcher.md 的定义看，它实际上是被授予了全部七类工具的"全栈研究员"，也是四个代理中唯一声明 color: yellow 的：

tools: WebSearch, WebFetch, TodoWrite, Read, Grep, Glob, LS
model: sonnet

这里有个值得注意的细节：README.md 的对比矩阵中把它简写为 WebSearch, WebFetch 两件套，而实际 frontmatter 还包含 TodoWrite、Read、Grep、Glob、LS——也就是说它同样具备在代码库内验证/比对外部结论的能力，README 表格只是突出了它的核心差异。

其研究工作流固定为四步：分析查询（拆解关键词、判断来源类型、规划多角度搜索）→ 执行策略性搜索（先宽后窄，必要时用 site: 限定权威域名）→ 抓取并分析内容（用 WebFetch 取全文，优先官方文档，记录发布日期）→ 综合发现（按相关性和权威性组织，含原文引用、来源链接、冲突信息标注与信息缺口）。其输出模板包含 Summary、Detailed Findings（每条注明来源、权威性理由、关键信息）、Additional Resources 和 Gaps or Limitations 四节。质量准则强调准确性（精确引用）、相关性、时效性（标注版本与日期）、权威性（官方源优先）和透明性（明确标出过时、冲突或不确定的信息）。

Agent 对比矩阵

README.md 给出的选型速查表：

Agent	关注点	工具	使用场景
codebase-locator	WHERE（位置）	Grep, Glob, LS	找文件和目录
codebase-analyzer	HOW（实现）	Read, Grep, Glob, LS	理解技术细节
codebase-pattern-finder	EXAMPLES（模式）	Grep, Glob, Read, LS	找可模仿的模板
web-search-researcher	EXTERNAL（外部研究）	WebSearch, WebFetch	从网络获取信息

工具集的编排逻辑很清晰：locator 完全不读文件内容（纯定位，最快）；analyzer 和 pattern-finder 增加 Read（分别用于"理解"和"提取范例"）；web-search-researcher 则以 WebSearch/WebFetch 为核心。所有代理均声明 model: sonnet。

统一约束：五个代理共同遵守的原则

README.md 规定了所有 Agent 的共同约束，而这并非空话——逐一核对四个定义文件可以发现，每条约束都落实为 prompt 中的硬性指令：

• Read-only（只读）：不修改任何代码；
• Objective（客观）：不做推荐、不做批评；
• Focused（聚焦）：留在各自职责域内；
• Accurate（精确）：提供精确的 file:line 引用；
• Complete（完整）：完整读取文件，不读一半就下结论。

尤其"Objective"一条，在三个代码库代理的定义中都以相同措辞的 "CRITICAL" 区块反复强化，例如 codebase-locator.md 与 codebase-analyzer.md 均声明 "YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY"，并在文件结尾统一收束为同一句人设锚定："You are a documentarian, not a critic or consultant"（你是记录者，不是批评者或顾问）。pattern-finder 更进一步列出"不得识别反模式、不得做模式对比分析、不得建议哪个模式更好"。这种设计的目的很直接：把"探索/理解"与"评审/建议"两种认知任务分离，保证探索阶段输出的信息是中性的事实底座，供后续规划阶段使用。

实战编排：Medusa 命令工作流中的真实用法

这套 Agent 并非孤立存在，它们被 Medusa 的自定义命令直接编排进了标准研发流程。从 .claude/commands/ 目录可以看到两个典型调用方：

研究流程（research.md） 中明确规定：

• 用 codebase-locator 找文件与组件的 WHERE（位置）
• 用 codebase-analyzer 理解具体代码的 HOW（且明确注明"不对其做批评"）
• 用 codebase-pattern-finder 找既有模式的示例（且"不对其做评价"）
• 用 web-search-researcher 获取外部文档和资源

计划制定流程（create_plan.md） 则在制定方案阶段调用：

• 用 codebase-locator 找出与工单/任务相关的所有文件
• 用 codebase-analyzer 理解当前实现如何工作
• 并在"需要更多探索"的提示区列出三个代理及其示例问法，如"找出所有处理 [某组件] 的文件""分析 [某系统] 如何工作""找类似功能作为建模参考"

这正好印证了 README.md Tips 一节给出的组合建议：

1. 先用 locator：不知道代码在哪时，先用 codebase-locator；
2. 再 analyze：知道位置后，用 codebase-analyzer 理解其工作原理；
3. 找 patterns：用 codebase-pattern-finder 查看相似实现；
4. 外部研究：非代码库信息交给 web-search-researcher；
5. 组合使用：多个代理可并行运行，以获得全面探索。

换言之，Medusa 的编排哲学是"定位 → 理解 → 对标 → 外部补充"的漏斗式流程：前三个代理全部在仓库内闭环完成（且只读、只描述现状），第四个代理负责仓库边界之外的信息。

可借鉴的设计要点

从 Medusa 的这套实现中，可以提炼出几个对自有仓库同样适用的设计手法：

1. 用 frontmatter 做工具级权限隔离。把"不许读文件"（locator）、"可以读但只给结论"（analyzer）等约束，落实到 tools: 字段而非仅靠 prompt 叮嘱，从能力层面杜绝越界行为。
2. description 字段写给调度 LLM 看。各定义文件的 description 都是对"何时该调用我"的自然语言描述（如 locator 的 "Use it if you find yourself desiring to use one of these tools more than once"），这是主代理路由决策的依据，比职责标题更影响实际调用率。
3. 固定输出模板。四个代理各自定义了带小标题的固定输出结构（locator 的六类文件分组、analyzer 的七段分析报告、pattern-finder 的模式目录、researcher 的来源引用研究），使不同代理的产物可以直接拼装成同一份文档的不同章节。
4. 探索与评审分离。"documentarian, not a critic or consultant" 的人设约束贯穿所有代码库代理，保证探索阶段的输出是中性事实底座，评审与建议留给后续独立阶段。
5. 用一份 README 收敛选择逻辑。当代理数量增长时，一份"何时用哪个 + 对比矩阵 + 组合技巧"的选型指南（如本仓库的 .claude/agents/README.md）能显著降低使用方的决策成本，也便于人和 Agent 共同快速检索。

适用前提与限制

需要说明的适用边界：这套 Agent 体系是 Claude Code（.claude/ 配置目录）生态下的 subagent 定义，frontmatter 中的 tools、model: sonnet、color 等字段由 Claude Code 解析；其中的 WebSearch/WebFetch 能力依赖运行环境提供对应的联网工具。文档与定义文件中的示例路径（如 src/services/feature.js、handlers/webhook.js）均为输出格式的占位示意，并非 Medusa 仓库的真实文件；Medusa 的真实结构参考 CLAUDE.md 中的 monorepo 目录说明。