code-understand

Generates a ranked, citation-backed focus map of load-bearing symbols in a codebase.

Updated Nov 9, 2023
One-click install
npx skills add https://github.com/oresttokovenko/dot-files --skill code-understand-oresttokovenko
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: code-understand
Source: https://github.com/oresttokovenko/dot-files/tree/main/chezmoi/dot_agents/skills/code-understand
Command: npx skills add https://github.com/oresttokovenko/dot-files --skill code-understand-oresttokovenko

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Orienting in an unfamiliar or large codebase usually means grepping around and reading files at random. This Skill produces a ranked focus map of the files and symbols an architecture actually depends on, each with a file:line citation, so you read only what matters before making a change. ## Core Features & Use Cases - Ranked focus map: Extracts the load-bearing symbols of a project with file:line citations and evidence types, using CodeGraph when installed or a dependency-free builtin extractor (regex AST plus ripgrep cross-file references) otherwise. - Flexible seeding: Scan the whole project, seed from specific changed files, or seed from everything changed since a git ref to assess the blast radius of a diff. - Use Case: Before refactoring a module you have never read, run the focus map to see who calls it and what it calls, then open only the cited locations instead of scanning the entire tree. ## Quick Start Ask the agent to run a code-understand focus map on the current project and explain which files are load-bearing before making your planned change.

Frequently Asked Questions about code-understand

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I understand an unfamiliar codebase before making changes?

Run the code-understand command on the project directory to get a ranked focus map of load-bearing symbols with file:line citations. Then open only the cited locations instead of reading the whole tree or grepping at random.

How to find who calls a function across a codebase?

Seed the focus map with the file containing the function using the --changed flag. With the CodeGraph backend you get real call-graph edges; with the builtin backend, ripgrep text matches indicate possible references that you should confirm by opening the cited files.

Does code-understand work without installing CodeGraph?

Yes, the auto and builtin backends work with zero setup using a regex AST extractor plus ripgrep. CodeGraph is an optional enhancement that adds structural cross-file call-graph evidence, and it should only be installed with the user's approval.

How do I check the blast radius of a git diff?

Pass --since with a git ref such as HEAD~5 or a base branch, or repeat --changed for each file in your diff. The focus map then seeds from those files and ranks the symbols whose changes could propagate.

What are the limitations of the builtin extractor backend?

The builtin backend's rg-reference entries are text-match evidence only, not confirmed structural relationships, so you must open the cited file to verify. Its defines, imports, and changed-file entries are factual, and the output is a disposable cache, not documentation to commit.