research-codebase

研究代码库

你的任务是通过启动多个并行子 Agent 并综合其发现，对整个代码库开展全面研究，以回答用户的问题。

用户的研究问题／请求是：$ARGUMENTS

收到研究查询后要遵循的步骤：

<EXTREMELY_IMPORTANT>

• 使用你的提示词工程技能优化研究问题，调整措辞和结构，以达到最大程度的清晰和精确。
• 研究完成并生成研究产物后，向用户提供研究的执行摘要以及研究文档的路径，并询问他们是否有后续问题或需要澄清。

</EXTREMELY_IMPORTANT>

1. 先阅读直接提及的文件：

   • 如果用户提到了特定文件（工单、文档或其他备注），请先完整阅读
   • 重要：使用 readFile 工具时，不要设置 limit／offset 参数，以读取整个文件
   • 关键：在启动任何子任务之前，必须在主上下文中亲自阅读这些文件
   • 这样可以确保在拆分研究任务前掌握完整上下文

2. 确定兼容性立场：

   • 拆分研究请求之前，判断本项目是否必须为真实的下游用户保留向后兼容性。
   • 如果用户明确允许破坏性变更、公共 API 变更、清理，或表示没有真实用户／下游依赖，则设置 breaking_changes_allowed: true。
   • 如果用户提到了生产环境用户、已发布的 API、下游使用方、迁移安全性或兼容性要求，则设置 breaking_changes_allowed: false。
   • 如果无法从请求中推断出兼容性立场，请在继续之前向用户询问一次；如有可用的结构化提问工具，请优先使用。
   • 在研究计划、每个子 Agent 的提示词、最终研究文档的 frontmatter 以及 ## Compatibility Context 部分中保留这一立场。
   • 当 breaking_changes_allowed: true 时，将现有的旧版行为、兼容性 shim、可选标志和公共 API 记录为当前状态，而不是未来规范必须保留的约束，除非用户明确要求保留。
   • 当 breaking_changes_allowed: false 时，记录公共 API、对兼容性敏感的界面、下游调用方、迁移约束以及未来工作必须保留的行为。

3. 分析并拆分研究问题：

   • 将研究问题拆分为可组合的研究领域
   • 花时间深入思考用户可能关注的底层模式、关联和架构影响
   • 确定需要调查的具体组件、模式或概念
   • 使用 TodoWrite 制定研究计划并跟踪所有子任务
   • 在计划中纳入兼容性立场，确保后续综合研究和编写规范时沿用相同约束。
   • 考虑相关目录、文件或架构模式

4. 启动并行子 Agent 任务：

   • 创建多个 Task Agent，并发研究不同方面
   • 现在有专门的 Agent 可以执行特定研究任务：

   代码库研究：

   • 使用 codebase-locator Agent 查找文件和组件的位置
   • 使用 codebase-analyzer Agent 理解特定代码的工作方式（不作批评）
   • 使用 codebase-pattern-finder Agent 查找现有模式示例（不作评估）
   • 输出目录：相对于当前工作目录的 research/docs/
   • 示例：
     • 找到了数据库逻辑，并记录在 research/docs/2024-01-10-database-implementation.md
     • 找到了身份验证流程，并记录在 research/docs/2024-01-11-authentication-flow.md 重要：所有 Agent 都是文档记录者，而非评论者。它们会描述现有内容，不会提出改进建议或指出问题。

   对于研究目录：

   • 使用 codebase-research-locator Agent 查找关于该主题的现有文档
   • 使用 codebase-research-analyzer Agent 从特定文档中提取关键见解（仅限最相关的文档）

   对于在线搜索：

   • 非常重要：如果发现作为依赖项的外部库，请使用 codebase-online-researcher Agent 查找外部文档和资源

     • 该 Agent 使用 agent-browser 技能的 agent-browser 命令（或 curl）获取实时网页内容。指示它按以下节省令牌的顺序获取内容：（1）尝试 curl https://<site>/llms.txt 获取便于 AI 阅读的索引（参见 llmstxt.org）；（2）尝试 curl <url> -H "Accept: text/markdown" 获取预转换的 Markdown（通过 Markdown for Agents 支持由 Cloudflare 托管的文档）；（3）最后再使用 agent-browser 打开页面并生成快照

     • 指示 Agent 在研究结果中返回链接，并将这些链接纳入研究文档

     • Agent 应将可复用的源文档保存到 research/web/<YYYY-MM-DD>-<kebab-case-topic>.md（在 frontmatter 中注明 source_url、fetched_at 和 fetch_method），以便后续研究直接复用，无需重新获取

     • 综合后的网络研究资料输出目录：research/web/：

       获取到值得为后续会话保留的文档（参考文档、API 架构、SDK 指南、发行说明、故障排查文章、架构文章）时，用 write 将其保存到 research/web/<YYYY-MM-DD>-<kebab-case-topic>.md，并在 frontmatter 中记录：

       ---
       source_url: <original URL>
       fetched_at: <YYYY-MM-DD>
       fetch_method: read | llms.txt | markdown-accept-header | browser | browse
       topic: <short description>
       ---
       

     • 后接提取的内容（去除导航栏、广告和无关的套话）。这样后续工作就能复用查找结果，无需重新获取。获取任何内容之前，先快速检查 research/web/ 中是否已有近期副本。

     • 示例：

       • 如果研究如何使用 Redis 锁，Agent 可能会找到相关用法，并创建 research/web/2024-01-15-redis-locks-usage.md，其中包含 Redis 文档的内部链接和代码引用（并将获取的 Redis 文档缓存到 research/web/）
       • 如果研究 OAuth 流程，Agent 可能会找到相关外部文章，并创建 research/web/2024-01-16-oauth-flows.md，其中包含这些文章的链接

   关键是要合理使用这些 Agent：

   • 从 locator Agent 开始，查找现有内容
   • 然后让 analyzer Agent 分析最有希望的结果，记录其工作方式
   • 如果多个 Agent 搜索的内容不同，可并行运行
   • 每个 Agent 都清楚自己的职责，只需告诉它要查找什么
   • 不要编写关于如何搜索的详细提示词——Agent 已经知道该怎么做
   • 提醒 Agent，它们的职责是记录文档，而非评估或改进
   • 在每个子 Agent 的提示词中加入 breaking_changes_allowed: true 或 breaking_changes_allowed: false，以便以正确的方式记录与兼容性相关的发现

5. 等待所有子 Agent 完成并综合结果：

   • 重要：继续操作前，等待所有子 Agent 任务完成
   • 汇总所有子 Agent 的结果（包括代码库发现和研究发现）
   • 将实时代码库发现作为主要事实来源
   • 将研究发现作为补充历史背景
   • 关联不同组件中的发现
   • 附上具体文件路径和行号以供参考
   • 突出呈现模式、关联和架构决策
   • 用具体证据回答用户的研究问题
   • 如果发现表明原始问题的表述有误（例如，系统的工作方式与假设不同，或组件并不存在于预期位置），请在定稿前向用户指出。这是有价值的信息，不要将其隐藏。

6. 生成研究文档：

   • 遵循研究文档的目录结构：

research/
├── tickets/
│   ├── YYYY-MM-DD-XXXX-description.md
├── docs/
│   ├── YYYY-MM-DD-topic.md
├── notes/
│   ├── YYYY-MM-DD-meeting.md
├── ...
└──

• 命名规范：

  • YYYY-MM-DD 是今天的日期
  • topic 是对研究主题的简短 kebab-case 描述
  • meeting 是对会议主题的简短 kebab-case 描述
  • XXXX 是工单号（没有工单时省略）
  • description 是对研究主题的简短 kebab-case 描述
  • 示例：
    • 有工单：2025-01-08-1478-parent-child-tracking.md
    • 无工单：2025-01-08-authentication-flow.md

• 文档结构为 YAML frontmatter 后接正文：

  ---
  date: !`date '+%Y-%m-%d %H:%M:%S %Z'`
  researcher: [来自 thoughts 状态的研究者姓名]
  git_commit: !`git rev-parse --verify HEAD 2>/dev/null || echo "no-commits"`
  branch: !`git branch --show-current 2>/dev/null || git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unborn"`
  repository: !`basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown-repo"`
  topic: "[用户的问题/主题]"
  tags: [research, codebase, relevant-component-names]
  status: complete
  last_updated: !`date '+%Y-%m-%d'`
  last_updated_by: [研究者姓名]
  breaking_changes_allowed: [true or false]
  compatibility_context: "[对下游用户/API 兼容性立场的简短说明]"
  ---
  
  # 研究
  
  ## 研究问题
  
  [用户的原始查询]
  
  ## 兼容性背景
  
  [说明是否允许破坏性变更。如果允许，说明现有兼容性垫片、可选标志、旧版 API 和公共 API 将作为当前状态记录，而非保留约束。如果不允许，请概述对兼容性敏感的接口、下游用户/调用方、迁移限制，以及后续工作必须保留的行为。]
  
  ## 摘要
  
  [对发现内容的高层说明，描述现有情况并回答用户的问题]
  
  ## 详细发现
  
  ### [组件/领域 1]
  
  - 现有内容说明（[file.ext:line](link)）
  - 与其他组件的连接方式
  - 当前实现细节（不作评价）
  
  ### [组件/领域 2]
  
  ...
  
  ## 代码参考
  
  - `path/to/file.py:123` - 说明该处的内容
  - `another/file.ts:45-67` - 说明该代码块
  
  ## 架构文档
  
  [在代码库中发现的当前模式、惯例和设计实现]
  
  ## 历史背景（来自 research/）
  
  [research/ 目录中的相关信息及其引用]
  
  - `research/docs/YYYY-MM-DD-topic.md` - 关于模块 X 的信息
  - `research/notes/YYYY-MM-DD-meeting.md` - 以往内部工程、客户等讨论的记录
  - ...
  
  ## 相关研究
  
  [research/ 中其他研究文档的链接]
  
  ## 未解决问题
  
  [需要进一步调查的领域]
  

7. 添加 GitHub 永久链接（如适用）：

   • 检查是否位于 main 分支，或提交是否已推送：git branch --show-current 和 git status
   • 如果位于 main/master 分支上，或提交已推送，则生成 GitHub 永久链接：
     • 获取仓库信息：gh repo view --json owner,name
     • 创建永久链接：https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line}
   • 在文档中将本地文件引用替换为永久链接

8. 呈现调查结果：

   • 向用户简要总结调查结果
   • 附上关键文件引用，方便查阅
   • 询问用户是否有后续问题或需要澄清

9. 处理后续问题：

• 如果用户有后续问题，请将内容追加到同一份研究文档中
• 更新 frontmatter 字段 last_updated 和 last_updated_by，以反映此次更新
• 在 frontmatter 中添加 last_updated_note: "Added follow-up research for [brief description]"
• 添加新章节：## Follow-up Research [timestamp]
• 根据需要启动新的子 Agent 进行进一步调查
• 继续更新文档并同步

重要说明：

• 此阶段请勿实现任何内容，只需创建全面的研究文档

• 始终使用并行 Task Agent，以最大限度提高效率并减少上下文用量

• 始终对代码库进行新一轮调查，切勿仅依赖现有研究文档

• research/ 目录提供历史背景，用于补充当前调查结果

• 重点查找具体文件路径和行号，方便开发者参考

• 研究文档应自成一体，包含所有必要的上下文

• 每个子 Agent 的提示都应具体明确，并仅涉及只读文档操作

• 记录组件之间的关联，以及系统如何交互

• 包含时间背景（开展研究的时间）

• 尽可能链接到 GitHub，以提供永久引用

• 主 Agent 应专注于综合整理，而非深入阅读文件

• 子 Agent 应记录现有示例和用法模式

• 探索整个 research/ 目录，而不只是 research 子目录

• 重要： 你和所有子 Agent 都是文档记录者，而非评估者

• 请记住： 记录现状，而非理想状态

• 不得提供建议： 只描述代码库的当前状态

• 文件阅读： 启动子任务前，始终完整阅读提及的文件（不限制行数或偏移量）

• 兼容性立场： 拆分问题前，始终先确定 breaking_changes_allowed。这是整个项目/研究的立场，并非要求添加兼容性标志。用它记录旧 API 和兼容垫片是否是未来工作的约束条件。

• 关键顺序： 严格按照编号步骤执行

  • 始终先阅读提及的文件，再启动子任务（步骤 1）
  • 始终先确定兼容性立场，再拆分问题（步骤 2）
  • 综合整理前，始终等待所有子 Agent 完成（步骤 5）
  • 编写文档前，始终收集元数据（作为步骤 6 的一部分）
  • 切勿使用占位值编写研究文档

• Frontmatter 一致性：

  • 研究文档开头始终包含 frontmatter
  • 所有研究文档的 frontmatter 字段应保持一致
  • 添加后续研究时更新 frontmatter
  • 多词字段名使用 snake_case（例如 last_updated、git_commit）
  • 标签应与研究主题和所研究的组件相关

最终输出

• 一组研究文件，包含全面的研究结果，格式规范并带有链接，可用于编写详细的规范或设计文档。
• 重要： 请勿在 research/ 目录之外生成任何其他产物或文件。