codebase-analyzer

Core Principle: Institutional Memory > One-off Analysis

Every analysis updates a knowledge file that future runs build on. Never start from zero.

<quick_start>

1. Check: Does .claude/CODEBASE.md exist?

   • No → Full Scan mode
   • Yes → Update mode

2. Full Scan: Glob entry points → Read architecture → Grep patterns → Find smells → Create knowledge file

3. Update: Read existing → git diff → Update changed sections → Add timestamp </quick_start>

<success_criteria>

• .claude/CODEBASE.md created/updated with current timestamp
• Architecture mapped (2-5 bullet points with file refs)
• Patterns documented in table format
• Smells categorized by severity (HIGH/MED/LOW) with checkboxes
• Decisions captured with rationale and source
• Output report shows key findings and recommendations </success_criteria>

1. Detect stack — Language, framework, database, infrastructure

   Glob: "**/main.py", "**/index.ts", "**/package.json", "**/requirements.txt"
   

2. Map architecture — Entry points, feature structure, data flow

   Read: main entry files
   Glob: "**/router*.py", "**/routes/**", "**/api/**"
   

3. Identify patterns — What conventions does this codebase follow?

   Grep: "@router|@app|Depends|BaseModel"
   Grep: "repository|service|schema"
   

4. Find smells — DRY violations, god files, unclear boundaries

   # Find large files
   find . -name "*.py" -exec wc -l {} + | sort -rn | head -20
   

5. Document decisions — From comments, commit history, docs

   Grep: "# TODO|# HACK|# NOTE|# Why"
   

6. Create knowledge file — Sharp observations only

   Write: .claude/CODEBASE.md (see template in references/)
   

1. Read existing knowledge

   Read: .claude/CODEBASE.md
   

2. Check what changed

   git diff --name-only HEAD~10
   # Or since last analysis date from CODEBASE.md
   

3. Read changed files

   Read: [changed files from diff]
   

4. Update affected sections

   • Architecture: if entry points or structure changed
   • Patterns: if new conventions discovered
   • Smells: add new, mark fixed with [x]
   • Decisions: if new rationale found

5. Update timestamp

   **Last analyzed:** [current date]
   

1. Verify file exists and is readable
2. Check markdown structure is parseable (has expected ## sections)
3. If corrupted or malformed:
   • Back up to .claude/CODEBASE.md.backup
   • Recreate with full scan

After creating/updating:

1. Verify all required sections present
2. Check file:line references are valid
3. Ensure no duplicate smells entries

<knowledge_file> Location: .claude/CODEBASE.md (in project root)

Template: See references/knowledge-file-template.md

Required Sections:

Section	Content	Format
Architecture	Entry points, structure, data flow	2-5 bullets
Patterns	Conventions with file:line refs	Table
Smells	Issues with severity	Checkbox list
Decisions	Why things are this way	Table
API Surface	Key endpoints by feature	Grouped list
Dependencies	External services	Table

Quality Rules:

1. Sharp, not verbose — Each bullet is actionable
2. File:line references — Always cite specific locations
3. Severity levels — HIGH/MED/LOW for smells
4. Checkbox for smells — [ ] open, [x] fixed
5. Tables over prose — Scannable > readable
6. Update timestamps — Know when analysis is stale </knowledge_file>