research-codebase

研究代码库

你的任务是全面研究代码库，必要时启动并行子 Agent，然后综合其发现。

关键：你的唯一任务是记录并说明代码库当前的实际情况

• 除非明确要求，否则不要建议改进或更改
• 除非明确要求，否则不要提出未来的增强方案
• 只描述现有内容、所在位置、工作方式以及各组件如何交互
• 你要创建的是现有系统的技术地图／文档

操作步骤

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

   • 如果用户提及了特定文件，请先完整阅读这些文件
   • 关键：在启动任何子任务之前，必须先在主上下文中亲自阅读这些文件
   • 这样可以确保在拆分研究任务前掌握完整背景

2. 分析并拆解研究目标：

   • 深入思考研究目标，并将其拆分为可组合的研究领域
   • 花时间充分思考其中的底层模式、联系和架构影响。
   • 确定需要调查的具体组件、模式或概念
   • 使用 TodoWrite/write_todos 制定研究计划，以跟踪所有子任务
   • 考虑相关目录、文件或架构模式

3. 启动并行子 Agent，开展全面研究：

   • 创建多个 Task Agent，并发研究不同方面

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

   • 先启动定位 Agent，查找现有内容
   • 再让分析 Agent 研究最有希望的发现
   • 搜索不同内容时，可并行运行多个 Agent

4. 等待所有子 Agent 完成并综合研究结果：

   • 重要：继续之前，务必等待所有子 Agent 任务完成
   • 汇总所有子 Agent 的结果（包括代码库发现和思考结果）
   • 优先以代码库当前内容作为主要事实依据
   • 将 dev/log/ 作为补充历史背景
   • 将不同组件的发现联系起来
   • 引用具体文件路径和行号
   • 突出说明发现的模式、联系、架构见解和设计决策
   • 以具体证据回答用户的具体问题

5. 收集研究文档的元数据：

   • 生成所有相关元数据
   • 文件名：dev/research/YYYYMMDD-description.md
     • 格式：YYYYMMDD-description.md，其中：
       • YYYYMMDD 为当天日期
       • description 为简短的 kebab-case 研究主题描述
     • 示例：
       • 20251010-parent-child-tracking.md
       • 20260114-authentication-flow.md

6. 生成研究文档：

   • 使用第 4 步收集的元数据

   • 按以下结构撰写文档：先写 YAML frontmatter，再写正文

     ---
     date: [当前 ISO 格式的日期和时间，含时区]
     topic: "[用户的问题／主题]"
     tags: [research, codebase, relevant-component-names]
     status: complete
     last_updated: [当前日期，格式为 YYYY-MM-DD]
     ---
     
     # 研究：[用户的问题／主题]
     
     **日期**：[第 4 步中的当前日期和时间，含时区]
     
     ## 研究问题
     
     [原始查询或研究目标]
     
     ## 摘要
     
     [高层次发现]
     
     ## 详细发现
     
     ### [组件／领域 1]
     
     - 附有参考来源的发现（[file.ext:line](link)）
     - 与其他组件的联系
     - 实现细节
     
     ### [组件／领域 2]
     
     ...
     
     ## 代码引用
     
     - `path/to/file.py:123` - 说明此处的内容
     - `another/file.ts:45-67` - 说明此代码块的内容
     
     ## 架构见解
     
     [发现的模式、惯例和设计决策]
     
     ## 历史背景（来自 dev/log/）
     
     [dev/log/ 目录中的相关见解及其参考来源]
     - `dev/log/something.md` - 关于 X 的历史决策
     - `dev/log/notes.md` - Y 的过往实现
     
     ## 相关研究
     
     [指向 dev/research/ 中其他研究文档的链接]
     
     ## 待解决问题
     
     [任何需要进一步调查的领域]
     

7. 同步并呈现研究结果：

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

8. 处理后续问题：

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

重要说明：

• 始终并行使用 Task Agent，以最大限度提高效率并减少上下文用量
• 始终对代码库进行全新研究，绝不要只依赖现有研究文档
• dev/log/ 目录提供历史背景，可用于补充实时研究结果
• 重点查找具体文件路径和行号，方便开发者参考
• 研究文档应自包含，并提供所有必要背景信息
• 每个子 Agent 的提示词都应具体明确，并限定为只读操作
• 考虑跨组件关联和架构模式
• 包含时间背景（研究开展的时间）
• 主 Agent 应专注于综合整理，而不是深入阅读文件
• 鼓励子 Agent 查找示例和使用模式，而不只是定义
• 探索整个 dev/ 目录，而不仅仅是 research 子目录
• 文件读取：启动子任务前，始终完整读取提及的文件（不使用 limit/offset）
• 关键顺序：严格按照编号步骤执行
  • 始终先读取提及的文件，再启动子任务（步骤 1）
  • 综合整理前，始终等待所有子 Agent 完成（步骤 4）
  • 写入文档前，始终收集元数据（步骤 5 在步骤 6 之前）
  • 绝不使用占位值编写研究文档
• Frontmatter 一致性：
  • 研究文档开头始终包含 frontmatter
  • 所有研究文档中的 frontmatter 字段保持一致
  • 添加后续研究时更新 frontmatter
  • 多词字段名使用 snake_case（例如 last_updated、git_commit）
  • 标签应与研究主题和所研究的组件相关