code-understand

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

3.3k|328|Updated Apr 6, 2026
One-click install
npx skills add https://github.com/Ar9av/obsidian-wiki --skill code-understand
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: code-understand
Source: https://github.com/Ar9av/obsidian-wiki/tree/main/.skills/code-understand
Command: npx skills add https://github.com/Ar9av/obsidian-wiki --skill code-understand

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

When working in an unfamiliar or large codebase, developers waste time grepping and reading files at random to figure out which files and symbols actually matter before making a change. This Skill produces a ranked focus map of the symbols an architecture hangs on, each with a file:line citation, so you read only what matters.

Core Features & Use Cases

  • Ranked Focus Map: Extracts the load-bearing files and symbols of a codebase with file:line citations and evidence types, using CodeGraph when available or a dependency-free builtin extractor (regex AST plus ripgrep cross-file references) otherwise.
  • Scoped Analysis: Seed the map from the full project, specific changed files via --changed, or everything changed since a git ref via --since, with a configurable symbol cap.
  • Use Case: Before refactoring a module you have never read, run the command with --since HEAD~5 to see the blast radius of recent changes, then open only the cited locations to understand who calls what before editing.

Quick Start

Ask your agent to map out this project's architecture and show which files are load-bearing before making changes.

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 obsidian-wiki code-understand --project <dir> to get a ranked focus map of load-bearing symbols with file:line citations. Open only the cited locations instead of reading the whole tree, then form your opinion from the actual source.

How do I find the blast radius of a code change?

Use the --changed flag with specific files or --since with a git ref like HEAD~5 to seed the focus map from your diff. The output ranks symbols connected to those changes so you can see what would break before finishing the edit.

Does code-understand work without CodeGraph installed?

Yes, the auto and builtin backends work with zero setup using a regex AST extractor plus ripgrep cross-file references. CodeGraph adds real call-graph edges, but rg-reference entries from the builtin backend are text matches that should be confirmed by opening the file.

What is the difference between builtin and CodeGraph backends?

The CodeGraph backend produces structural facts from real call-graph edges that can be cited directly. The builtin backend's defines, imports, and changed-file entries are facts, but its rg-reference entries are text-match evidence only and need manual confirmation.

When should I not use a codebase focus map?

Do not use it to summarize what a project does for a wiki; that is handled by wiki-update Step 3b which calls the same extractor internally. Also treat the output as a disposable cache, never committing it to docs or PR descriptions.