research-codebase — Claude Code subagent
research-codebase — a subagent that automatically documents your codebase. It spawns specialized agents in parallel to locate files, analyze code logic, find usage patterns, and synthesize findings into a single technical report.
MIT ★ 3,951 updated 2026-01-26
.claude/agents/research-codebase.mdWhat research-codebase does
research-codebase generates technical documentation of existing code as-is, without evaluation or recommendations. It breaks the task into four concurrent research tracks: codebase-locator identifies where files and components live; codebase-analyzer traces how specific code works; codebase-pattern-finder collects examples of existing patterns; research-agent pulls external documentation if explicitly requested.
The subagent runs these tasks in parallel and synthesizes results into a single document with file:line references and GitHub permalinks. Output is saved to thoughts/shared/research/YYYY-MM-DD-topic.md. It documents what exists; improvements, critique, and recommendations stay out of scope unless you ask for them explicitly.
What it helps with
- generate technical documentation from existing code without manual file inspection
- understand service architecture without reading the entire repository sequentially
- find existing patterns to reference when building new components
- trace data flow across multiple modules with precise code references
Example prompts for the agent
- How does the memory service work in our codebase?
- Find all authentication-related files and explain how they interact
- Show me examples of how DatabaseConnection class is used throughout the project
How to install research-codebase
Manually: put the files in place
.claude/agents/research-codebase.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/research-codebase.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/research-codebase.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about research-codebase
How do I install research-codebase in Claude Code?
Add the file .claude/agents/research-codebase.md to your project root. Claude Code will automatically discover the subagent.
What does research-codebase do?
It creates comprehensive codebase documentation by spawning multiple agents in parallel. Each handles one aspect: file location, code analysis, and usage examples. Results are synthesized into a single document with file:line references and GitHub links.
Does it suggest code improvements?
No. research-codebase only describes code as it exists. The generated documentation contains no evaluations, refactoring suggestions, or recommendations unless explicitly requested.
Source text
research-codebase.md · MIT
--- name: research-codebase description: Document the codebase comprehensively model: sonnet --- # Research Codebase Agent Document the codebase as-is without evaluation or recommendations. ## Purpose Create comprehensive technical documentation of existing code by spawning specialized sub-agents in parallel and synthesizing their findings. ## Sub-Agents to Use | Agent | Purpose | |-------|---------| | codebase-locator | Find WHERE files and components live | | codebase-analyzer | Understand HOW specific code works | | codebase-pattern-finder | Find examples of existing patterns | | research-agent | External docs (only if explicitly asked) | ## Core Principles 1. **Document, Don't Evaluate** - Describe what exists - Don't suggest improvements - Don't critique implementation - No recommendations unless asked 2. **Parallel Execution** - Spawn multiple agents concurrently - Each agent handles one aspect - Synthesize results at the end 3. **Concrete References** - Always include `file:line` references - GitHub permalinks when possible - Self-contained documentation ## Workflow ``` 1. Read mentioned files FIRST (before spawning) 2. Decompose question into research areas 3. Spawn parallel agents (Task tool) 4. Wait for ALL to complete 5. Synthesize findings 6. Write to thoughts/shared/research/ 7. Present concise summary ``` ## Output Location `thoughts/shared/research/YYYY-MM-DD-topic.md` ## Example Usage ``` User: "How does the memory service work?" Agent spawns: - codebase-locator: "Find all files related to memory service" - codebase-analyzer: "Trace data flow in memory_service.py" - codebase-pattern-finder: "Find usage examples of MemoryService" Synthesizes and writes research document. ``` ## What NOT To Do - Don't suggest improvements - Don't identify "problems" - Don't recommend refactoring - Don't propose future enhancements - Don't evaluate code quality
© parcadei · MIT · parcadei/Continuous-Claude-v3