CodeDebrief — детерминированные workflow-карты кода для агентов

CodeDebrief превращает локальную кодовую базу в детерминированные workflow-флоучарты, которые кодинг-агенты могут смотреть, рендерить, расширять, переводить и объяснять. Он статически строит карту точек входа, решений, ветвей, внутренних вызовов, возвратов, исключений и исходов до того, как агент начнёт отвечать, поэтому визуальное объяснение опирается на переиспользуемые артефакты, а не на свежую реконструкцию «на лету».

Анализатор, артефакты, вьюер и MCP-сервер работают локально и не требуют ключа LLM-провайдера. Важно, чем CodeDebrief не является: это не генератор документации, не поиск багов, не универсальная графовая БД и не сервис обогащения через LLM. Это слой навигации по workflow для понимания того, как код-пути на самом деле связаны.

Статус: pre-1.0 alpha. Модель версионируется, но схема и MCP-payload могут меняться до 1.0. Актуальный релиз — v0.17.0.

Зачем это существует

Агент может реконструировать workflow из сырого исходника, но эта реконструкция обычно зависит от того, какие поиски он выполнит, какие файлы выберет и в какой контекст успеет прочитать. Повторять этот процесс медленно, а менее очевидные ветки или межфайловые пути могут выпасть.

CodeDebrief создаёт переиспользуемый слой навигации до того, как агент что-то объяснит:

• entrypoints, решения, ветви, вызовы, исходы и source-диапазоны;
• доменные понятия — статусы, роли, разрешения, enum и feature flags;
• контекст затронутых workflow для файлов, символов, потоков и путей зависимостей;
• канонические визуальные срезы со стабильными хешами диаграмм;
• опциональные языковые лейблы как presentation layer поверх фактов анализатора.

Быстрый старт

Требуется Python 3.10+. Установка через uv:

uv tool install codedebrief
codedebrief setup claude

Вместо claude подставьте codex, gemini или cursor. Чтобы анализировать только выбранные папки, их передают через --source:

codedebrief setup claude --source backend/ frontend/

Для воркспейса из нескольких репозиториев заведите отдельную папку под конфиг и артефакты и укажите --source на репозитории:

mkdir pipeline-map
cd pipeline-map
codedebrief setup claude --source ../ingest-service ../transform-service ../warehouse-ui

Объём имеет значение: анализировать весь репозиторий или много больших папок заметно увеличивает время setup, update и ответов MCP (больше файлов для хеширования, парсинга, линковки и поиска). Лучше выбирать минимальные корни, в которых всё ещё содержатся нужные агентам workflow.

Ответы MCP ограничены token_budget. Если агент передал явный бюджет, CodeDebrief его соблюдает. Для широких запросов agent_context, идущих с дефолтным бюджетом, CodeDebrief автоматически повышает эффективный бюджет на больших проектах, чтобы первый срез поместился без принудительного повтора.

После setup можно задавать обычные вопросы:

Show me the checkout workflow.
Which branches handle a failed payment?
What workflows are affected by this file?
Where is this status handled?
Expand this workflow one level deeper.

Ручная навигация:

codedebrief view

По умолчанию конфиг и артефакты лежат в codedebrief-out/:

codedebrief-out/
├── codedebrief.toml       опциональный конфиг проекта, создаётся setup
├── codedebrief.html        локальный интерактивный вьюер всего проекта
├── codedebrief.md          обозримые Mermaid-флоучарты
├── codedebrief.json        каноническая модель для MCP, CI, скриптов и вьюера
├── codedebrief.hash.json   sidecar-хеш модели для быстрых MCP cold start
└── codedebrief.errors.jsonl сохранённая диагностика CLI/MCP при ошибках

Файлы, нужные провайдеру, лежат там, где клиент их ожидает: .mcp.json, AGENTS.md, CLAUDE.md, GEMINI.md, .cursor/rules/codedebrief.mdc и каталоги агентских скиллов.

Для явного обновления во время разработки:

codedebrief update
codedebrief validate --check-sync

Удаление из проекта:

codedebrief clear

Где это вписывается

CodeDebrief не заменяет поддерживаемую документацию проекта. Документация должна фиксировать архитектуру, намерения, инварианты, конвенции, эксплуатационные знания и «почему» важных решений.

CodeDebrief закрывает более быструю и узкую задачу: инспектируя workflow, зашитый в текущий исходник, во время брейншторма, отладки, планирования изменений или ревью влияния. Он полезен, чтобы:

• визуализировать один сфокусированный фрагмент workflow по запросу;
• проследить решения и внутренние вызовы между файлами;
• посмотреть workflow, затронутые файлом, символом или планируемым изменением;
• дать агенту общий структурный срез для немедленного анализа.

Документация объясняет систему во времени. CodeDebrief даёт визуальный срез текущего исходника, когда нужно о нём рассуждать. Любое объяснение агента или языковые лейблы — это presentation layer поверх сгенерированного анализатором флоучарта, а не его источник.

MCP-поверхность

Основные MCP-инструменты:

CLI остаётся компактным: setup, update, view, validate, doctor, clear и mcp.

Поддерживаемые языки

Анализатор извлекает control flow для 11 языковых идентификаторов:

Сгенерированные модели содержат metadata.language_capabilities с feature flags и заметками о ограничениях для каждого языка. Агенты должны опираться на этот контракт при объяснении глубины анализа.

Доменная логика

CodeDebrief извлекает и агрегирует доменные понятия:

• члены enum;
• статусы и состояния жизненного цикла;
• роли и разрешения;
• feature flags;
• обработанные значения и решения, ветвящиеся по ним.

agent_context включает релевантную доменную логику внутрь workflow_slice со ссылками на потоки, узлы, source-диапазоны, снапшоты и таргеты вьюера. Сопоставление значений использует смоделированные факты кода, включая суффикс-матчи вроде PAID для Status.PAID.

Конфигурация

CodeDebrief работает без конфига. Новые прогоны setup создают codedebrief-out/codedebrief.toml только когда дефолтов недостаточно.

[codedebrief]
source_roots = ["."]
exclude = []
exclude_dirs = []
include_public_functions = true
max_call_depth = 4
output_dir = "codedebrief-out"
self_exclude = true

[codedebrief.entrypoints]
include = []
exclude = []

[codedebrief.scopes]
backend = ["backend/**", "services/**"]
frontend = ["frontend/**", "web/**"]
edge = ["edge/**", "workers/**"]

Дефолты вычищают типовые каталоги VCS, зависимостей, кешей и сборки: .git, node_modules, virtualenv, .next, .turbo, .svelte-kit, .nx, .pytest_cache, .mypy_cache, .ruff_cache, .pyre, .dart_tool, dist, build, out, target, obj, coverage, vendor, Pods и codedebrief-out.

Ограничения

CodeDebrief не исполняет код, не наблюдает за runtime, не выполняет полное символьное выполнение, не доказывает бизнес-корректность и не восстановливает глубокое состояние фреймворка. Это статическая модель исходников, управляющих потоков, выбранных конвенций фреймворка и разрешимых внутренних вызовов.

Важные практические ограничения:

• динамический dispatch может остаться неразрешённым;
• глубина возможностей зависит от фронтенда анализатора;
• сгенерированные или неподдерживаемые файлы могут пропускаться;
• большие срезы ограничены token-бюджетом и сообщают о пропусках;
• первый отображаемый срез — сжатая сводка и может быть расширен MCP-инструментами.

Частые вопросы

Зачем это вместо репозиторий-суммаризации? Суммаризация — проза под один запрос и один контекст. CodeDebrief держит переиспользуемую структурную модель: ограниченные флоучарты, source-якоря, пропуски и хендлы расширения для последующих вопросов.

Это инструмент ревью кода? Нет. CodeDebrief — для понимания кода и навигации по workflow. Он не выдаёт возможные дефекты как продуктовый вывод.

Нужен ли ключ LLM? Нет. Анализатор, артефакты, Mermaid-диаграммы, вьюер и MCP-сервер локальные и детерминированные.

Чем отличается от call graph? Call graph показывает отношения символов. CodeDebrief моделирует workflow-срезы с entrypoint-ми, решениями, ветками, упорядоченными шагами, source-диапазонами, доменными понятиями, визуальными таргетами и инструментами расширения для агентов.

Можно использовать только как ручной вьюер? Да, через codedebrief view. MCP — основная поверхность для агентов, но вьюер остаётся официальной поверхностью для ручного исследования.

Лицензия

Apache License 2.0.