Codebase Understanding

Overview

• Bottom-up Analysis: Start analysis from leaf directories and summarize layer by layer upwards
• One-sentence Descriptions: Summarize the function of each class and function in one sentence
• State Persistence: Supports resumable analysis, allowing you to continue after interruption
• Incremental Updates: Only analyze modified files to improve efficiency

Usage Scenarios

1. Understanding New Projects

• "Help me understand the code structure of this project"
• "What does this codebase do? What are the main modules?"
• "I just took over this project and need to understand the overall architecture"

1. Scan the source code directory structure using the Glob tool
2. Initialize the

   .analysis-state.json

   state file
3. Start analysis from leaf directories and generate README.md files
4. Generate README.md files for parent directories layer by layer upwards
5. Finally generate a source code overview README.md in the root directory

2. Generating Technical Documentation

• "Generate complete code documentation for this project"
• "Need a reference document for this codebase"
• "Generate API documentation and architecture descriptions"

1. Check if analysis state exists; if so, continue from there
2. Complete README.md generation for all directories
3. Generate an overall architecture document in the root directory
4. Provide indexes for key files and functions

3. Analyzing Function Implementations

• "Where is this function implemented?"
• "Find the code that handles user login"
• "Track the complete process of order creation"

1. Use the Grep tool to search for keywords (e.g., "login", "authentication")
2. Read relevant files to understand function implementations
3. Track function call chains
4. Mark key processes in the README.md of the corresponding directory

Workflow

Phase 1: Preparation and Scanning

# 1. Identify source code directories
src_dirs = ["src", "lib", "app", "server"]

# 2. Scan directory tree structure
Use Bash tool: find src -type d | sort

# 3. Initialize or load state file
If .analysis-state.json exists → Load state
If not exists → Create new state file

Phase 2: Analyze Leaf Directories

1. List all files in the directory
   javascript

   Glob: **/*.{js,ts,py,java,go,rs,cpp,c,h}

2. Perform analysis on each file
   • Read file content:

     Read(path/to/file)

   • Identify class definitions and function definitions
   • Extract function signatures (function name, parameters, return type)
   • Analyze function body to understand functionality
   Detailed Methods: See references/file-analysis.md
3. Generate one-sentence descriptions
   • Template:

     [Verb] + [Object] + [Method] + [Result]

   • Example:

     Validates user email and password and returns user object

4. Generate README.md
   • Use template: assets/leaf-readme-template.md
   • Write to file:

     Write(path/to/README.md, content)

5. Update state
   json

   {
     "src/utils/auth": {
       "status": "completed",
       "readmeGenerated": true,
       "files": ["login.js", "register.js"],
       "fileHashes": { "login.js": "abc123", ... }
     }
   }

Phase 3: Analyze Branch Directories

1. Read README.md files of all subdirectories
   javascript

   for (subdir of subdirs) {
     readme = Read(subdir/README.md);
     Extract "Directory Overview" section;
   }

2. Analyze files in the current directory (if any)
   • Same file analysis method as leaf directories
3. Generate README.md
   • Use template: assets/branch-readme-template.md
   • Include summary of subdirectory overviews
   • Include analysis of current directory files
4. Update state
   json

   {
     "src/services": {
       "status": "completed",
       "subdirs": ["user", "order", "payment"],
       "completedSubdirs": ["user", "order", "payment"]
     }
   }

Phase 4: Generate Root Directory Documentation

1. Collect overviews of all first-level directories
2. Analyze tech stack
   • Read package.json / requirements.txt / pom.xml
   • Identify main dependencies and frameworks
3. Generate architecture diagram
   • Identify layered structure
   • Draw module relationship diagram
4. Generate README.md
   • Use template: assets/root-readme-template.md

State Management and Resumable Analysis

State File Location

Project root directory/.analysis-state.json

State Check and Recovery

if (exists('.analysis-state.json')) {
  state = load('.analysis-state.json');
  print("Existing analysis state found:");
  print(`Completed: ${state.stats.analyzedDirectories}/${state.stats.totalDirectories}`);
  print("Resuming from last interruption...");
} else {
  print("First-time analysis, initializing state file...");
  state = init();
}

pending_dirs = state.get_pending_directories();
for (dir of pending_dirs) {
  if (state.should_analyze(dir)) {
    analyze_directory(dir);
  }
}

Incremental Update Strategy

1. Calculate MD5 hash of files
2. Compare with hashes saved in the state file
3. If hashes are different → File has been modified, re-analyze
4. If hashes are the same → Skip, use existing results

Language Support

JavaScript / TypeScript

export class UserService { }
export function createUser() { }
export const validate = () => { }

Python

class UserService:
def create_user():
async def fetch_data():

Java

public class UserService { }
public void createUser() { }

Go

type UserService struct { }
func CreateUser() { }
func (s *UserService) Method() { }

Function Description Specifications

One-sentence Description Template

[Verb] + [Object] + [Method] + [Result]

Query [conditions] from [data source]

[Verb] + [Object] + [Result]

[Verb] + [Object] + [Conversion]

Quality Standards

• Validates user login credentials and returns JWT token
• Calculates total discount amount of items in shopping cart
• Retrieve user session information from Redis

• Process data (too vague)
• Helper function (no functional explanation)
• get, set (lack of context)

Output Document Structure

project/
├── README.md (Root directory overview)
├── src/
│   ├── README.md (src overview)
│   ├── utils/
│   │   ├── README.md (utils directory description)
│   │   ├── auth/
│   │   │   ├── README.md (auth module detailed description)
│   │   │   ├── login.js
│   │   │   └── register.js
│   │   └── date/
│   │       ├── README.md (date module detailed description)
│   │       └── helpers.js
│   └── services/
│       ├── README.md (services description)
│       ├── user/
│       │   ├── README.md (user service description)
│       │   └── service.js
│       └── order/
│           ├── README.md (order service description)
│           └── service.js

Best Practices

1. Parallel Processing

• Leaf directories can be analyzed in parallel
• Use Task tool to start multiple Explore agents working in parallel
• Parent directories must wait for subdirectories to complete

2. Progress Tracking

TodoWrite([
  { content: "Analyze src/utils/auth/", status: "in_progress" },
  { content: "Analyze src/utils/date/", status: "pending" },
  { content: "Generate src/utils/ README.md", status: "pending" }
]);

3. Error Handling

1. Record errors to state file
2. Mark directory as "failed"
3. Continue processing other directories
4. Provide error report at the end

4. Performance Optimization

• Use Glob instead of find command to search files
• Batch read files to reduce I/O operations
• Process independent directories in parallel
• Use file hashes to avoid repeated analysis

5. Quality Check

• ✅ All files have been analyzed
• ✅ All classes and functions have descriptions
• ✅ Descriptions are concise and accurate
• ✅ Markdown format is correct

Execution Examples

Example 1: Analyze Small Project

// 1. Scan directories
dirs = Glob("src/**")
// ["src/utils", "src/services", "src/models"]

// 2. Identify leaf directories
leaf_dirs = ["src/utils/auth", "src/utils/format", "src/services/user"]

// 3. Analyze leaf directories in parallel
for (dir of leaf_dirs) {
  analyze_leaf_directory(dir);
}

// 4. Analyze parent directories
analyze_branch_directory("src/utils");
analyze_branch_directory("src/services");

// 5. Generate root directory
generate_root_readme("src");

Example 2: Resume Interrupted Analysis

// 1. Load state
state = load_state(".analysis-state.json");

// 2. Get pending directories
pending = state.get_pending_directories();
// ["src/services/order", "src/services/payment"]

// 3. Continue analysis
for (dir of pending) {
  analyze_directory(dir);
}

// 4. Complete remaining parent directories
if (all_subdirs_completed("src/services")) {
  analyze_branch_directory("src/services");
}

Frequently Asked Questions

Q: What if the analysis is interrupted?

Q: Do I need to re-analyze after code modifications?

Q: How to analyze only specific directories?

Q: Will the generated README.md overwrite existing files?

Resources

references/

• state-management.md: Detailed implementation of state management and resumable analysis
• file-analysis.md: File analysis methods and language-specific patterns

assets/

• leaf-readme-template.md: Leaf directory README template
• branch-readme-template.md: Branch directory README template
• root-readme-template.md: Root directory README template