Создание интерактивной карты кода с помощью Codex

Создание интерактивной карты кода с помощью Codex

Попросите Codex создать интерактивную карту вашего репозитория, а затем отмечайте, какие модули изменились с момента её генерации.

Нажав на любой модуль, можно увидеть его вызывающие компоненты, зависимости, основные потоки выполнения, связанные тесты и подтверждающие данные из исходного кода.

Codex создаёт:

• docs/codemap/codemap.html
• docs/codemap/codemap.json
• docs/codemap/codemap.lock

Полный промпт

Анализируйте текущую кодовую базу. Не изменяйте код продукта. Создавайте или обновляйте файлы только в docs/codemap/.

Игнорируйте каталоги vendor, build, dist, cache и другие сгенерированные каталоги.

Если docs/codemap/ уже существует, сначала сравните существующий codemap.lock с текущим репозиторием и перечислите модули, которые изменились. Затем сгенерируйте эти три файла вместе:

1. docs/codemap/codemap.html
   Создайте полностью самодостаточную интерактивную карту кода, которая открывается непосредственно в браузере. Включите:

   • основные модули, сервисы, базы данных, очереди и внешние зависимости
   • не более 20 основных узлов; группируйте низкоуровневые файлы под их родительским модулем
   • вызовы и потоки данных между модулями
   • 3-5 самых важных сквозных потоков
   • чёткую тёмную тему по умолчанию
   • границы системы и самые важные потоки данных, видимые на первом экране
   • цветовое кодирование типов модулей с простой легендой
   • автоматическую компоновку, которая минимизирует пересечения рёбер
   • нажатие на любой модуль подчеркивает его вызывающие компоненты, зависимости, связанные тесты и потоки, к которым он принадлежит
   • выбор потока подчеркивает его полный путь
   • поиск, фильтрацию, масштабирование и управление перетаскиванием

   Вверху покажите название репозитория, время генерации и коммит, из которого он был сгенерирован.

2. docs/codemap/codemap.json
   Используйте эту структуру:

   JSON

   Скопіювати

   {
     "generated_at": "",
     "generated_from_commit": "",
     "scope": [],
     "nodes": [],
     "edges": [],
     "flows": []
   }
   

   Каждый узел должен включать:

   • id
   • path
   • role
   • entrypoints
   • tests
   • constraints
   • evidence

   Каждый край должен включать:

   • from
   • to
   • type
   • evidence

   type может быть только:

   • imports
   • calls
   • reads
   • writes
   • publishes
   • subscribes

   Каждый поток должен включать:

   • trigger
   • steps
   • outcome

   Каждый шаг должен ссылаться на существующий id узла. Приложите соответствующий путь источника и символ к каждому узлу и краю. Отметьте любые отношения без источника доказательства как неизвестные. Не догадывайтесь.

3. docs/codemap/codemap.lock
   Используйте парсируемый JSON для записи:

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

   Если не найдено существующего codemap.lock, считайте каждый модуль новым и создайте полную карту.

   Когда закончите, проверьте:

   • codemap.json успешно парсится
   • каждый путь узла существует и каждый символ доказательства можно найти в источнике
   • каждый край и шаг потока ссылается на существующий узел
   • codemap.html и codemap.json используют одни и те же узлы, рёбра и потоки
   • codemap.lock соответствует текущему коммиту, состоянию рабочего дерева и отпечаткам модулей
   • каждое отношение без источника доказательства отмечено как неизвестное

   Эти три файла всегда должны генерироваться вместе из текущего репозитория. Никогда не редактируйте только один из них вручную.

Наконец, покажите:

• созданные или измененные файлы
• устаревшие модули
• оставшиеся неизвестные
• результаты валидации
• полный дифф

Дополнительное правило

Добавьте правило в AGENTS.md, чтобы карта кода всегда оставалась синхронизированной с репозиторием:

В начале каждой задачи, изменяющей код, сравните текущий репозиторий с docs/codemap/codemap.lock.

Перед изменением модуля используйте docs/codemap/codemap.json, чтобы ответить на три вопроса:

1. Что его вызывает?
2. На что это влияет?
3. Какие тесты его покрывают?

Если карта устарела или не может ответить на эти вопросы, сгенерируйте codemap.html, codemap.json и codemap.lock перед изменением кода.

Когда изменяются границы модулей, зависимости, маршруты, базы данных, очереди или основные потоки данных, обновляйте карту кода в том же коммите, что и код.