Используйте этот сценарий, когда нужно изменить структуру кода и сохранить поведение продукта. CodeGraph показывает область влияния, помогает сравнить данные до и после правки и оформить решение по результатам проверки.
Результат
В конце у вас должны быть:
- выбранный символ и зафиксированная базовая ревизия;
- отчёт о влиянии и read-only-аудит до изменения;
- небольшая правка, выполненная в обычном редакторе;
- результаты тестов и линтера проекта;
- обновлённый CPG и данные проверки после изменения;
- явное решение: оставить правку, доработать её или откатить.
Нулевой код завершения подтверждает, что команда выполнилась. Неизменность поведения подтверждают тесты, линтер и результаты ревью.
Предварительные условия
- Репозиторий уже импортирован в CodeGraph.
- В рабочем дереве находятся только те изменения, которые вы собираетесь проверять.
- Известны команды тестов и линтера проекта.
- Известен путь к DuckDB, который показывает информация о проекте.
В примерах используются переменные PowerShell: так безопаснее работать с путями, содержащими пробелы.
$ProjectName = "my-project"
$RepoPath = "D:\src\my-project"
$CpgDb = "D:\codegraph-data\my-project.duckdb"
$BaseRef = "origin/main"
$Symbol = "qualified_symbol_name"
python -m src.cli projects info $ProjectName
Убедитесь, что показанные пути к исходникам и DuckDB относятся именно к изменяемому репозиторию. При несовпадении остановитесь.
1. Зафиксируйте исходное состояние
Сохраните Git-ревизию и состав текущих изменений штатными средствами контроля версий. Затем выполните детерминированный read-only-аудит:
python -m src.cli audit --db $CpgDb --source-path $RepoPath --profile ci_fast --format json --skip-llm-conclusion --skip-persistence
Флаг –skip-persistence запрещает диагностическому запуску обновлять проекции аудита. Если рефакторинг проходит управляемый процесс, сохраните вывод в системе доказательств задачи. Без параметра вывода команда не создаёт файл отчёта.
2. Ограничьте область влияния
До правки проанализируйте выбранный символ:
python -m src.cli impact $Symbol --db $CpgDb --max-depth 5 --format json
Проверьте direct_callers, transitive_callers, affected_methods и impact_score. Пустой результат означает «символ не найден», а не «изменение безопасно». Сначала проверьте имя символа, базу проекта, импорт языка и актуальность CPG.
Разделите работу, если область затрагивает чужую зону ответственности, публичный API, схему хранения, авторизацию или критическую точку входа за пределами одобренной задачи.
3. Выполните одну локальную правку
Измените код в обычном редакторе. Не смешивайте поведенчески нейтральный рефакторинг с новой функцией. Переименование, обновление зависимости, изменение API и алгоритма не должны попадать в один срез.
Сразу запустите профильные тесты и линтер проекта. Если проверка не прошла, верните заведомо рабочую версию штатными средствами контроля версий либо исправьте минимальный проблемный срез.
4. Обновите граф
Отчёт о влиянии использует импортированный CPG. После изменения исходников обновите его:
python -m src.cli cpg --path $RepoPath --output $CpgDb
Указывайте только базу, показанную для этого проекта. Если в вашей установке импорт выполняется другим одобренным процессом, используйте его, а перед повторным анализом ещё раз проверьте информацию о проекте.
5. Проверьте изменённый срез
Запустите единую проверку относительно зафиксированной базы:
python -m src.cli review --db $CpgDb --base-ref $BaseRef --format markdown
Затем повторите анализ влияния:
python -m src.cli impact $Symbol --db $CpgDb --max-depth 5 --format json
Второй отчёт должен объяснять ожидаемое структурное изменение и не добавлять неожиданных вызывающих символов, проблем безопасности или посторонних файлов. Если правка влияет на проектные метрики качества, повторите read-only-аудит.
Таблица решений
| Доказательства | Решение |
|---|---|
| Профильные тесты и линтер прошли, влияние осталось в одобренной области, критичные замечания проверки устранены | Оставить срез и приложить доказательства |
| Символ не найден или CPG устарел | Обновить контекст проекта и повторить анализ |
| Появились новые вызывающие символы, публичные поверхности или чувствительные пути | Остановиться и запросить расширенную проверку |
| Изменилось поведение или потребовалась правка критериев приёмки | Переклассифицировать работу в продуктовое изменение |
| Не прошли тесты, линтер или проверка | Исправить минимальный срез либо откатить его через систему контроля версий |
Что сохранить как доказательства
Зафиксируйте имя проекта, ревизию исходников, base ref, идентичность CPG, точные команды и коды завершения, значимые поля отчётов, результаты тестов и итоговое решение человека. В управляемой поставке вывод команд входит в пакет приёмочных доказательств вместе с требованиями, QA, ревью, AppSec и финансовым закрытием.
Диагностика
- «impact analysis requires explicit –db»: передайте путь DuckDB из projects info.
- Для известного символа нет вызывающих: проверьте квалифицированное имя и обновите CPG.
- В review попали посторонние файлы: проверьте base ref и область рабочей задачи.
- Аудит изменяет операционное состояние: повторите запуск с –skip-persistence.
- Результаты между запусками различаются: до сравнения сверьте ревизию, путь к базе, актуальность импорта и конфигурацию.
Актуальные исходные контракты
- src/cli/analysis_commands/audit_commands.py
- src/cli/analysis_commands/review_command.py
- src/cli/analysis_commands/impact_commands.py
- src/cli/domain_suite/gocpg_commands.py
См. также импорт проекта, проверку кода и сценарий 09: проверка кода.