Разработчик перенёс контекст ИИ-агента из чатов в репозиторий: утилита doubled-graph

Когда вы меняете Claude Code на Codex или другой инструмент, первая мысль: как перенести историю чатов. Автор разбора на Хабре считает, что это неверный вопрос. Полгода он держит контекст проекта не в переписке, а в репозитории, и говорит, что смена агента перестала быть болезненной.

Почему история чатов — плохая память

Переписка хранит разговор о проекте, а не итоговые решения. В ней есть шум, повторы, отменённые идеи и вежливые «ок». Новый агент обязан всё это прочитать и заново интерпретировать, а проверить интерпретацию нечем: в чате нет ни контрактов, ни границ модулей, ни критериев приёмки, которые можно сверить с кодом.

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

Автор предлагает простой тест переносимости. Откройте репозиторий в агенте, который проект никогда не видел, и дайте один промпт: «прочитай, что здесь есть, и расскажи, как устроен проект и что в нём сейчас происходит». Если ответ точный, контекст действительно живёт в репозитории.

Что лежит в репозитории

Основа — методология GRACE от osovv (лицензия MIT): замысел, границы модулей и проверки хранятся рядом с кодом. Автор добавил три вещи: сценарий миграции существующего кода, граф вызовов через CodeGraphContext и MCP-обёртку. Вместе это утилита doubled-graph.

Код размечается парными комментариями-якорями. У модуля есть MODULE_CONTRACT с целью, областью и зависимостями, у функции — CONTRACT с входами, выходами и побочными эффектами, а логика режется на блоки. Поле LINKS связывает файл с модулем, так что обычный grep по идентификатору вроде M-AUTH-VALIDATE выдаёт агенту пару нужных абзацев вместо сорока файлов. Линтер проверяет парность якорей, их уникальность и соответствие реальным экспортам.

Графов два. Declared описывает замысел и лежит в .grace/graph/. Computed строится из AST и показывает факт: кто кого вызывает. Инструмент detect_changes сверяет их и находит расхождения: код без модуля, модуль без кода, устаревшие зависимости, модуль без проверки, файл без разметки. Post-commit хук обновляет computed-граф, а detect_changes можно повесить на pre-commit или CI. Перед правкой агент также спрашивает, кого зазаденет изменение.

Миграция старых проектов

Методики «сначала спецификация, потом код» обычно умирают на десятилетнем проекте, где спецификации нет, а код работает. Поэтому режимов два. В migration истина в коде: агент восстанавливает замысел, размечает файлы и проходит гейты одобрения человеком. В post_migration истина в артефактах, и любое расхождение подозрительно. Тогда есть три выхода: обновить артефакт через бандл изменений, откатить код под контракт или записать в DRIFT.md и заблокировать модуль.

Отдельная идея — belief-state. В критичных точках агент пишет в лог, какое неочевидное допущение он принял, с якорем и session_id. Когда спустя месяцы придёт лог из прода, можно поднять состояние ИИ в этом месте.

Ограничения и вывод

Автор честно предупреждает: чисел не будет, контролируемого эксперимента он не ставил, всё держится на ощущениях. К тому же методика требовательна: он утверждает, что применять все десять принципов нужно целиком, а частичное внедрение не стоит усилий. Разметка якорями добавляет шум в код, а гейты одобрения замедляют быстрые правки. Для небольших проектов это может оказаться избыточным.

Но идея стоит внимания и без полной методики. Если вы работаете с несколькими агентами, вынесите в репозиторий хотя бы контракты модулей, граф зависимостей и список проверок, и пусть CI ловит расхождения с кодом. Проверить результат легко: дайте свежему агенту тот самый один промпт. Для пробы: pipx install doubled-graph, затем doubled-graph setup и стартовый промпт из папки prompts.