codebase-research

代码库研究模式与方法,用于理解错误上下文。用于调查代码工作原理、查找相关文件或理解代码流程。

📖 中文导读:代码库研究模式与方法,用于理解错误上下文。用于调查代码工作原理、查找相关文件或理解代码流程。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: codebase-research description: Patterns and methods for researching a codebase to understand bug context. Use when investigating how code works, finding related files, or understanding code flow. license: MIT compatibility: VS Code Insiders with GitHub Copilot metadata: author: accruent version: "2.0" based-on: HumanLayer research_codebase pattern

Codebase Research

This skill provides research patterns for bug investigation, following the HumanLayer documentarian philosophy.

Core Principles

The Documentarian Philosophy

From HumanLayer's research_codebase pattern:

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

  • DO NOT suggest improvements or changes
  • DO NOT perform root cause analysis (that's a separate phase)
  • DO NOT critique the implementation
  • ONLY describe what exists, where it exists, how it works

Research Best Practices

  1. Read files FULLY first - Never use limit/offset for initial reads
  2. Use a single comprehensive subagent - VS Code subagents run sequentially
  3. Wait for subagent to complete - Synthesize only after it returns
  4. Verify every claim - Include file:line references
  5. Stay factual - No opinions, evaluations, or suggestions

VS Code Copilot Tool Reference

Tool Identifier Purpose Example Usage
search/codebase Semantic search Find conceptually related code
search/fileSearch File name patterns Find *.test.ts files
search/textSearch Grep-style search Find exact error messages
search/usages Symbol usages Trace function calls
read/readFile Read file contents Get full context
web/githubRepo Git/GitHub info Historical context
runSubagent Spawn subagent Comprehensive research
edit/editFiles Create files Save research documents

Subagent Research Pattern

Since VS Code subagents run sequentially (not in parallel), combine all research tasks into a single comprehensive subagent prompt:

Use a subagent to perform comprehensive codebase research for bug {TICKET-ID}.

## Research Tasks

### Task 1: Locate Relevant Code
Find all locations related to: {bug symptoms}
- Search for: {keywords, function names, error messages}
- Return: Table of file:line references

### Task 2: Analyze Code Flow
For relevant files, document:
- Entry points, data flow, dependencies, exit points
- Return: Flow diagram with file:line citations

### Task 3: Find Related Patterns
Search for:
- Similar code, related tests, documentation
- Return: Examples with file:line references

## Rules
- Document only, no evaluations
- Include file:line for every claim

Research Document Structure

hypothesis.md

Initial investigation hypotheses created before research:

  • Symptom analysis
  • Investigation areas with search targets
  • Priority order

codebase-research.md

Comprehensive research findings:

  • Code locations table
  • Execution flow diagram
  • Dependencies and relationships
  • Exact code snippets with citations

verified-research.md

Verification of research accuracy:

  • Claim verification tables
  • Corrections made
  • Confidence ratings

Templates

See the templates folder for:

Forbidden Patterns

Never use these phrases in research documents:

  • "This could be improved by..."
  • "A better approach would be..."
  • "This is a code smell..."
  • "Consider refactoring..."
  • "The problem is..."
  • "This should be..."

References