name

codebase-analysis

description

TRIGGER when user asks to analyze, document, understand, or review a codebase or code module. Use when user wants to: generate technical docs, trace data flow, analyze algorithms, document data structures, understand architecture, or review code logic. Triggers on: 'analyze code', 'codebase analysis', 'document this code', 'understand this project', 'trace data flow', '算法分析', '代码分析', '代码梳理', '数据结构分析', '技术文档'. DO NOT trigger for: simple file reading, single-function explanation, general coding questions.

level

version

2.1

triggers

codebase analysis

analyze codebase

代码分析

代码梳理

数据结构分析

algorithm flow

argument-hint

<target_directory_or_module>

Codebase Analysis Skill

Purpose: Perform rigorous, code-based analysis of software projects to generate comprehensive technical documentation similar to the fastlivo2-tech-docs reference style.

What This Skill Does

This skill systematically analyzes a codebase and produces detailed markdown documentation covering:

System Overview (系统概述) - Architecture, modules, and relationships
Data Structures (数据结构详解) - Detailed breakdown of all key data structures
Data Flow (数据流分析) - How data moves through the system
Algorithm Flows (算法流程) - Core algorithms with step-by-step analysis
Key Functions (关键函数分析) - Deep dive into critical functions

Key Principle: All analysis is strictly based on actual code - no hallucinations, no assumptions without verification.

When to Use

Invoke this skill when you need to:

Understand a complex codebase systematically
Create technical documentation for a project
Analyze data structures and their relationships
Trace data flow and algorithms
Generate codebase reference materials
Review and document architecture decisions

Output Format

Each analysis module generates a corresponding .md file with:

Code references with file:line:column citations
ASCII diagrams for visualization
Verification checkpoints
Cross-references between documents
Consistent structure across all documents

Usage

/codebase-analysis <target_directory>
/codebase-analysis src/core
/codebase-analysis --module=StateEstimator

Methodology (9 Phases for Deep Analysis)

Phase 0: Project Context Detection & Auto-Initialization (项目上下文检测与自动初始化) ⭐ NEW

Purpose: Ensure CLAUDE.md exists for enhanced context, or auto-generate it Time: < 1 second (if CLAUDE.md exists) or 1-3 minutes (auto-/init) Output: Project context metadata + CLAUDE.md (generated if needed)

Steps:

Detect CLAUDE.md

if [ -f "CLAUDE.md" ]; then
  echo "✓ Found CLAUDE.md - reading project context"
  # Extract: project type, build commands, conventions
  # Continue to Phase 1
else
  echo "ℹ No CLAUDE.md found - auto-generating with /init"
  # Proceed to step 2: Auto-initialization
fi

Auto-initialization (if CLAUDE.md missing)

# Only runs if CLAUDE.md doesn't exist
echo "🔄 Running /init to generate CLAUDE.md..."
echo "   This may take 1-3 minutes..."
/init

# After /init completes:
echo "✓ CLAUDE.md generated"
echo "🔄 Reloading context with CLAUDE.md..."

# Clear current context (implementation-specific)
# Re-read CLAUDE.md with fresh context

echo "✓ Context loaded with CLAUDE.md enhancement"
echo ""
echo "Note: /init took ~X minutes. This is a one-time cost."
echo "      Future analyses will use existing CLAUDE.md (~2 seconds)."

Verify CLAUDE.md loaded

# After auto-init or if already existed
if [ -f "CLAUDE.md" ]; then
  echo "✓ CLAUDE.md context available for analysis"
  # Extract key information:
  # - Project overview
  # - Build commands
  # - Dependencies
  # - Architecture
  # - Conventions
else
  echo "⚠️  CLAUDE.md not available - using code structure analysis"
  # Fallback to code-only analysis (still works!)
fi

Detect project type (enhanced with CLAUDE.md)

# Primary: From CLAUDE.md (if available and accurate)
# Fallback: From code structure

if grep -q "Project Type" CLAUDE.md 2>/dev/null; then
  PROJECT_TYPE=$(grep "Project Type" CLAUDE.md)
elif [ -f "package.xml" ] || [ -f "CMakeLists.txt" ]; then
  PROJECT_TYPE="ROS/Catkin"
elif [ -f "Cargo.toml" ]; then
  PROJECT_TYPE="Rust"
# ... etc

Detect build system

# Primary: From CLAUDE.md build commands
# Fallback: From build files

if grep -q "catkin_make" CLAUDE.md 2>/dev/null; then
  BUILD_SYSTEM="CMake (Catkin)"
elif [ -f "CMakeLists.txt" ]; then
  BUILD_SYSTEM="CMake"
# ... etc

Checkpoint:

CLAUDE.md exists (either found or auto-generated)?
Project type detected?
Build system identified?
Context loaded (with or without CLAUDE.md)?

Key Principle:

✅ Auto-ensure CLAUDE.md: Generate if missing for better context
✅ Transparent: User sees what's happening
✅ One-time cost: /init runs once, then reused
✅ Fallback: Works even if /init fails

Behavior Changes:

Before (v2.0): No CLAUDE.md → code-only analysis
After (v2.1): No CLAUDE.md → auto-/init → enhanced analysis

User Experience:

# First time on fresh clone
$ /codebase-analysis /path/to/fresh/clone

ℹ No CLAUDE.md found - auto-generating with /init
🔄 Running /init to generate CLAUDE.md...
   This may take 1-3 minutes...
[init output...]
✓ CLAUDE.md generated
🔄 Reloading context with CLAUDE.md...
✓ Context loaded with CLAUDE.md enhancement

Note: /init took ~2 minutes. This is a one-time cost.
      Future analyses will use existing CLAUDE.md (~2 seconds).

✓ Phase 0: Context Detection Complete
[Continues to Phase 1...]

See: INIT_GUIDE.md for detailed fresh clone handling

⚠️ MANDATORY PRE-REQUISITE: Read WORKFLOW.md First

CRITICAL: Before starting any analysis, you MUST read WORKFLOW.md which contains the mandatory verification workflow.

Core Rule: All analysis MUST be based on actual code. Every claim MUST have a [VERIFY:] tag. No exceptions.

Workflow: Code Reading → Draft Generation → Verification → Fix Discrepancies → Final Output

Quality Gates: Cannot proceed to next phase without passing verification checkpoints.

Phase 1: Global Exploration (全局探索)

⚠️ MANDATORY: Read actual source files first
Identify project structure and key modules
Map dependencies and relationships
Understand framework and architecture
⚠️ NEW: Generate complete module inventory

Checkpoint:

Can you point to specific files for each claim?
NEW: All modules/threads enumerated?
NEW: Complexity assessed for each?

Phase 1.5: Analysis Planning (分析规划) ⭐ NEW

⚠️ MANDATORY: Generate explicit Phase 4 plan
Map Phase 1 modules to Phase 4 documents
Prioritize by complexity/importance
Generate PHASE4_PLAN.md
⚠️ MANDATORY: All Phase 1 items must have Phase 4 coverage

Output: PHASE4_PLAN.md

Complete list of algorithm documents to generate
Expected length per document
Code locations for each
Mathematical focus areas
Execution order

Checkpoint:

Every identified module has corresponding Phase 4 plan?
All threads covered?
Estimated total length ≥ 10,000 lines?

See: PHASE1_ENHANCED.md for detailed methodology

Phase 2: Data Structure Analysis (关键数据结构详细梳理)

⚠️ MANDATORY: Read struct/class definitions from code
Enumerate all key data structures
Document fields, methods, and relationships
Create structure diagrams with ASCII art
Cross-reference actual code definitions

Checkpoint: Every structure has [VERIFY: file:line] tag?

Phase 3: Data Flow Analysis (数据流梳理)

⚠️ MANDATORY: Trace through actual code execution
Trace data movement through the system
Identify transformation points
Document inputs and outputs at each stage
Validate against actual code execution paths

Checkpoint: All flow steps traceable to code?

Phase 4: Algorithm Deep Dive (算法深度分析) ⭐ NEW

⚠️ MANDATORY: Read algorithm implementation line-by-line
Mathematical formulations with complete derivations
Step-by-step execution flow with intermediate states
Complexity analysis with bottlenecks identified
Comparison with alternative approaches
Design rationale for algorithmic choices
Every formula verified against code
Generate: ALGORITHM_XX-[Name].md (1500-3000 lines each)

Checkpoint: Every derivation has code evidence?

Phase 5: Key Function Analysis (关键函数内部流程梳理)

⚠️ MANDATORY: Read function implementation completely
Deep dive into critical functions
Internal logic flow with line-by-line analysis
Dependencies and call graphs
Verification against implementation
Performance profiling data

Checkpoint: Each line analysis references actual code?

Phase 6: Q&A Documentation (问题解答文档) ⭐ NEW

⚠️ MANDATORY: All answers backed by code evidence
Answer "Why" questions about design decisions
Explain "How" questions about implementation
Provide configuration guidance for different scenarios
Document common pitfalls and solutions
Generate: KEY_QUESTIONS-[Module].md (500-1000 lines each)

Checkpoint: Every answer has [VERIFY:] tag?

Phase 7: Verification and Review (复核校准) ⚠️ MANDATORY

See WORKFLOW.md for complete verification protocol

⚠️ MANDATORY: Automated verification of all [VERIFY:] tags
⚠️ MANDATORY: Manual code cross-reference checking
⚠️ MANDATORY: Mathematical formula validation
⚠️ MANDATORY: Fix all discrepancies before output
⚠️ MANDATORY: Zero tolerance for hallucinations
Cross-check all claims against code
Validate code references
Ensure no hallucinations
Mathematical correctness verification
Peer review checklist

Quality Gate: Cannot generate final output until:

100% of [VERIFY:] tags validated
All discrepancies fixed
Zero hallucinations detected
All formulas match code

Quality Guarantees

Every analysis document MUST include:

Code Evidence: Every claim references actual code with file:line
Verification Tags: [VERIFY: relative/path/file:line] on EVERY claim
Anti-Hallucination: Zero speculation without code evidence
Consistency: Uniform structure and formatting
Traceability: Clear line from claim to code evidence

⚠️ MANDATORY REQUIREMENT:

If you cannot provide a [VERIFY:] tag, DO NOT make the claim
If you haven't read the code, DO NOT speculate
If uncertain, DELETE the content entirely

See: WORKFLOW.md for mandatory verification protocol

File System Structure

codebase-analysis-skill/
├── SKILL.md                    # Claude Code native auto-discovery
├── skill.md                    # OMC skill definition (this file)
├── WORKFLOW.md                 # ⭐ MANDATORY verification workflow (READ FIRST!)
├── README.md                   # Usage guide
├── Gotchas.md                  # Common pitfalls (MOST IMPORTANT)
├── CHANGELOG.md                # Version history
├── CONTRIBUTING.md             # Contribution guide
├── LICENSE                     # MIT License
├── templates/                  # Document generation templates
│   ├── system_overview.md      # Architecture overview
│   ├── data_structures.md      # Data structure breakdown
│   ├── algorithm_flow.md       # ⭐ Deep algorithm analysis (v2.0)
│   └── key_questions.md        # ⭐ Q&A documentation (v2.0)
├── verification/               # Verification tools
│   ├── verify_all_refs.sh      # ⭐ Automated [VERIFY:] tag checker
│   ├── verify_analysis.sh      # Full analysis verification
│   └── code_reference_checklist.md  # Manual verification checklist
├── helpers/                    # Helper scripts
│   ├── ascii_diagrams.sh       # ASCII diagram utilities
│   └── code_ref_formatter.sh   # Code reference formatting
├── docs/                       # Detailed methodology docs
│   ├── ANALYSIS_FLOW.md        # Progressive refinement explained
│   ├── INIT_GUIDE.md           # CLAUDE.md handling strategy
│   ├── PHASE1_ENHANCED.md      # Phase 1 enhanced methodology
│   └── PHASE4_GUIDE.md         # Algorithm deep dive guide
└── examples/                   # Usage examples
    └── example-output.md       # Sample output from Voxel-SLAM

Critical Files (read in this order):

WORKFLOW.md - Mandatory verification workflow
Gotchas.md - Common pitfalls to avoid
skill.md - This file (methodology overview)

Progressive Disclosure

This skill uses file system structure for progressive disclosure (Tip 3 from skill creation guide):

Core: skill.md loaded first
Templates: Loaded when analysis begins
Helpers: Loaded when generating output
Verification: Loaded during review phase

This prevents overwhelming Claude with all context at once.

Gotchas (Common Pitfalls)

This is the most valuable section - learned from real analysis failures.

See Gotchas.md for detailed coverage of:

Hallucinating features not in code
Misinterpreting data structures
Missing critical code paths
Incorrect data flow assumptions
Verification blind spots

Verification Requirements

Every document must pass:

✅ All claims reference actual code (file:line:column)
✅ ASCII diagrams match code structure
✅ Data flows validated by execution tracing
✅ No speculative statements without evidence
✅ Cross-references resolve correctly
✅ Verification checkpoints completed

Example Output Style

Reference: fastlivo2-tech-docs (reference repo)

Key characteristics:

Bilingual (Chinese + English) where appropriate
Multi-layer structure (Concept → Structure → Operation → Integration → Summary)
Extensive ASCII diagrams
Actual code snippets with line numbers
Step-by-step algorithm breakdowns
Verification checklists at end of each section

Next Steps: When this skill is invoked:

FIRST: Read WORKFLOW.md (mandatory verification protocol)
SECOND: Read Gotchas.md (common pitfalls)
THEN: Begin with Phase 1 and proceed systematically
ALWAYS: Verify all claims against code before proceeding to next phase
FINALLY: Pass all quality gates before generating output

Non-negotiable: Zero tolerance for unverified claims or hallucinations.

FilesExpand file tree

skill.md

Latest commit

History

skill.md

File metadata and controls

Codebase Analysis Skill

What This Skill Does

When to Use

Output Format

Usage

Methodology (9 Phases for Deep Analysis)

Phase 0: Project Context Detection & Auto-Initialization (项目上下文检测与自动初始化) ⭐ NEW

⚠️ MANDATORY PRE-REQUISITE: Read WORKFLOW.md First

Phase 1: Global Exploration (全局探索)

Phase 1.5: Analysis Planning (分析规划) ⭐ NEW

Phase 2: Data Structure Analysis (关键数据结构详细梳理)

Phase 3: Data Flow Analysis (数据流梳理)

Phase 4: Algorithm Deep Dive (算法深度分析) ⭐ NEW

Phase 5: Key Function Analysis (关键函数内部流程梳理)

Phase 6: Q&A Documentation (问题解答文档) ⭐ NEW

Phase 7: Verification and Review (复核校准) ⚠️ MANDATORY

Quality Guarantees

File System Structure

Progressive Disclosure

Gotchas (Common Pitfalls)

Verification Requirements

Example Output Style