Как я собираю Marginalia: мой сетап для ИИ-разработки

Я не разработчик и не пишу код для Marginalia. В этом проекте я занимаюсь другой частью работы: придумываю игру, принимаю решения по дизайну и архитектуре, формулирую задачи, пишу спеки и проверяю результат.

Код пишут ИИ-агенты.

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

Это не инструкция и не универсальный рецепт. Я не считаю себя достаточно опытным, чтобы учить кого-то агентной разработке. Скорее, это дневник о том, как сейчас устроен мой сетап и что в нём оказалось сложнее, чем выглядело на старте.

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

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

Тогда я начал разделять работу между агентами.

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

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

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

Особенно хорошо это заметно на балансе. Раньше я бы последовательно менял связанные файлы, каждый раз дожидаясь результата. Теперь несколько небольших изменений можно отправить в работу одновременно. В некоторых случаях это ускоряет процесс в разы.

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

Но это не значит, что агенты сами решают, какой должна быть Marginalia.

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

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

Моя роль постепенно сместилась. Я меньше слежу за отдельными действиями и больше отвечаю за то, чтобы система в целом не развалилась: чтобы задача была правильно описана, изменения не конфликтовали, а результат соответствовал замыслу.

Часть контроля удалось автоматизировать. Скрипты следят за состояниями рабочих деревьев и сообщают о проблемах. Watchdog отслеживает лишние процессы. Тесты проверяют ожидаемое поведение. Но автоматизация не освобождает от проверки. Она просто не даёт держать каждую мелочь в голове.

Недавно таким способом я перерабатывал интерфейс Marginalia.

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

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

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

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

Воркер выполняет свою часть и присылает сигнал о завершении. Но этот сигнал означает только одно: агент считает, что закончил. Это ещё не значит, что работа действительно принята.

Дальше продюсер проверяет дифф, смотрит, какие файлы изменились, запускает тесты и решает, можно ли сливать ветку. Если всё в порядке, изменения попадают в основную ветку, а затем я проверяю результат в игре.

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

В основе сетапа находится OpenCode. Я использую его как среду, через которую запускаются и настраиваются агенты.

Orca ADE работает поверх этого процесса как координатор нескольких рабочих деревьев. Он помогает запускать агентов, отслеживать их состояния, организовывать обмен сообщениями и не терять связь между задачей и конкретной веткой разработки.

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

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

В Marginalia модели распределяются по сложности работы. Большие задачи с длинным контекстом и сложной логикой отправляются сильным моделям. Небольшие исправления, где не нужно удерживать в памяти весь проект, могут выполнять бесплатные coding-модели.

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

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

В сетапе есть Mem0 MCP Server. Я использую его как память Marginalia. Туда попадают решения по проекту, найденные ошибки и правила работы.

Мне не нужно, чтобы агент помнил весь старый чат. Гораздо полезнее сохранить короткое знание: этот подход уже пробовали и отвергли, этот файл нельзя менять в рамках такой задачи, эта ошибка однажды появилась из-за пропущенного этапа.

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

Система ещё не выглядит законченной. Но для долгого проекта это важный слой. Код объясняет, что сделано. Память может объяснить, почему это сделано именно так.

Рой агентов не убрал проблемы. Он просто сделал их заметнее.

В начале спека напрямую вставлялась в TUI. Иногда она доходила до воркера не полностью. Передача через временный Markdown-файл эту проблему сняла. Были лишние процессы, для которых теперь работает watchdog. Кодировка тоже ломалась, и окончательного решения здесь у меня пока нет.

Самый неприятный тип ошибок возникает, когда агент понимает задачу формально, но не улавливает её смысл.

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

Пришлось переписывать спеку подробнее. Мне казалось, что информации в ней достаточно. Оказалось, что «достаточно для человека» и «достаточно для модели» - не одно и то же.

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

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

После перехода к такому процессу проект заметно вырос. Появились новые анимации, события и метрики, пролог, drag-and-drop карточек и другие элементы, которые в последовательном режиме заняли бы гораздо больше времени.

Но главный результат не в количестве фич.

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

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

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

Рой агентов не заменил автора Marginalia. Он заменил часть ручной сборки кода и позволил мне вести несколько направлений одновременно.

Пока это не отлаженная производственная система. Это живой сетап, который постоянно приходится чинить и перестраивать. Но сейчас он позволяет Marginalia расти с темпом, который без параллельной работы был бы для меня недоступен.

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

Marginalia продолжает расти. Вместе с ней растёт и система, на которой я её собираю.

P.S. В телеге можно найти промежуточные результаты разработки и актуальные отчеты