8.2 KiB
8.2 KiB
name, description, allowed-tools
| name | description | allowed-tools |
|---|---|---|
| deep-analysis | Proactively investigates codebases to understand complex patterns, trace multi-file flows, analyze architecture decisions, and provide comprehensive code insights. Use when users ask about code structure, implementation details, or need to understand how features work. | Task |
Deep Code Analysis
This Skill provides comprehensive codebase investigation capabilities using the codebase-detective agent with semantic search and pattern matching.
When to use this Skill
Claude should invoke this Skill when:
- User asks "how does [feature] work?"
- User wants to understand code architecture or patterns
- User is debugging and needs to trace code flow
- User asks "where is [functionality] implemented?"
- User needs to find all usages of a component/service
- User wants to understand dependencies between files
- User mentions: "investigate", "analyze", "find", "trace", "understand"
- User is exploring an unfamiliar codebase
- User needs to understand complex multi-file functionality
Instructions
Phase 1: Determine Investigation Scope
Understand what the user wants to investigate:
- Specific Feature: "How does user authentication work?"
- Find Implementation: "Where is the payment processing logic?"
- Trace Flow: "What happens when I click the submit button?"
- Debug Issue: "Why is the profile page showing undefined?"
- Find Patterns: "Where are all the API calls made?"
- Analyze Architecture: "What's the structure of the data layer?"
Phase 2: Invoke codebase-detective Agent
Use the Task tool to launch the codebase-detective agent with comprehensive instructions:
Use Task tool with:
- subagent_type: "code-analysis:detective"
- description: "Investigate [brief summary]"
- prompt: [Detailed investigation instructions]
Prompt structure for codebase-detective:
# Code Investigation Task
## Investigation Target
[What needs to be investigated - be specific]
## Context
- Working Directory: [current working directory]
- Purpose: [debugging/learning/refactoring/etc]
- User's Question: [original user question]
## Investigation Steps
1. **Initial Search**:
- Use semantic search (claude-context MCP) if available
- Otherwise use grep/ripgrep/find for patterns
- Search for: [specific terms, patterns, file names]
2. **Code Location**:
- Find exact file paths and line numbers
- Identify entry points and main implementations
- Note related files and dependencies
3. **Code Flow Analysis**:
- Trace how data/control flows through the code
- Identify key functions and their roles
- Map out component/service relationships
4. **Pattern Recognition**:
- Identify architectural patterns used
- Note code conventions and styles
- Find similar implementations for reference
## Deliverables
Provide a comprehensive report including:
1. **📍 Primary Locations**:
- Main implementation files with line numbers
- Entry points and key functions
- Configuration and setup files
2. **🔍 Code Flow**:
- Step-by-step flow explanation
- How components interact
- Data transformation points
3. **🗺️ Architecture Map**:
- High-level structure diagram
- Component relationships
- Dependency graph
4. **📝 Code Snippets**:
- Key implementations (show important code)
- Patterns and conventions used
- Notable details or gotchas
5. **🚀 Navigation Guide**:
- How to explore the code further
- Related files to examine
- Commands to run for testing
6. **💡 Insights**:
- Why the code is structured this way
- Potential issues or improvements
- Best practices observed
## Search Strategy
**With MCP Claude-Context Available**:
- Index the codebase if not already indexed
- Use semantic queries for concepts (e.g., "authentication logic")
- Use natural language to find functionality
**Fallback (No MCP)**:
- Use ripgrep (rg) or grep for pattern matching
- Search file names with find
- Trace imports manually
- Use git grep for repository-wide search
## Output Format
Structure your findings clearly with:
- File paths using backticks: `src/auth/login.ts:45`
- Code blocks for snippets
- Clear headings and sections
- Actionable next steps
Phase 3: Present Analysis Results
After the agent completes, present results to the user:
-
Executive Summary (2-3 sentences):
- What was found
- Where it's located
- Key insight
-
Detailed Findings:
- Primary file locations with line numbers
- Code flow explanation
- Architecture overview
-
Visual Structure (if complex):
EntryPoint (file:line) ├── Validator (file:line) ├── BusinessLogic (file:line) │ └── DataAccess (file:line) └── ResponseHandler (file:line) -
Code Examples:
- Show key code snippets inline
- Highlight important patterns
-
Next Steps:
- Suggest follow-up investigations
- Offer to dive deeper into specific parts
- Provide commands to test/run the code
Phase 4: Offer Follow-up
Ask the user:
- "Would you like me to investigate any specific part in more detail?"
- "Do you want to see how [related feature] works?"
- "Should I trace [specific function] further?"
Example Scenarios
Example 1: Understanding Authentication
User: "How does login work in this app?"
Skill invokes codebase-detective agent with:
"Investigate user authentication and login flow:
1. Find login API endpoint or form handler
2. Trace authentication logic
3. Identify token generation/storage
4. Find session management
5. Locate authentication middleware"
Agent provides:
- src/api/auth/login.ts:34-78 (login endpoint)
- src/services/authService.ts:12-45 (JWT generation)
- src/middleware/authMiddleware.ts:23 (token validation)
- Flow: Form → API → Service → Middleware → Protected Routes
Example 2: Debugging Undefined Error
User: "The dashboard shows 'undefined' for user name"
Skill invokes codebase-detective agent with:
"Debug undefined user name in dashboard:
1. Find Dashboard component
2. Locate where user name is rendered
3. Trace user data fetching
4. Check data transformation/mapping
5. Identify where undefined is introduced"
Agent provides:
- src/components/Dashboard.tsx:156 renders user.name
- src/hooks/useUser.ts:45 fetches user data
- Issue: API returns 'full_name' but code expects 'name'
- Fix: Map 'full_name' to 'name' in useUser hook
Example 3: Finding All API Calls
User: "Where are all the API calls made?"
Skill invokes codebase-detective agent with:
"Find all API call locations:
1. Search for fetch, axios, http client usage
2. Identify API client/service files
3. List all endpoints used
4. Note patterns (REST, GraphQL, etc)
5. Find error handling approach"
Agent provides:
- 23 API calls across 8 files
- Centralized in src/services/*
- Using axios with interceptors
- Base URL in src/config/api.ts
- Error handling in src/utils/errorHandler.ts
Success Criteria
The Skill is successful when:
- ✅ User's question is comprehensively answered
- ✅ Exact code locations provided with line numbers
- ✅ Code relationships and flow clearly explained
- ✅ User can navigate to code and understand it
- ✅ Architecture patterns identified and explained
- ✅ Follow-up questions anticipated
Tips for Optimal Results
- Be Comprehensive: Don't just find one file, map the entire flow
- Provide Context: Explain why code is structured this way
- Show Examples: Include actual code snippets
- Think Holistically: Connect related pieces across files
- Anticipate Questions: Answer follow-up questions proactively
Integration with Other Tools
This Skill works well with:
- MCP claude-context: For semantic code search
- MCP gopls: For Go-specific analysis
- Standard CLI tools: grep, ripgrep, find, git
- Project-specific tools: Use project's search/navigation tools
Notes
- The codebase-detective agent uses extended thinking for complex analysis
- Semantic search (MCP) is preferred but not required
- Agent automatically falls back to grep/find if needed
- Results are actionable and navigable
- Great for onboarding to new codebases
- Helps prevent incorrect assumptions about code