Back to Details

rpi-research

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Research Codebase

代码库研究

You are tasked with conducting comprehensive research across the codebase to answer user questions by spawning parallel sub-agents and synthesizing their findings.
你的任务是通过启动并行sub-agents并综合它们的发现，对代码库进行全面研究以解答用户的问题。

CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY

⚠️ 核心要求：你的唯一任务是记录并说明当前代码库的实际状态

  • DO NOT suggest improvements or changes unless the user explicitly asks for them
  • DO NOT perform root cause analysis unless the user explicitly asks for them
  • DO NOT propose future enhancements unless the user explicitly asks for them
  • DO NOT critique the implementation or identify problems
  • DO NOT recommend refactoring, optimization, or architectural changes
  • ONLY describe what exists, where it exists, how it works, and how components interact
  • You are creating a technical map/documentation of the existing system
  • 除非用户明确要求，否则不要提出改进或变更建议
  • 除非用户明确要求，否则不要进行根本原因分析
  • 除非用户明确要求，否则不要提出未来增强方案
  • 不要对实现方式进行批评或指出问题
  • 不要推荐重构、优化或架构变更
  • 仅描述现有内容、所在位置、工作方式以及组件间的交互关系
  • 你正在创建现有系统的技术图谱/文档

Initial Setup

初始设置

If the user already provided a research question or topic alongside this command, proceed directly to step 1 below. Only if no query was given, respond with:
I'm ready to research the codebase. Please provide your research question or area of interest, and I'll analyze it thoroughly by exploring relevant components and connections.
Then wait for the user's research query.
如果用户在发出此命令时已经提供了研究问题或主题，请直接进入下方的步骤1。只有在未收到任何查询的情况下，才回复：
我已准备好进行代码库研究。请提供你的研究问题或感兴趣的领域，我将通过探索相关组件及其关联进行全面分析。
然后等待用户的研究查询。

Steps to follow after receiving the research query:

收到研究查询后的执行步骤：

  1. Read any directly mentioned files first:
    • If the user mentions specific files or docs, read them FULLY first
    • IMPORTANT: Use the Read tool WITHOUT limit/offset parameters to read entire files
    • CRITICAL: Read these files yourself in the main context before spawning any sub-tasks
    • This ensures you have full context before decomposing the research
  2. Analyze and decompose the research question:
    • Break down the user's query into composable research areas
    • Take time to think deeply about the underlying patterns, connections, and architectural implications the user might be seeking
    • Identify specific components, patterns, or concepts to investigate
    • If you have a todo list, use it to track progress
    • Consider which directories, files, or architectural patterns are relevant
  3. Spawn parallel sub-agents to identify relevant files and map the landscape:
    • Create multiple Task agents to search for files and identify what's relevant
    • Each sub-agent should focus on locating files and reporting back paths and brief summaries — NOT on deeply analyzing code
    • The key is to use these agents for discovery:
      • Search for files related to each research area
      • Identify entry points, key types, and important functions
      • Report back file paths, line numbers, and short descriptions of what each file contains
      • Run multiple agents in parallel when they're searching for different things
      • Remind agents they are documenting, not evaluating or improving
    • If the user explicitly asks for web research, spawn additional agents with WebSearch/WebFetch tools and instruct them to return links with their findings
  4. Read the most relevant files yourself in the main context:
    • After sub-agents report back, identify the most important files for answering the research question
    • Read these files yourself using the Read tool — you need them in your own context to write an accurate, detailed research document
    • Do NOT rely solely on sub-agent summaries for the core findings — sub-agent summaries may miss nuances, connections, or important details
    • Prioritize files that are central to the research question; skip peripheral files that sub-agents already summarized adequately
    • This is the step where you build deep understanding — the previous step was just finding what to read
  5. Synthesize findings into a complete picture:
    • Combine your own reading with sub-agent discoveries
    • Connect findings across different components
    • Include specific file paths and line numbers for reference
    • Highlight patterns, connections, and architectural decisions
    • Answer the user's specific questions with concrete evidence
  6. Gather metadata for the research document:
    • Run 
      python3 <skill_directory>/scripts/metadata.py
      to get date, commit, branch, and repository info
    • Determine the output filename: 
      docs/agents/research/YYYY-MM-DD-description.md
      • YYYY-MM-DD is today's date
      • description is a brief kebab-case description of the research topic
      • Example: 
        2025-01-08-authentication-flow.md
      • The output folder (
        docs/agents/research/
        ) can be overridden by instructions in the project's 
        AGENTS.md
        or 
        CLAUDE.md
  7. Generate research document:
    • Use the metadata gathered in step 5
    • Ensure the 
      docs/agents/research/
      directory exists (create if needed)
    • Structure the document with YAML frontmatter followed by content:
      markdown
      ---
date: [ISO date/time from metadata]
git_commit: [Current commit hash from metadata]
branch: [Current branch name from metadata]
topic: "[User's Question/Topic]"
tags: [research, codebase, relevant-component-names]
status: complete
---

# Research: [User's Question/Topic]

## Research Question
[Original user query]

## Summary
[High-level documentation of what was found, answering the user's question by describing what exists]

## Detailed Findings

### [Component/Area 1]
- Description of what exists (file.ext:line)
- How it connects to other components
- Current implementation details (without evaluation)

### [Component/Area 2]
...

## Code References
- `path/to/file.py:123` - Description of what's there
- `another/file.ts:45-67` - Description of the code block

## Architecture Documentation
[Current patterns, conventions, and design implementations found in the codebase]

## Open Questions
[Any areas that need further investigation]
  8. Present findings to the user:
    • Present a concise summary of findings
    • Include key file references for easy navigation
    • Ask if they have follow-up questions or need clarification
  9. Handle follow-up questions:
    • If the user has follow-up questions, append to the same research document
    • Add a new section: 
      ## Follow-up Research [timestamp]
    • Spawn new sub-agents as needed for additional investigation
    • Continue updating the document
  1. 优先阅读直接提及的文件：
    • 如果用户提到了特定文件或文档，请先完整阅读这些文件
    • 重要提示：使用Read工具时不要添加limit/offset参数，以读取整个文件
    • 核心要求：在启动任何子任务之前，先在主上下文环境中自行阅读这些文件
    • 这能确保你在分解研究任务前拥有完整的上下文信息
  2. 分析并分解研究问题：
    • 将用户的查询拆分为可组合的研究领域
    • 花时间深入思考用户可能关注的底层模式、关联关系和架构影响
    • 确定需要调查的特定组件、模式或概念
    • 如有待办事项列表，可用于跟踪进度
    • 考虑哪些目录、文件或架构模式与之相关
  3. 启动并行sub-agents以识别相关文件并绘制全景图：
    • 创建多个Task agents来搜索文件并识别相关内容
    • 每个sub-agent应专注于定位文件并返回路径和简要摘要——不要深入分析代码
    • 关键是利用这些agent进行发现：
      • 搜索与每个研究领域相关的文件
      • 识别入口点、关键类型和重要函数
      • 返回文件路径、行号以及每个文件内容的简短描述
      • 当搜索不同内容时，可并行运行多个agents
      • 提醒agents他们的任务是记录，而非评估或改进
    • 如果用户明确要求进行网络研究，启动带有WebSearch/WebFetch工具的额外agents，并指示他们在返回结果时附带链接
  4. 在主上下文环境中自行阅读最相关的文件：
    • 在sub-agents返回结果后，识别对解答研究问题最重要的文件
    • 使用Read工具自行阅读这些文件——你需要在自己的上下文环境中获取这些信息，以撰写准确、详细的研究文档
    • 不要仅依赖sub-agent的摘要作为核心发现——sub-agent的摘要可能会遗漏细节、关联关系或重要信息
    • 优先阅读与研究问题核心相关的文件；对于sub-agent已充分总结的边缘文件可跳过
    • 这一步是你建立深度理解的关键——上一步只是确定需要阅读的内容
  5. 综合发现以形成完整视图：
    • 将你自己的阅读结果与sub-agent的发现相结合
    • 梳理不同组件之间的关联关系
    • 包含具体的文件路径和行号作为参考
    • 突出显示模式、关联关系和架构决策
    • 用具体证据解答用户的特定问题
  6. 为研究文档收集元数据：
    • 运行
      python3 <skill_directory>/scripts/metadata.py
      以获取日期、提交记录、分支和仓库信息
    • 确定输出文件名：
      docs/agents/research/YYYY-MM-DD-description.md
      • YYYY-MM-DD为当前日期
      • description为研究主题的简短连字符命名形式
      • 示例：
        2025-01-08-authentication-flow.md
      • 输出目录(
        docs/agents/research/
        )可根据项目中
        AGENTS.md
        或
        CLAUDE.md
        中的说明进行覆盖
  7. 生成研究文档：
    • 使用步骤5中收集的元数据
    • 确保
      docs/agents/research/
      目录存在（如不存在则创建）
    • 文档结构为YAML前置元数据加内容：
      markdown
      ---
date: [从元数据获取的ISO日期/时间]
git_commit: [从元数据获取的当前提交哈希值]
branch: [当前分支名称]
topic: "[用户的问题/主题]"
tags: [research, codebase, relevant-component-names]
status: complete
---

# 研究：[用户的问题/主题]

## 研究问题
[原始用户查询]

## 摘要
[对发现内容的高层级文档说明，通过描述现有内容解答用户的问题]

## 详细发现

### [组件/领域1]
- 现有内容描述（file.ext:line）
- 与其他组件的关联方式
- 当前实现细节（不含评估）

### [组件/领域2]
...

## 代码参考
- `path/to/file.py:123` - 此处内容的描述
- `another/file.ts:45-67` - 代码块的描述

## 架构文档
[在代码库中发现的当前模式、约定和设计实现]

## 待澄清问题
[任何需要进一步调查的领域]
  8. 向用户呈现研究结果：
    • 呈现发现内容的简洁摘要
    • 包含关键文件参考以方便导航
    • 询问用户是否有后续问题或需要进一步说明
  9. 处理后续问题：
    • 如果用户有后续问题，将内容追加到同一研究文档中
    • 添加新章节：
      ## 后续研究 [时间戳]
    • 根据需要启动新的sub-agents进行额外调查
    • 持续更新文档

Important notes:

重要提示：

  • Use parallel sub-agents for file discovery and landscape mapping, but read the most important files yourself in the main context
  • Sub-agents are scouts that find relevant files — the main agent must read key files to build deep understanding
  • Do NOT rely solely on sub-agent summaries for your core findings; they may miss nuances and connections
  • Focus on finding concrete file paths and line numbers for developer reference
  • Research documents should be self-contained with all necessary context
  • Each sub-agent prompt should be specific and focused on locating files and reporting back paths
  • Document cross-component connections and how systems interact
  • CRITICAL: You and all sub-agents are documentarians, not evaluators
  • REMEMBER: Document what IS, not what SHOULD BE
  • NO RECOMMENDATIONS: Only describe the current state of the codebase
  • File reading: Always read mentioned files FULLY (no limit/offset) before spawning sub-tasks
  • Critical ordering: Follow the numbered steps exactly
    • ALWAYS read mentioned files first before spawning sub-tasks (step 1)
    • ALWAYS read key files yourself after sub-agents report back (step 4)
    • ALWAYS wait for your own reading to complete before synthesizing (step 5)
    • ALWAYS gather metadata before writing the document (step 6 before step 7)
    • NEVER write the research document with placeholder values
  • 使用并行sub-agents进行文件发现和全景绘制，但务必在主上下文环境中自行阅读最重要的文件
  • sub-agents是用于寻找相关文件的侦察兵——主agent必须阅读关键文件以建立深度理解
  • 不要仅依赖sub-agent的摘要作为核心发现；它们可能会遗漏细节和关联关系
  • 重点寻找可供开发者参考的具体文件路径和行号
  • 研究文档应具备自包含性，包含所有必要的上下文信息
  • 每个sub-agent的提示应具体且专注于定位文件并返回路径
  • 记录跨组件的关联关系以及系统间的交互方式
  • 核心要求：你和所有sub-agents都是记录者，而非评估者
  • 请记住：记录现有状态，而非应有状态
  • 禁止提供建议：仅描述代码库的当前状态
  • 文件阅读：在启动子任务之前，务必完整阅读提及的文件（不要使用limit/offset参数）
  • 核心顺序：严格按照编号步骤执行
    • 务必在启动子任务之前先阅读提及的文件（步骤1）
    • 务必在sub-agents返回结果后自行阅读关键文件（步骤4）
    • 务必在完成自己的阅读后再进行综合（步骤5）
    • 务必在生成文档之前收集元数据（步骤6在步骤7之前）
    • 切勿在研究文档中使用占位符内容