mrosati84 Codebase Analysis Skill
Use this skill when asked to inspect, explain, refactor, extend, debug, or assess an unfamiliar codebase.
Goals
- Build a concise mental model of the codebase.
- Identify entry points, core modules, data flow, and external dependencies.
- Identify all existing runnable scripts (ex: run the dev server, build, deployment, etc.)
- Surface risks, conventions, and likely impact areas.
- Produce actionable findings before proposing code changes.
Process
- Inspect the codebase structure.
- Read top-level docs:
README.md,AGENTS.md/CLAUDE.md, architecture notes, contributing docs, and setup files. - Identify languages, frameworks, libraries, package managers, build tools, test and run commands.
- Locate application entry points and configuration files.
- Trace the relevant feature path from input to output.
- Check tests, fixtures, CI workflows, and lint/type settings.
- Summarize findings with file references and uncertainty.
Heuristics
- Prefer reading existing conventions over inventing new patterns.
- Do not assume framework behavior when config or code contradicts defaults.
- Treat generated, vendored, minified, and lock files as supporting evidence only.
- Search for similar implementations before designing a new one.
- Verify public APIs, side effects, and persistence boundaries before editing.
Output Format
Provide:
Overview: what the codebase does.Architecture: main components and how they interact.Relevant files: files inspected and why they matter.Execution path: request/event/job flow, if applicable.Dependencies: important internal and external dependencies.Risks: fragile areas, missing tests, unclear behavior.Next steps: recommended investigation or implementation plan.
Guardrails
- Do not make broad claims without file evidence.
- Mark guesses explicitly as assumptions.
- Do not edit code until the impact area is understood.
- Keep the summary concise and focused on the user’s task.