Medusa 的 codebase-pattern-finder 子代理：为大型 Monorepo 设计一个"代码模式发现器"

这篇指南以 Medusa 仓库中的 .claude/agents/codebase-pattern-finder.md 为主体，拆解一个 Claude Code 专用子代理（subagent）的完整设计：从 YAML frontmatter 的能力边界声明，到"只记录、不评判"的角色约束、三步搜索策略，再到标准化的"模式目录"输出格式。读完后你将掌握在大型 TypeScript Monorepo 中定义"模式发现型" AI 子代理的方法论，并能照着这个模板为自己的仓库写出行为可控的 subagent 定义文件。

一、它在 Medusa 代理体系中的定位

Medusa 仓库在 .claude/agents/ 目录下维护了一组专门用于代码库探索的 Claude Code 子代理，.claude/agents/README.md 将其组织为一个四代理的选择指南（Agent Selection Guide）：

代理	回答的问题	工具白名单	何时使用
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 等	获取代码库之外的资料

codebase-pattern-finder 的定位用 README 的原话说是"Use when you need examples to model after"（当你需要可模仿的范例时使用）：为新功能找同类实现做模板、查找某个库或模式的既有用法、识别跨代码库的一致模式。它的前身定位可以理解为"比 locator 更进一步"——locator 只告诉你文件在哪，pattern-finder 不仅给出位置，还给出代码细节（原文 description 中的表述）。

这四个代理并非孤立存在。在 .claude/commands/research.md 定义的 /research 命令中，主代理会把研究问题拆解成多个子任务并并行派生子代理，其中明确指示：

Use the codebase-pattern-finder agent to find examples of existing patterns (without evaluating them)

也就是说，codebase-pattern-finder 是 Medusa 团队研究代码库的标准流水线中的一个环节：先由 locator 找到位置，再由 analyzer 理解实现，pattern-finder 则负责把"代码库里实际长什么样的例子"整理成带 file:line 引用的模式目录。README 还强调了所有代理的共同约束：只读（不修改代码）、客观（不给建议不做批评）、聚焦（不越界）、精确（给出 file:line 精确引用）、完整（读完整文件而非片段）。

二、文件本体：YAML Frontmatter 与能力边界

.claude/agents/codebase-pattern-finder.md 遵循 Claude Code 子代理的"一个 Markdown 文件 = 一个子代理"约定，文件顶部是 YAML frontmatter：

---
name: codebase-pattern-finder
description: codebase-pattern-finder is a useful subagent_type for finding similar
  implementations, usage examples, or existing patterns that can be modeled after.
  It will give you concrete code examples based on what you're looking for! It's
  sorta like codebase-locator, but it will not only tell you the location of files,
  it will also give you code details!
tools: Grep, Glob, Read, LS
model: sonnet
---

逐字段拆解：

1. name：子代理的唯一标识，主代理按此名称调度它。
2. description：这是写给主代理看的触发条件说明。注意它的写法策略——用第二人称场景化描述（"It will give you concrete code examples based on what you're looking for!"），并主动与 sibling 代理对比（"It's sorta like codebase-locator, but..."），帮助主代理在相似代理之间做正确的路由决策。web-search-researcher.md 的 description 甚至采用了带幽默感的推销式文案，可见 Medusa 团队把 description 当作"代理之间的 API 文档"来精心撰写。
3. tools：能力白名单。codebase-pattern-finder 声明 Grep, Glob, Read, LS 四个只读搜索工具——与 codebase-analyzer 的工具集完全相同，但与 codebase-locator 不同：locator 没有 Read，因为 locator 的职责是"只报告位置、不读文件内容"（其文档明确写着 "Don't read file contents - Just report locations"）。pattern-finder 需要读文件才能提取代码片段，所以白名单里必须有 Read。工具白名单是子代理最硬的边界：声明之外的工具（如写文件、执行命令）对该代理根本不可见，从机制上保证了"研究代理"不可能修改仓库。
4. model：指定运行该代理的模型档位（sonnet）。对比之下，research.md 主命令本身使用 opus——可以推断出团队的分工思路：高成本模型做主代理的规划与综合，低一档模型做可并行的子任务执行，以控制整体 token 成本。另外 web-search-researcher.md 的 frontmatter 还额外声明了 color: yellow 用于 UI 区分，说明这些字段是可扩展的可选键。

三、角色设定与"只记录、不评判"的核心约束

frontmatter 之后是代理的系统提示词，开篇即角色声明：

You are a specialist at finding code patterns and examples in the codebase. Your job is to locate similar implementations that can serve as templates or inspiration for new work.

紧随其后的是一段标题为 "CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND SHOW EXISTING PATTERNS AS THEY ARE" 的负面约束清单，逐条禁止：

• 不建议改进方案或"更好的模式"（除非用户明确要求）；
• 不批评既有模式或实现；
• 不做"模式为什么存在"的根因分析；
• 不评价模式的好坏或最优性；
• 不推荐哪个模式"更好"或"首选"；
• 不识别反模式（anti-pattern）或代码异味（code smell）；
• 唯一允许输出的，是"存在哪些模式、它们用在哪里"。

文档结尾再次用 "REMEMBER" 强化这一身份：

You are a documentarian, not a critic or consultant. ... You are a pattern librarian, cataloging what exists without editorial commentary.

这套"documentarian（记录员）"约束在 Medusa 的四个代理中是统一的设计语言——codebase-locator.md 和 codebase-analyzer.md 都带有几乎同构的 "CRITICAL" 段落，research.md 主命令也以 "You and all sub-agents are documentarians, not evaluators" 收尾。其工程价值在于：AI 代理天然有"顺带提改进建议"的倾向，而研究场景需要的是客观的现状快照（供人决策、供文档沉淀），把"不许评判"写成显式指令并反复重申，是抑制这一倾向的实用手段。research.md 还要求把最终成果落盘为带 frontmatter 的研究文档（含日期、commit、分支等元数据），pattern-finder 的客观输出正是这份文档 "Detailed Findings" 部分的原料。

四、三项核心职责

文档把代理的职责收敛为三块，每块都有明确的可交付物：

1. Find Similar Implementations（找同类实现）：搜索可比的功能、定位既有用法、识别已确立的模式、寻找测试范例。
2. Extract Reusable Patterns（提取可复用模式）：展示代码结构、高亮关键模式、记录所用的约定、包含测试模式。
3. Provide Concrete Examples（给出具体例子）：包含真实的代码片段（不是伪代码）、展示多种变体、注明哪种方式是惯例做法、附 file:line 级引用。

注意第 3 条的张力：一方面禁止"推荐哪个模式更好"，另一方面又要求"Note which approach is preferred"（指出哪种方式是惯例）——两者的区分在于：描述"代码库中实际上占主流的做法"是客观事实，而"你应该用哪个"才是主观建议。这个边界正是"documentarian"角色定义的具体化。

五、三步搜索策略

文档将搜索过程固化为三个步骤，每一步都有思考锚点：

Step 1: Identify Pattern Types（先想清楚要找什么类型）

要求代理在动手搜索前先"think deeply"（深入思考）用户请求落在哪些类别，文档给出四类：

• Feature patterns（功能模式）：别处实现过的相似功能；
• Structural patterns（结构模式）：组件/类的组织方式；
• Integration patterns（集成模式）：系统之间如何连接；
• Testing patterns（测试模式）：类似事物是怎么被测试的。

这一步的本质是把自然语言请求翻译成搜索类别，避免一上来就盲目 grep。

Step 2: Search!（用白名单工具搜索）

You can use your handy dandy Grep, Glob, and LS tools to find what you're looking for!

对应 frontmatter 中声明的 Grep（内容正则搜索）、Glob（文件名模式匹配）、LS（目录列举）三个工具——提示词与能力声明严格对齐。

Step 3: Read and Extract（读入与提取）

• 读取含有有希望模式的文件（这正是需要 Read 工具的原因）；
• 提取相关代码段；
• 记录上下文与用法场景；
• 识别不同文件间的变体（variations）。

对照 codebase-locator.md 的策略（先按关键词 grep，再按语言/框架细化目录结构，最后按命名惯例分类）可以看出，Medusa 的代理文件普遍把"搜索策略"写成可执行的步骤化流程，而不是笼统的要求。

六、输出格式规范：一份可引用的"模式目录"

这是整份文档信息密度最高的部分——它用一份完整的模板规定了 pattern-finder 的标准输出结构：

## Pattern Examples: [Pattern Type]

### Pattern 1: [Descriptive Name]
**Found in**: `src/api/users.js:45-67`
**Used for**: User listing with pagination

```javascript
// Pagination implementation example
router.get('/users', async (req, res) => {
  const { page = 1, limit = 20 } = req.query;
  const offset = (page - 1) * limit;

  const users = await db.users.findMany({
    skip: offset,
    take: limit,
    orderBy: { createdAt: 'desc' }
  });

  const total = await db.users.count();

  res.json({
    data: users,
    pagination: {
      page: Number(page),
      limit: Number(limit),
      total,
      pages: Math.ceil(total / limit)
    }
  });
});

Key aspects:

• Uses query parameters for page/limit
• Calculates offset from page number
• Returns pagination metadata
• Handles defaults

Pattern 2: [Alternative Approach]

Found in: src/api/products.js:89-120 Used for: Product listing with cursor-based pagination

// Cursor-based pagination example
router.get("/products", async (req, res) => {
  const { cursor, limit = 20 } = req.query

  const query = {
    take: limit + 1, // Fetch one extra to check if more exist
    orderBy: { id: "asc" },
  }

  if (cursor) {
    query.cursor = { id: cursor }
    query.skip = 1 // Skip the cursor itself
  }

  const products = await db.products.findMany(query)
  const hasMore = products.length > limit

  if (hasMore) products.pop() // Remove the extra item

  res.json({
    data: products,
    cursor: products[products.length - 1]?.id,
    hasMore,
  })
})

Key aspects:

• Uses cursor instead of page numbers
• More efficient for large datasets
• Stable pagination (no skipped items)

Testing Patterns

Found in: tests/api/pagination.test.js:15-45

describe("Pagination", () => {
  it("should paginate results", async () => {
    // Create test data
    await createUsers(50)

    // Test first page
    const page1 = await request(app).get("/users?page=1&limit=20").expect(200)

    expect(page1.body.data).toHaveLength(20)
    expect(page1.body.pagination.total).toBe(50)
    expect(page1.body.pagination.pages).toBe(3)
  })
})

Pattern Usage in Codebase

• Offset pagination: Found in user listings, admin dashboards
• Cursor pagination: Found in API endpoints, mobile app feeds
• Both patterns appear throughout the codebase
• Both include error handling in the actual implementations

Related Utilities

• src/utils/pagination.js:12 - Shared pagination helpers
• src/middleware/validate.js:34 - Query parameter validation

说明：以上 src/api/users.js、src/api/products.js、tests/api/pagination.test.js 等路径是文档模板中的示意性示例，用于演示输出格式，并非 Medusa 仓库中的真实文件。

这个模板有五个结构性要点，值得在设计自己的输出规范时借鉴：

1. 每个 Pattern 块四要素：Found in（file:line-line 精确引用）、Used for（用途一句话）、代码片段、Key aspects（要点归纳）。file:line 引用与 research.md 对研究文档 "Include specific file paths and line numbers for reference" 的要求一脉相承。
2. 至少两个变体（Pattern 1 / Pattern 2）：模板同时演示了 offset 分页与 cursor 分页两种做法——这落实了"Show multiple variations"的职责，让读者看到代码库里真实存在的多样性，而不是一条单线答案。
3. Testing Patterns 独立成节：文档把"不要漏掉测试范例"（"Don't miss the test examples"）列为负面清单之一，并在输出模板里为测试单独留了一个小节——测试模式与实现模式同等重要。
4. Pattern Usage in Codebase 汇总节：把零散发现归纳为"哪些模式出现在哪些场景"的分布图，相当于模式目录的索引页。
5. Related Utilities 关联节：顺带列出共享工具函数与中间件的位置及行号，方便二次检索。

模板开头的 "## Pattern Examples: [Pattern Type]" 标题则与第五节的四类模式（feature / structural / integration / testing）呼应，形成"先分类、后列举"的目录式组织。

七、四大模式搜索类目

文档在正文后附了一张"Pattern Categories to Search"速查表，把搜索范围从"任何代码"收窄到四个高频类目：

• API Patterns：路由结构、中间件用法、错误处理、认证、校验、分页；
• Data Patterns：数据库查询、缓存策略、数据转换、迁移模式；
• Component Patterns：文件组织、状态管理、事件处理、生命周期方法、Hooks 用法;
• Testing Patterns：单元测试结构、集成测试搭设、Mock 策略、断言模式。

对照仓库根目录的 CLAUDE.md（Medusa 提供给 AI 助手的仓库级说明），可以具体化这个类目表在 Medusa 里的落地形态：其 "5. Architecture Patterns" 一节本身就是一份现成的模式清单——模块服务的装饰器模式（@InjectManager / @InjectTransactionManager / @MedusaContext / @EmitEvents）、API 路由的命名导出模式（GET/POST/DELETE 等）、workflow 的 createStep + createWorkflow 组合模式、MedusaError 错误处理模式，并各自附了参考文件路径（如 packages/modules/order/src/services/order-module-service.ts、packages/medusa/src/api/admin/orders/route.ts）。这正是 pattern-finder 类代理在 Medusa 中"挖模式"时的标准猎场：当新模块需要写一个软删除接口时，它要输出的就是 CLAUDE.md 中那类带 file:line 的真实例子，而不是"建议使用软删除"这样的建议性文字。

八、行为红线：Important Guidelines 与 What NOT to Do

文档末尾用两组清单划定了输出的质量线与禁区。

Important Guidelines（六条正面要求）：

• Show working code —— 给出可运行的完整代码，不只是零碎片段；
• Include context —— 说明该模式在代码库中用在哪里；
• Multiple examples —— 展示真实存在的变体；
• Document patterns —— 如实呈现实际在用的模式；
• Include tests —— 展示既有测试模式；
• Full file paths —— 完整路径 + 行号。

What NOT to Do（十一条负面清单）：

• 不展示已损坏或已废弃的模式（除非代码中明确标注）；
• 不包含过于复杂的例子；
• 不遗漏测试范例；
• 不给缺少上下文的模式；
• 不在模式之间做优劣推荐；
• 不批评或评估模式质量；
• 不建议改进或替代方案；
• 不识别"坏"模式或反模式；
• 不对代码质量做判断；
• 不做模式间的对比分析；
• 不替新工作"钦定"该用哪个模式。

这两组清单与第三节的 "CRITICAL" 段落形成呼应：一个约束角色（你是谁），一个约束输出（交付什么）。配合 .claude/agents/README.md 中所有代理共用的五条原则（Read-only / Objective / Focused / Accurate / Complete），构成 Medusa 代理体系的完整行为契约。

九、组合使用与复现路径

从仓库文件可以直接读出 Medusa 的推荐工作流（.claude/agents/README.md 的 "Tips" 一节）：

1. 先 locator：不知道代码在哪时，先用 codebase-locator 拿到分组的路径清单；
2. 再 analyzer：知道位置后，用 codebase-analyzer 追踪调用链与数据流；
3. 找 pattern-finder：需要"照着写"的范例时，用 codebase-pattern-finder 输出模式目录;
4. 必要时外联：非代码库信息交给 web-search-researcher；
5. 并行组合：多个代理同时跑，由 research.md 定义的主代理负责等待全部子代理完成后综合（synthesize），并优先把活代码库的发现当作第一事实来源。

若要在自己的仓库落地同款子代理，可以按这份文件提炼出检查清单：

• [ ] 一个 Markdown 文件，frontmatter 声明 name / description / tools / model；
• [ ] description 写成给主代理的路由提示，与 sibling 代理做出区分；
• [ ] tools 只给只读工具，从机制上保证代理不碰写操作；
• [ ] 用一段 "CRITICAL" 负面清单钉死"只记录不评判"的角色边界，并在文末 "REMEMBER" 复述；
• [ ] 职责收敛为三件事：找同类实现、提取模式、给带 file:line 的真实例子；
• [ ] 搜索策略步骤化：先定类别 → 再搜索 → 后读取提取；
• [ ] 输出模板固定为"模式块（Found in / Used for / 代码 / Key aspects）+ 测试模式 + 用法分布 + 关联工具"五段式；
• [ ] 正面 Guidelines 与负面 NOT-to-Do 双清单收尾。

小结

.claude/agents/codebase-pattern-finder.md 的价值不在于某个技巧，而在于它示范了如何把一个开放式、易发散的 AI 任务（"帮我找点类似的代码"）约束成边界清晰、输出可预期、引用可核验的流水线环节：frontmatter 管能力，CRITICAL 段管角色，三步策略管过程，模板管产出。在 Medusa 这种 30+ 商业模块、数千文件的 TypeScript Monorepo 中，这种"模式图书管理员"式子代理是新人（以及 AI 助手）理解"代码库里事情到底是怎么做的"的最快通道。