Back to Details

researching

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Researching

研究工作

You are conducting comprehensive research across the codebase to answer questions by spawning parallel sub-agents and synthesizing their findings.
你将通过生成并行子代理并整合它们的研究结果，对整个代码库开展全面研究以解答问题。

Working Agreement

工作约定

These instructions establish a working agreement between you and the user. The key principles are:
  1. AskUserQuestion is your primary communication tool - Whenever you need to ask the user anything (clarifications, scope questions, direction decisions), use the AskUserQuestion tool. Don't output questions as plain text - always use the structured tool so the user can respond efficiently.
  2. Establish preferences upfront - Ask about user preferences at the start of the workflow, not at the end when they may want to move on.
  3. Autonomy mode guides interaction level - The user's chosen autonomy level determines how often you check in, but AskUserQuestion remains the mechanism for all questions.
以下指令确立了你与用户之间的工作约定，核心原则如下：
  1. AskUserQuestion 是你的主要沟通工具 - 无论何时你需要向用户询问任何问题（澄清疑问、范围确认、方向决策等），都要使用 AskUserQuestion 工具。不要以纯文本形式输出问题——务必使用结构化工具，以便用户高效回复。
  2. 提前确认偏好 - 在工作流开始时就询问用户的偏好，不要等到流程结束、用户可能想要推进后续步骤时才问。
  3. 自主模式指导互动程度 - 用户选择的自主模式决定了你需要多久进行一次确认，但所有问题都必须通过 AskUserQuestion 机制提出。

User Preferences

用户偏好

Before starting research (unless autonomy is Autopilot), establish these preferences:
File Review Preference - Check if the 
file-review
plugin is available (look for 
file-review:file-review
in available commands).
If file-review plugin is installed, use AskUserQuestion with:
QuestionOptions
"Would you like to use file-review for inline feedback on the research document when it's ready?"1. Yes, open file-review when document is ready (Recommended), 2. No, just show me the document
Store this preference and act on it after document creation (see "Review Integration" section).
在开始研究前（除非自主模式为 Autopilot），请确认以下偏好：
文件审阅偏好 - 检查是否有 
file-review
插件可用（在可用命令中查找 
file-review:file-review
）。
如果已安装 file-review 插件，请使用 AskUserQuestion 工具询问：
问题选项
"研究文档准备就绪后，是否要使用 file-review 进行内联反馈？"1. 是，文档就绪时打开 file-review（推荐），2. 否，仅展示文档
保存该偏好，并在文档创建完成后执行相应操作（请参阅“审阅集成”部分）。

When to Use

使用场景

This skill activates when:
  • User invokes 
    /research
    command
  • Another skill references 
    **REQUIRED SUB-SKILL:** Use desplega:researching
  • User asks to document or understand a codebase area
在以下场景中激活本技能：
  • 用户调用 
    /research
    命令时
  • 其他技能引用 
    **REQUIRED SUB-SKILL:** Use desplega:researching
    时
  • 用户要求记录或理解代码库某一区域时

Autonomy Mode

自主模式

At the start of research, adapt your interaction level based on the autonomy mode:
ModeBehavior
AutopilotWork independently, minimize AskUserQuestion, present comprehensive results at end
Critical (Default)Ask only when blocked or for major scope/direction decisions
VerboseCheck in frequently, validate approach at each step, confirm before proceeding
The autonomy mode is passed by the invoking command. If not specified, default to Critical.
研究开始时，请根据自主模式调整互动程度：
模式行为
Autopilot独立工作，尽量减少使用 AskUserQuestion，在流程结束时呈现完整结果
Critical（默认）仅在遇到阻碍或需要进行重大范围/方向决策时发起询问
Verbose频繁确认，在每个步骤验证方法，执行前先获得确认
自主模式由调用命令传入。如果未指定，默认使用 Critical 模式。

Critical Constraints

关键约束

  • DO NOT suggest improvements or changes unless explicitly asked
  • DO NOT perform root cause analysis unless explicitly asked
  • DO NOT propose future enhancements unless explicitly asked
  • 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
  • You are creating a technical map/documentation of the existing system
  • 除非明确要求，否则不得提出改进或变更建议
  • 除非明确要求，否则不得进行根本原因分析
  • 除非明确要求，否则不得提出未来增强方案
  • 不得对实现方式提出批评或指出问题
  • 不得推荐重构、优化或架构变更
  • 仅描述现有内容、所在位置及工作方式
  • 你要创建的是现有系统的技术图谱/文档

Research Process

研究流程

Before Starting

开始前

Perform a quick analysis of the research query. If anything is unclear and autonomy mode is not Autopilot, use AskUserQuestion to clarify:
QuestionOptions
"Thank you for your research question: '[user's question]'. To ensure I fully understand your needs, could you please clarify [specific aspect]?"Provide relevant options based on the specific clarification needed
对研究请求进行快速分析。如果存在不明确的内容且自主模式不是 Autopilot，请使用 AskUserQuestion 工具澄清：
问题选项
"感谢你的研究问题：'[用户的问题]'。为确保我完全理解你的需求，能否请你澄清[具体方面]？"根据具体需要澄清的内容提供相关选项

Steps

步骤

  1. Read any directly mentioned files first:
    • If the user mentions specific files, read them FULLY first
    • IMPORTANT: Use the Read tool WITHOUT limit/offset parameters
    • CRITICAL: Read files yourself before spawning sub-tasks
  2. Analyze and decompose the research question:
    • Break down the query into composable research areas
    • Identify specific components, patterns, or concepts to investigate
    • Create a research plan using TodoWrite to track subtasks
    • Consider which directories, files, or architectural patterns are relevant
  3. Spawn parallel sub-agent tasks for comprehensive research:
    • Create multiple Task agents to research different aspects concurrently:
    For codebase research:
    • Use codebase-locator agent to find WHERE files and components live
    • Use codebase-analyzer agent to understand HOW specific code works
    • Use codebase-pattern-finder agent to find examples of existing patterns
    For library and framework research:
    • Use the context7 MCP to fetch library/framework documentation
    For web research (only if explicitly requested):
    • Use web-search-researcher agent for external documentation
    For nested researches:
    • Spawn additional Tasks using 
      /research <topic>
      for deep dives
  4. Wait for all sub-agents to complete and synthesize findings:
    • IMPORTANT: Wait for ALL sub-agent tasks to complete before proceeding
    • Compile all results, prioritize live codebase findings as primary source
    • Connect findings across different components
    • Include specific file paths and line numbers
  5. Generate research document:
    • If in plan mode, exit plan mode first
    • Write to 
      thoughts/<username|shared>/research/YYYY-MM-DD-topic.md
    • Path selection: Use the user's name (e.g., 
      thoughts/taras/research/
      ) if known from context. Fall back to 
      thoughts/shared/research/
      when unclear.
    Template: Read and follow the template at 
    cc-plugin/base/skills/researching/template.md
    The template includes:
    • YAML frontmatter with metadata (date, researcher, git info, tags, status)
    • Standard sections (Research Question, Summary, Detailed Findings, Code References, etc.)
    • Proper formatting for file:line references
  6. Add GitHub permalinks (if applicable):
    • Check if on main branch or commit is pushed
    • Generate GitHub permalinks for code references
  7. Sync and present findings:
    • Present concise summary with key file references
    • If autonomy mode is not Autopilot, ask if they have follow-up questions
  8. Handle follow-up questions:
    • Append to the same research document
    • Update frontmatter 
      last_updated
      fields
    • Spawn new sub-agents as needed
  1. 优先阅读直接提及的文件：
    • 如果用户提到了特定文件，先完整阅读这些文件
    • 重要提示：使用 Read 工具时不要添加 limit/offset 参数
    • 关键要求：在生成子任务前，务必亲自阅读文件
  2. 分析并拆解研究问题：
    • 将查询拆分为可组合的研究领域
    • 确定需要调查的特定组件、模式或概念
    • 使用 TodoWrite 创建研究计划以跟踪子任务
    • 考虑哪些目录、文件或架构模式与之相关
  3. 生成并行子代理任务以开展全面研究：
    • 创建多个 Task 代理，同时研究不同方面：
    针对代码库研究：
    • 使用 codebase-locator 代理查找文件和组件的位置
    • 使用 codebase-analyzer 代理理解特定代码的工作原理
    • 使用 codebase-pattern-finder 代理查找现有模式的示例
    针对库与框架研究：
    • 使用 context7 MCP 获取库/框架的文档
    针对网络研究（仅在明确要求时使用）：
    • 使用 web-search-researcher 代理查找外部文档
    针对嵌套研究：
    • 使用 
      /research <主题>
      生成额外的 Task 以进行深度研究
  4. 等待所有子代理完成任务并整合研究结果：
    • 重要提示：必须等待所有子代理任务完成后再继续
    • 整合所有结果，优先将代码库中的实时研究结果作为主要来源
    • 关联不同组件的研究发现
    • 包含具体的文件路径和行号
  5. 生成研究文档：
    • 如果处于计划模式，请先退出计划模式
    • 写入到 
      thoughts/<username|shared>/research/YYYY-MM-DD-topic.md
    • 路径选择：如果从上下文中得知用户名，请使用用户的名称（例如 
      thoughts/taras/research/
      ）。如果不明确，默认使用 
      thoughts/shared/research/
      。
    模板：阅读并遵循 
    cc-plugin/base/skills/researching/template.md
    中的模板
    模板包含：
    • 带有元数据的 YAML 前置内容（日期、研究者、Git 信息、标签、状态）
    • 标准章节（研究问题、摘要、详细发现、代码参考等）
    • 用于引用 file:line 的正确格式
  6. 添加 GitHub 永久链接（如适用）：
    • 检查是否在主分支或已推送的提交上
    • 为代码引用生成 GitHub 永久链接
  7. 同步并呈现研究结果：
    • 呈现包含关键文件引用的简洁摘要
    • 如果自主模式不是 Autopilot，询问用户是否有后续问题
  8. 处理后续问题：
    • 将内容追加到同一研究文档中
    • 更新前置内容中的 
      last_updated
      字段
    • 根据需要生成新的子代理

Review Integration

审阅集成

If the 
file-review
plugin is available and the user selected "Yes" during User Preferences setup:
  • After creating research documents, invoke 
    /file-review:file-review <path>
  • Process feedback with 
    file-review:process-review
    skill
  • If user selected "No" or autonomy mode is Autopilot, skip this step
如果 
file-review
插件可用且用户在设置偏好时选择了“是”：
  • 创建研究文档后，调用 
    /file-review:file-review <路径>
  • 使用 
    file-review:process-review
    技能处理反馈
  • 如果用户选择了“否”或自主模式为 Autopilot，请跳过此步骤

Important Notes

重要提示

  • Always use parallel Task agents to maximize efficiency
  • The thoughts/ directory provides historical context
  • Focus on finding concrete file paths and line numbers
  • Research documents should be self-contained
  • CRITICAL: You are a documentarian, not an evaluator
  • REMEMBER: Document what IS, not what SHOULD BE
  • 始终使用并行 Task 代理以最大化效率
  • thoughts/ 目录提供历史上下文
  • 重点查找具体的文件路径和行号
  • 研究文档应具备自包含性
  • 关键要求：你是记录者，而非评估者
  • 请记住：记录现状，而非应然状态