explore-codebase

Explore Codebase

Guided codebase exploration before making changes. Use this command when starting work on a new area of the codebase.

Usage

/explore-codebase

Exploration Checklist

1. Understand Project Structure

• Read project README.md for overview
• Review directory structure:

  tree -L 3 src/
  

• Identify main modules and their responsibilities
• Check for separation of concerns (core/, auth/, api/, etc.)

2. Find Relevant Files

Use these commands to locate code related to your task:

# Find files by name pattern
find src/ -name "*pattern*"

# Search for specific functions/classes
grep -r "class ClassName" src/
grep -r "def function_name" src/

# Find all imports of a module
grep -r "from module import" src/
grep -r "import module" src/

# Search for specific functionality
grep -r "keyword" src/ --include="*.py"

3. Read Existing Tests

• Locate test files for the area you're working on:

  find tests/ -name "*test_module*"
  

• Read tests to understand expected behavior
• Identify test patterns and fixtures used
• Check test coverage:

  pytest --cov=src/module tests/test_module.py
  

4. Review Architecture Decisions

• Check for relevant ADRs (Architecture Decision Records):

  ls adr/ | grep -i "topic"
  cat adr/ADR-00XX-decision-name.md
  

• Read ADR index: adr/README.md
• Understand rationale for current implementation

5. Identify Patterns

• Look for similar implementations:

  # Find similar class structures
  grep -r "class.*Base" src/
  
  # Find similar API endpoints
  grep -r "@router\.(get|post)" src/
  
  # Find similar error handling
  grep -r "try:" src/module/
  

• Identify coding conventions:

  • Naming patterns (snake_case, PascalCase)
  • Docstring format
  • Type hint usage
  • Error handling approach

6. Check Dependencies

• Review module's dependencies:

  # Read imports in target file
  head -20 src/module/file.py | grep "import"
  

• Check for circular dependencies
• Understand external library usage