К основному содержанию
скилл CX Codex

codebase-map — скилл для Claude Code: карта проекта и установка

Скилл codebase-map для Claude Code разбирает незнакомый репозиторий и собирает карту его архитектуры. Запускается по просьбе объяснить устройство проекта или проследить путь запроса.

MIT ★ 541 обновлён 2026-11-09

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add dotslashsimran/simcraft --skill codebase-map -a claude-code
Открыть на GitHub

Что делает codebase-map

Скилл читает README, манифесты, CI, модели данных и историю Git, строит граф импортов и прослеживает один реальный запрос или команду во время запуска. Результат — MAP.md с диаграммой Mermaid, переходами по файлам и строкам, горячими точками, связями между файлами, глоссарием и первыми задачами; скрипт может создать и SVG.

Работа с репозиторием ведётся только на чтение, а промежуточные файлы складываются во временную папку, если не запрошен MAP.md в проекте. Скрипты используют стандартную библиотеку Python 3.9+ и Git. Для установки через Claude Code нужна команда npx; шаги анализа могут запускать код проекта, но миграции и действия с общей базой данных или реальными учётными данными запрещены.

Какие задачи решает

  • разобраться, что делает незнакомый репозиторий
  • найти файлы на пути пользовательского запроса
  • выявить циклы импортов и горячие точки
  • подготовить карту архитектуры для нового участника команды

Примеры запросов агенту

  • Объясни устройство этого репозитория и создай MAP.md.
  • Проследи, где обрабатывается запрос на вход пользователя.
  • Покажи горячие точки и связи между файлами в этом проекте.

Как установить codebase-map

1Через Skills CLI (Vercel)

npx skills add dotslashsimran/simcraft --skill codebase-map -a claude-code

2Вручную: положить файлы

~/.claude/skills/codebase-map/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/codebase-map/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о codebase-map

Как установить codebase-map в Claude Code?

Выполни npx skills add dotslashsimran/simcraft --skill codebase-map -a claude-code. Файл скилла находится по пути ~/.claude/skills/codebase-map/SKILL.md.

Что делает codebase-map?

Изучает структуру проекта, историю Git и граф импортов, затем запускает один сценарий и фиксирует путь выполнения. Итоговая карта сохраняется в MAP.md, при необходимости создаётся SVG.

Что нужно для работы codebase-map?

Для скриптов нужны Python 3.9+ и Git. Запуск анализируемого проекта выполняется по шагам CI; миграции и действия с общей базой данных или реальными учётными данными запрещены.

Исходный текст

SKILL.md · MIT
---
name: codebase-map
description: Understand an unfamiliar codebase fast, the way senior engineers do. Reads the orientation signals (README, manifests, CI, Dockerfiles, routes, migrations), mines git history for hotspots, hidden coupling and ownership, builds the import graph to find layers, cycles, load-bearing and dead code, then traces one real request or command end to end by actually running it. Writes MAP.md with a one-paragraph purpose, a Mermaid architecture diagram, the traced path as file:line hops, hotspot and coupling tables, a glossary, gotchas and first tasks, plus an optional SVG. Use when the user says "explain this codebase", "I'm new to this repo", "map the architecture", "onboard me", "where does X happen", "how is this project structured", or joins a new team or project.
---

# Codebase map

Reading files top to bottom is the slow way in. Senior engineers ask four questions instead, in this order: **what does it do, how is it run, where does the important work happen, and what path does one real request take.** The first three come from cheap signals (manifests, CI, git history, imports). The fourth only comes from running the code. Everything ends up in one file, `MAP.md`, that a new person can read in ten minutes.

Work **read-only** on the repo. Put every output in a temp folder (`out=$(mktemp -d)`) unless the user asks for `MAP.md` in the repo. Never run migrations, deploys or anything that touches a shared database or real credentials.

Scripts are in `scripts/`, Python 3.9+ standard library and git only. `S=~/simcraft/skills/coding/codebase-map/scripts`.

## 0. Ask one thing

"Is there a specific thing you need to do here (fix a bug, own an area, review a change), or a general map?" A goal decides which path to trace. If there is no answer, map the whole repo and trace its most important user action.

## 1. Orient (15 minutes)

```
python3 $S/entrypoints.py <repo> > $out/entry.md
```
It lists docs to read first, build and run commands (package.json scripts, console scripts, Makefile, Procfile, Dockerfile CMD, compose services), CI pipelines and the commands they run, mains, servers, CLI commands, HTTP routes, background jobs, the data model, environment variables (with a flag when the `.env` template is missing one), and tests. Every hit is `file:line`.

Then read, in this order: README and contributor docs, **the CI file** (it is the only build recipe that is known to work), the main manifest, the entrypoint files. Write the **one-paragraph purpose** now, before reading more code: who uses it, what goes in, what comes out, what it talks to.

## 2. The data model is the backbone

Read the schema before the logic. Migrations (oldest shows the original core, newest shows where the product is going), ORM models, Prisma or SQL files, or, if there is no database, the main data shapes (pydantic models, TS types, JSON files on disk). Write down the 3 to 7 core entities and how they relate. Most business logic is "load these, change them, save them", so knowing the nouns makes the code readable.

## 3. Structure from imports

```
python3 $S/deps.py <repo> --json $out/deps.json --mermaid $out/deps.mmd --svg $out/deps.svg > $out/deps.md
```
Read: the **layers** (level 0 is the foundation, top is entry code), **folder cycles** (tangled modules, with the cheapest edge to cut), **load-bearing files** (most importers: change carefully), **possibly dead files** (no importers), and the main external packages. If one folder holds most of the code, run again with `--under <that folder>` to see inside it.

## 4. History: where the work and the risk are

```
python3 $S/hotspots.py <repo> --deps $out/deps.json > $out/hot.md
```
- **Hotspots** (changes x complexity): the few files where most bugs and most of your future work will be.
- **Change coupling**: files that change in the same commits. A pair with `import link = NO` is a hidden dependency, for example two copies of the same logic, or a client and server that share a format. These are the best gotchas.
- **Ownership** and **knowledge at risk**: who to ask about each area, and complex files whose main author has gone quiet.
- **Bug magnets**, **frozen code** and **new code**.

Add `--anonymize` if the map will be shared outside the team. Under about 30 commits, git signals are weak: say so and lean on steps 3 and 5.

## 5. Trace one real path by running it

This is the step that turns guesses into knowledge. Pick one real user action (the one the top hotspots serve, or the user's goal). Get it running using the CI steps. Then either:
- find the **sink** (the DB write, the HTTP response, the output file), put a stack dump or breakpoint there (`breakpoint()`, `traceback.print_stack()`, `console.trace()`, `debug.PrintStack()`), trigger the action once, and read the stack bottom-up; or
- for Python, run it under the tracer: `python3 $S/trace_py.py --repo <repo> --out $out/trace.txt -- <script or -m module> <args>`. It prints every repo function the run touched, by depth, as `file:line`.

If the path calls paid or external services, stub them at the edge (patch the HTTP call to return a canned response) instead of using real keys. Record each hop as `file:line  what happens here`, and mark anything surprising.

## 6. Load-bearing vs dead

Load-bearing = many importers, on the traced path, or a hotspot. Dead candidates = no importers and frozen for a year. Before calling anything dead, grep for its name as a string (plugin registries, `getattr`, dynamic imports, config files, framework conventions). Say "probably dead, because..." rather than "dead".

## 7. Write MAP.md

Use the template in [reference.md](reference.md#mapmd-template): purpose, how to run it, architecture diagram (Mermaid, drawn from what you learned, not just the raw import graph), the traced path, data model, hotspots, coupling pairs, who knows what, glossary, gotchas, first tasks. Mark each claim **ran** (you saw it happen) or **read** (from the code). Then check every reference:
```
python3 $S/check_map.py $out/MAP.md <repo>
```
Fix every broken one. Finish with a five-line summary in chat and the path to `MAP.md` (and the SVG if made).

## Rules

- Never claim a hop you did not see in code or in a run. A wrong map is worse than none.
- Explain jargon the first time it appears, and put every project-specific term in the glossary.
- First tasks must be small, real and safe: a test to add for a hotspot, a log line on the traced path, a dead file to confirm.
- Depth, per-language tracing recipes, heuristics and their limits: [reference.md](reference.md). A real example: [examples/MAP.md](examples/MAP.md).

© dotslashsimran · MIT · dotslashsimran/simcraft

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
acquire-codebase-knowledge официальный github Скилл acquire-codebase-knowledge для GitHub Copilot изучает существующий репозиторий и готовит документацию по его устройству. Запускается по просьбе описать архитектуру, составить карту проекта или помочь освоиться в кодовой базе. CX Codex +1 2 200установок gsd-map-codebase open-gsd Скилл gsd-map-codebase для Claude Code анализирует существующий проект и создаёт карту его устройства. Полное сканирование запускает параллельных агентов и сохраняет семь документов в .planning/codebase/. CX Codex +1 589установок agent-3-codebase-explorer happycapy-ai Субагент agent-3-codebase-explorer исследует репозиторий перед исправлением или новой функцией: находит нужные файлы, разбирает структуру и готовит карту кодовой базы. CX Codex ★ 138звёзд репо codebase-summarizer patricio0312rev Скилл codebase-summarizer сканирует репозиторий и собирает ARCHITECTURE.md: точки входа, связи модулей, диаграммы и подсказки, куда лезть за правкой. CX Codex +1 411установок codebase-explorer davila7 Субагент codebase-explorer исследует незнакомый проект: находит стек, архитектуру, точки входа и поток данных. По запросу сохраняет выводы в CLAUDE.md. CX Codex 256установок codebase-recon Jiachen Yu Плагин codebase-recon изучает историю Git, чтобы показать устройство проекта до чтения кода. Помогает найти часто меняющиеся и проблемные файлы, а также понять распределение знаний в команде. CX Codex ★ 1 596звёзд репо

Из того же набора24

Весь набор →
flaky-test-killer Скилл flaky-test-killer для Claude Code ищет причину нестабильных тестов и помогает устранить её в коде. Запускает проверки под нагрузкой и сравнивает частоту сбоев до и после исправления. CX Codex +1 ★ 541звёзд репо reverse-engineer-video Скилл reverse-engineer-video для Claude Code разбирает монтаж референсного ролика и готовит план для его пересъёмки. Запускается по просьбе найти склейки, движения камеры, ритм или сравнить ремейк с оригиналом. CX Codex +1 ★ 541звёзд репо system-design-from-scratch Скилл system-design-from-scratch для Claude Code и Codex помогает проектировать бэкенд и распределённые системы через написание рабочего кода, нагрузочные тесты и симуляцию сбоев. CX Codex +1 ★ 541звёзд репо paper-to-runnable Скилл paper-to-runnable для Claude Code превращает исследовательскую статью в минимальную рабочую реализацию её основной идеи. Запускается по просьбе реализовать или воспроизвести статью, в том числе по ссылке arXiv или локальному PDF. CX Codex +1 ★ 541звёзд репо api-design-review Скилл api-design-review для Claude Code проверяет дизайн HTTP API, SDK или CLI. Запускается по просьбе оценить спецификацию, эргономику SDK или риск изменения перед выпуском. CX Codex +1 ★ 541звёзд репо code-loop Скилл code-loop для Claude Code создаёт зацикленные видео из сцен three.js и шейдеров GLSL. Агент подключает его по запросу на генеративную анимацию или GIF без видимого стыка. CX Codex +1 ★ 541звёзд репо dx-audit Скилл dx-audit для Claude Code проверяет путь нового разработчика через документацию SDK, API, CLI или фреймворка. Агент проходит один сценарий в чистой среде и фиксирует трение, ошибки и время до первого успеха. CX Codex +1 ★ 541звёзд репо rough-cut Скилл rough-cut для Claude Code собирает черновой монтаж разговорного видео. Запускается по просьбе убрать паузы, слова-паразиты и неудачные дубли. CX Codex +1 ★ 541звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой