CodeGraph + OpenCode: быстрый старт

Это самое короткое и честное руководство по началу работы.

Если говорить совсем просто, картина такая:

GoCPG поддерживает граф кода в актуальном состоянии.
OpenViking хранит память проекта и контекст рабочих сеансов.
PostgreSQL хранит правила: кто открыл сеанс, кто может его читать, кто может принять его от другого человека и каким сохранённым знаниям ещё можно доверять.
OpenCode — это место, где вы задаёте вопросы, проверяете изменения, продолжаете работу и передаёте контекст другому человеку.

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

Что вы получаете¶

После настройки OpenCode сможет:

понимать живую структуру кода текущего проекта;
использовать память проекта через OpenViking, когда нужен более широкий контекст;
вести явный рабочий сеанс вместо постоянного старта с нуля;
продолжать тот же самый контекст после паузы, перезапуска или сжатия истории;
передавать один и тот же сеанс другому человеку для проверки, ревью или тестирования;
не подмешивать в ответы заведомо устаревшие знания как будто они всё ещё надёжны.
использовать все 149 MCP-инструментов CodeGraph, включая codegraph_hypothesis для построения гипотез по безопасности.

Простая картина системы¶

CodeGraph даёт OpenCode три вида понимания:

Живая структура кода - функции, вызывающие и вызываемые связи, влияние изменений, сложность, поток данных - главный источник правды: GoCPG
Память проекта - отобранные навыки, синхронизированный контекст репозитория, полезная память из рабочих сеансов - главный источник правды: OpenViking
Правила и владение - кто открыл сеанс - кто может читать - кто может изменять - кто принял передачу - каким сохранённым знаниям ещё можно доверять - главный источник правды: PostgreSQL

Что должно быть готово¶

Нужно, чтобы у вас были:

установленный CodeGraph;
построенный граф проекта в файле .duckdb, которым управляет GoCPG;
запущенный API CodeGraph;
установленный OpenCode;
подключённый модуль opencode-codegraph.

Рекомендуемый локальный набор служб:

GoCPG
API CodeGraph
OpenViking
PostgreSQL

Быстрая настройка¶

Создайте файл opencode.json в корне проекта:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codegraph": {
      "type": "local",
      "command": ["python", "-m", "src.mcp", "--transport", "stdio", "--db", "data/projects/codegraph.duckdb"],
      "environment": {
        "CODEGRAPH_PROJECT": ""
      }
    }
  },
  "lsp": {
    "codegraph": {
      "command": ["python", "-m", "codegraph_lsp", "--db", "data/projects/codegraph.duckdb"],
      "extensions": [".py", ".go", ".js", ".ts", ".java", ".c", ".cpp", ".cs", ".kt", ".php", ".rb"]
    }
  },
  "plugin": ["opencode-codegraph"],
  "instructions": [".codegraph/AGENTS.md", ".codegraph/SCENARIO_PLAYBOOK.md"]
}

После этого запустите OpenCode:

opencode

Или используйте готовый скрипт запуска из репозитория:

python scripts/run_opencode_codegraph.py --model openai/gpt-5.3-codex

Быстрая проверка¶

Выполните:

opencode mcp list
opencode agent list
opencode debug config

Хороший результат выглядит так:

MCP codegraph подключён;
агент codegraph виден;
модуль opencode-codegraph загружен;
раздел LSP указывает на правильный .duckdb файл.

Первые 10 минут¶

1. Понять проект¶

В OpenCode:

/onboard как устроен этот репозиторий?

Что произойдёт:

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

2. Понять одну функцию¶

/explain create_app

Что произойдёт:

сначала будет использован граф кода;
при необходимости будет подключена память проекта;
объяснение останется внутри того же исследовательского сеанса.

3. Проверить свои изменения¶

/review

Что произойдёт:

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

4. Понять, что делать дальше¶

/status

или

/next

Эти команды нужны, когда вы не хотите гадать: продолжать, обновлять, проверять или уже можно двигаться дальше.

Обычная личная работа¶

Обычный путь одного разработчика выглядит так:

Начните с /onboard или /explain.
Работайте внутри одного явного сеанса.
Используйте /review перед завершением заметных изменений.
Используйте /status или /next, если не уверены.
Используйте /continue после паузы, перезапуска или сжатия истории.
Используйте /update, когда нужно обновить граф кода или память проекта.

Главная идея здесь простая: OpenCode не должен вести себя так, будто после каждой паузы всё забыто. Система теперь старается сохранять одну линию контекста на протяжении реальной работы.

Совместная работа¶

Теперь система поддерживает общие рабочие сеансы внутри одного проекта.

Это означает, что один человек может начать исследование, а другой — продолжить его с тем же набором доказательств и подсказок.

Типичные примеры:

разработчик -> ревьюер
разработчик -> тестировщик
ревьюер -> разработчик

Что поддерживается:

явное открытие сеанса;
предоставление доступа только для чтения;
передача владения другому человеку;
повторное открытие того же сеанса позже;
явное закрытие или архивирование после завершения работы.

Почему это важно:

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

Как устроена память¶

Не всем сохранённым знаниям можно одинаково доверять.

Теперь CodeGraph разделяет знания из OpenViking по состояниям:

актуально — можно использовать по умолчанию;
требует проверки — может быть полезно, но уже есть риск устаревания;
устарело — не должно попадать в обычный поиск и обычные подсказки.

Почему это важно:

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

Поведение по умолчанию:

OpenCode предпочитает только актуально;
состояние требует проверки подключается только по явному запросу;
состояние устарело исключается из обычных подсказок.

Что `OpenCode` делает сам¶

Модуль уже берёт на себя много полезной работы:

добавляет контекст графа кода, когда в чате упоминаются файлы или намерение изменить код;
держит в разговоре краткое состояние проекта;
старается сохранить непрерывность явного сеанса в длинных диалогах;
добавляет подсказки к командам /onboard, /review, /continue, /status, /next, /update;
при подходящих условиях выполняет действия после коммита.

Это означает, что в большинстве случаев вам не нужно вручную вызывать низкоуровневые операции памяти.

Чем можно управлять явно¶

Если нужен полный контроль, модуль и API поддерживают явные действия:

открыть сеанс;
посмотреть список сеансов;
посмотреть сведения о сеансе;
дать доступ к сеансу;
принять или отклонить передачу;
отозвать доступ;
закрыть сеанс;
отправить сеанс в архив;
получить релевантный контекст;
прочитать конкретный ресурс;
просмотреть раздел дерева ресурсов;
зафиксировать реально использованный контекст;
запустить фоновое сохранение;
проверить состояние этого сохранения.

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

Когда система сужает возможности¶

На практике OpenCode может работать в трёх режимах:

Полный контекст - готов и граф кода, и память проекта
Ожидание синхронизации - память проекта настроена, но ещё не готова - OpenCode работает уже, но осторожнее и уже по охвату
Только граф кода - OpenViking временно недоступен или работает с ограничениями - понимание по графу кода всё равно сохраняется

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

Что делать при проблемах¶

Я не вижу инструменты `CodeGraph`¶

Проверьте:

opencode mcp list
python -m src.mcp --transport stdio --db data/projects/codegraph.duckdb

`/onboard` или `/continue` дают слишком мало контекста¶

Проверьте:

/status

Если память проекта ещё синхронизируется, OpenCode специально будет работать уже и осторожнее.

Помощник как будто не использует сохранённую память¶

Возможные причины:

память ещё не готова;
нужный фрагмент помечен как требует проверки;
нужный фрагмент помечен как устарело;
система временно работает в режиме только по графу кода.

Другой человек не может продолжить мой контекст¶

Проверьте, был ли сеанс:

открыт для чтения;
передан явно;
закрыт или отправлен в архив раньше времени.

Полезные привычки с первого дня¶

Если хотите быстро получить пользу, придерживайтесь таких привычек:

используйте /onboard, когда заходите в незнакомый код;
используйте /explain перед изменением рискованных функций;
используйте /review перед тем, как считать задачу завершённой;
используйте /status, когда чувствуете неуверенность;
используйте /continue, а не ручную пересборку контекста;
передавайте сеанс явно, если работу продолжает другой человек.

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

Что вы получаете¶

Простая картина системы¶

Что должно быть готово¶

Быстрая настройка¶

Быстрая проверка¶

Первые 10 минут¶

1. Понять проект¶

2. Понять одну функцию¶

3. Проверить свои изменения¶

4. Понять, что делать дальше¶

Обычная личная работа¶

Совместная работа¶

Как устроена память¶

Что OpenCode делает сам¶

Чем можно управлять явно¶

Когда система сужает возможности¶

Что делать при проблемах¶

Я не вижу инструменты CodeGraph¶

/onboard или /continue дают слишком мало контекста¶

Помощник как будто не использует сохранённую память¶

Другой человек не может продолжить мой контекст¶

Полезные привычки с первого дня¶

Что `OpenCode` делает сам¶

Я не вижу инструменты `CodeGraph`¶

`/onboard` или `/continue` дают слишком мало контекста¶