meta-methodology-research-methodology

研究方法

**快速指南：**研究会把可供另一位 Agent 采取行动的发现交给它，而无需重复搜索。先按名称定位文件，再按内容缩小范围，最后阅读包含答案的文件；每项结论都注明其来源文件、行范围和符号，并连同搜索方式一起报告未找到结果的搜索。有两项工具特性会影响结果的含义。搜索没有返回结果，并不能证明某项内容不存在：Grep 工具会跳过被 git 忽略的文件，Glob 的列表有数量上限，而长文件的 Read 结果可能不完整。在 macOS、Linux 和 WSL 上，Claude Code 默认工具集中不包含 Glob 和 Grep 工具，因此需要在 shell 中通过 find 和 grep 执行相同步骤。

详细资源：

• examples/core.md — 搜索顺序、证据格式、发现模板、路径和缺失项检查、范围界定、进度记录，以及一个完整示例
• reference.md — 各搜索工具会跳过哪些内容、会在哪里截断，当前会话有哪些工具，以及报告前检查清单

---

适用路径

• 你遵循的指令规定了报告格式 — 按该格式填写；本技能提供每个条目应包含的证据及其需要通过的检查。
• 未指定报告格式 — 使用 examples/core.md 中的发现模板。

---

<critical_requirements>

报告发现之前

在将文件路径或内容写入发现之前，先打开文件。 根据惯例推断出的路径只是猜测，而采取行动的 Agent 可能会打开一个并不存在的文件。

每项结论都注明来源文件、行范围和符号。 行范围方便读者一次核对结论；符号则能在编辑导致行号变动后帮助他们再次找到该内容。

连同搜索方式一起报告未找到结果的搜索。 缺失结论的可信度取决于其模式、路径和过滤条件；读者可以重新执行这些搜索，但无法重现你的结论。

调查期间保持代码原样。 调查中途所做的更改会改变证据，读者便无法判断结论对应的是哪个状态。

</critical_requirements>

---

自动检测： X 在哪里定义、X 在此代码库中如何工作、查找类似实现、整理组件 / 端点 / 命令目录、模式发现、代码库调查、架构调查、API 目录、文件:行号引用、使用次数、参考文件、研究发现、Glob、Grep

适用于：

• 查找某种模式位于何处，以及它的遵循情况有多一致
• 整理现有内容 — 组件、API 和端点、命令、配置、架构决策
• 在构建新内容之前，查找最接近的现有实现
• 编写供另一位 Agent 采取行动的发现，避免其重复搜索

由其他流程处理：

• 实施发现所指向的更改 — 研究到确定位置为止，实施及其测试属于单独步骤
• 判断代码是否良好 — 研究报告现状及出现频率；质量和安全结论属于审查工作
• 将发现转化为规格说明 — 范围和验收标准属于规划工作

---

发现的读者并未旁观调查过程。他们无法判断某项结论是直接读到的还是推断出来的，因此值得交接的结论必须可供核查：具体位置、该处代码的实际内容，以及得出结论的搜索方式。需要读者重新推导的发现毫无帮助；错误的发现比没有发现代价更高，因为读者会以此为基础继续工作。

---

<decision_framework>

先进行哪种搜索

What do you already know?
├─ The symbol's name → its definition first (a language server's go-to-definition
│                      where one is running, else a search for the declaration),
│                      then its references
├─ Text the code contains → content search, scoped to the directory if known
├─ What the file would be called → name search, then read the likeliest match
└─ Nothing yet → list the top-level layout, then search by name

调查到什么程度

问题决定交付内容，交付内容决定调查深度。

"How does X work?"          → X's flow: 2–3 exemplary files read end to end
"What exists for X?"        → a catalogue with counts; 1–2 files sampled
"Find similar to Y"         → the closest match, read completely
"How should I implement Z?" → the existing code to follow, in reading order
"Patterns for X?"           → several instances, and where they vary

何时停止

Is the question that was asked answered?
├─ NO  → keep going, inside the question
└─ YES → Does every claim carry a location you read?
         ├─ YES → report
         └─ NO  → read the file now, or drop the claim

</decision_framework>

---

核心模式

模式 1：定位、缩小范围、阅读

先按名称查找候选项，再按内容缩小范围，最后阅读包含答案的文件。每一步的成本都低于下一步，因此只有已确认相关的文件才会进入成本较高的读取阶段。

Glob  "src/**/*error*"                    → 6 candidate files
Grep  "extends AppError" in src/ (count)  → 4 matches in 4 files
Read  src/errors/app-error.ts             → class AppError, lines 8–31

如果会话没有 Glob 或 Grep 工具，shell 中的 find 和 grep 就是相同的两个步骤。

完整演示：examples/core.md

模式 2：基于证据的声明

一条声明，一个位置：文件、行号范围、符号、该处的代码原文，以及实例数量。

AppError base class — src/errors/app-error.ts:8-31, class AppError
Usage: 4 subclasses (Grep "extends AppError" in src/, count mode → 4)

完整格式及其失败版本：examples/core.md

模式 3：结构化发现

如果没有指定报告格式：提供摘要、发现的模式、按顺序阅读的文件、可参照的现有文件、缺口，以及包含未找到结果的搜索的验证表。

## Research Summary        ## Recommended Approach
## Patterns Found           ## Gaps
## Files to Reference       ## Verification Checklist

完整模板：examples/core.md

模式 4：验证路径和缺失项

只有打开文件后，路径才会列入发现；仅在搜索结果中看到的路径应列在“缺口”下，并标明尚未读取。缺失项应与搜索方式一同列出，且必须先经过对照验证——使用相同路径和筛选条件搜索已知存在的内容，以确认搜索确实能找到文本。

Grep "jwt" -i in src/      → 0 matches
Grep "session" -i in src/  → 12 matches   (control: the search works here)
Finding: no JWT handling in src/ — gitignored files not searched

完整代码：examples/core.md

模式 5：聚焦问题范围

报告问题所询问的内容。范围之外的材料，若与答案有关，则在“缺口”下用一行说明；若无关，则省略。

Asked:  How does the API authenticate requests?
Report: the session flow, the route guard, the files to read first
Leave:  database schema, deployment, the client's login form

完整代码：examples/core.md

模式 6：长期研究的进度记录

跨多个软件包的研究应持续记录进度——已检查的文件、发现的模式及其数量、缺口——这样遇到上下文压缩或交接时，就能根据记录继续，而不必依赖记忆。

完整模板：examples/core.md

---

<red_flags>

危险信号

会误导依据发现结果采取行动的 Agent：

• 路径是按惯例推测出来的（utils/formatDate.ts），而不是来自搜索结果——读者打开的文件根本不存在。请写出搜索返回的路径。
• 模式是根据文件名或该框架中的代码库通常采用的做法推断出来的——这描述的是其他代码库。请阅读文件并引用其中内容。
• 根据调用位置描述 API——这只是某个调用方传入的参数，不是约定。请追溯到声明处。
• “大约在第 50 行”“在 auth 模块中”“沿用现有惯例”——读者还得重复你的搜索。请给出文件、范围和符号。
• 从匹配行列表中读取使用次数——列表会在达到工具的结果上限后停止，因此统计结果偏少。请使用计数模式，其总数涵盖所有匹配项。
• 声称“所有路由都使用这种方式”，却没有提供计数依据——读者信任你的结论，结果唯一的例外就会破坏他们的修改。请说明计数和搜索方式。
• 在只询问位置的发现结果中给出实现代码或质量评价——这回答了没人提出的问题，而且缺少实现者所需的上下文。请指出应参照的现有文件。
• 发现结果没有阅读顺序——读者只能随机打开文件。请排出最先打开的两三个文件。

容易出乎意料的行为：

• Grep 工具会跳过被 gitignore 忽略的文件，因此“0 个匹配项”并不能说明生成代码、构建输出或已安装的依赖中没有匹配项。默认情况下，Glob 不会应用 gitignore 过滤，因此它会列出 Grep 根本不会搜索的文件。
• Glob 的结果按修改时间排序，而非相关性排序，且有数量上限；出现截断标记就意味着列表不完整。
• 读取较长文件时，Read 可能只返回第一页，并标记为 PARTIAL view——在此之后断言“文件不包含 X”并未得到验证。
• Grep 模式使用 ripgrep 正则表达式，因此 interface{} 必须写成 interface\{\}。在较早版本的 Claude Code 中，如果模式被 ripgrep 拒绝，或者工具无法读取某个路径，结果会显示为没有匹配项，而不是报错。
• 行号描述的是读取文件时的状态。之后的编辑（包括其他 Agent 的编辑）会导致行号移动，因此范围应与符号一同提供。
• 测试可能展示生产代码已不再采用的模式，配置可能覆盖源码所暗示的内容，而且单体仓库中的每个包都可能遵循各自的惯例。请说明发现结果来自哪里。
• 仍被广泛使用的模式可能标记为 @deprecated；请将其报告为已弃用，而不是建议照搬的惯例。