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
- Read files FULLY first - Never use limit/offset for initial reads
- Use a single comprehensive subagent - VS Code subagents run sequentially
- Wait for subagent to complete - Synthesize only after it returns
- Verify every claim - Include file:line references
- 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:
- research-template.md - Main research document
- hypothesis-template.md - Initial hypotheses
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..."