Codebase Summary

Generate comprehensive codebase documentation optimized for AI assistants and developers.

Parameters

Gather all parameters upfront in a single prompt:

Workflow

Step 1: Setup

1. •Validate codebase_path exists
2. •Create output_dir if needed
3. •If update_mode and index.md exists:
   • •Run git log --oneline -20 to identify recent changes
   • •Focus analysis on modified components

Step 2: Analyze Structure

Run the structure analyzer:

python {baseDir}/scripts/analyze_structure.py "{codebase_path}" --depth 4 --output "{output_dir}/codebase_info.md"

Run the dependency extractor:

python {baseDir}/scripts/extract_dependencies.py "{codebase_path}" --output "{output_dir}/dependencies.md"

Then manually analyze:

• •Identify packages, modules, major components
• •Map architectural patterns (MVC, microservices, etc.)
• •Find key interfaces, APIs, entry points

Step 3: Generate Documentation

Create these files in {output_dir}/:

index.md - Primary AI context file:

• •AI instructions for using the documentation
• •Quick reference table mapping questions to files
• •Table of contents with summaries for each file
• •Brief codebase overview

architecture.md:

• •System architecture with Mermaid graph diagram
• •Layer descriptions
• •Design patterns used
• •Key design decisions with rationale

components.md:

• •Component overview with Mermaid classDiagram
• •Per-component: purpose, location, key files, dependencies, interface

interfaces.md:

• •API endpoints with request/response formats
• •Internal interfaces and implementations
• •Error codes and handling

data_models.md:

• •ER diagram with Mermaid erDiagram
• •Per-model: table, fields, indexes, relationships

workflows.md:

• •Key processes with Mermaid sequenceDiagram
• •Step-by-step breakdowns
• •Error handling

See {baseDir}/references/documentation-templates.md for templates.

Step 4: Review

If check_consistency:

• •Verify terminology consistency across documents
• •Check cross-references are valid

If check_completeness:

• •Identify undocumented components
• •Note gaps from language/framework limitations

Save findings to {output_dir}/review_notes.md.

Step 5: Consolidate (if enabled)

If consolidate is true:

1. •Create file at codebase root (not in output_dir)
2. •Use consolidate_target as filename
3. •Tailor content to target:

Default AGENTS.md prompt: Focus on information NOT in README.md or CONTRIBUTING.md—file purposes, directory structure, coding patterns, testing instructions, package guidance.

Step 6: Summary

Report:

1. •What was documented
2. •Next steps for using documentation
3. •How to add index.md to AI assistant context
4. •If update_mode: summarize detected changes

Output Structure

{consolidate_target}           # At codebase root if consolidate=true
{output_dir}/
├── index.md                   # Primary AI context (read this first)
├── codebase_info.md          # Structure analysis output
├── architecture.md           # System architecture
├── components.md             # Component details
├── interfaces.md             # APIs and interfaces
├── data_models.md            # Data models
├── workflows.md              # Key workflows
├── dependencies.md           # Dependencies output
└── review_notes.md           # Review findings

Progress Indicators

Provide updates:

Setting up...
✅ Created {output_dir}

Analyzing structure...
✅ Found X packages across Y languages
✅ Identified Z components

Generating documentation...
✅ Created index.md
✅ Generated architecture.md, components.md...

Reviewing...
✅ Consistency check complete
✅ Found N gaps documented in review_notes.md

Done!
✅ Documentation at {output_dir}
✅ Primary context file: {output_dir}/index.md

Resources

• •Scripts: {baseDir}/scripts/analyze_structure.py, {baseDir}/scripts/extract_dependencies.py
• •Templates: {baseDir}/references/documentation-templates.md