diff --git a/articles/2026-07-27-symphony.md b/articles/2026-07-27-symphony.md new file mode 100644 index 0000000..780020f --- /dev/null +++ b/articles/2026-07-27-symphony.md @@ -0,0 +1,110 @@ +# Symphony: как превратить GitHub Issues в управляемый поток работы с Codex + +Когда задач для AI-агента становится больше одной, основной проблемой становится не «как написать хороший промпт», а «как организовать работу». Какие задачи агент может брать сам? Где он работает? Что происходит, если задача требует решения человека? Как не запустить два агента на один и тот же issue? + +Для этого и появился Symphony — открытая спецификация OpenAI и её референсная реализация для оркестрации агентов разработки. Symphony читает задачи из трекера, создаёт для каждой из них изолированное рабочее окружение и запускает в нём агента, например Codex. Команда при этом управляет очередью задач и проверяет результаты, а не вручную сопровождает каждую агентную сессию. [Анонс OpenAI](https://openai.com/index/open-source-codex-orchestration-symphony/), [репозиторий Symphony](https://github.com/openai/symphony). + +## Откуда взялся Symphony + +OpenAI опубликовала Symphony 27 апреля 2026 года, но сама идея появилась раньше. Первая внутренняя версия была очень простой: сессия Codex в `tmux`, которая опрашивала Linear и запускала подагентов для новых задач. Но по мере роста числа агентных задач стало понятно, что нужен не просто скрипт запуска, а воспроизводимый операционный контур: очередь работ, изоляция, лимиты параллелизма, понятные статусы и человеческие точки контроля. + +В моём окружении для интерактивной работы с несколькими агентами используется `zellij`, а не `tmux`. Но терминальный мультиплексор решает только вопрос организации сессий. Symphony поднимается на уровень выше и организует работу вокруг задач и ожидаемых результатов. + +В результате OpenAI сначала описала Symphony как независимую от языка спецификацию, а затем создала референсную реализацию на Elixir. Саму Elixir-реализацию Codex написал по этой спецификации, после чего команда продолжила развивать и уточнять обе части. + +Важно, что Symphony — не «ещё один AI-агент» и не замена Codex. Это диспетчер вокруг агента. Он отвечает на вопросы «какую задачу взять», «где её выполнять» и «когда завершить запуск», а Codex отвечает за саму инженерную работу. + +Упрощённо поток выглядит так: + +```text +Issue в трекере + → Symphony выбирает подходящую задачу + → создаёт для неё изолированное рабочее пространство + → запускает Codex с контекстом задачи и правилами репозитория + → Codex выполняет описанный в WORKFLOW.md процесс + → задача приходит к результату или передаётся человеку +``` + +Конкретный результат определяет не Symphony, а правила проекта в `WORKFLOW.md`. Одна задача может закончиться pull request’ом, другая — исследованием или планом, а третья — вопросом, который должен решить человек. + +## Что даёт Symphony + +Главное преимущество — переход от разовых агентных запусков к управляемому процессу разработки. + +- Задачи становятся очередью: команда явно отмечает, какие issue готовы к автономной обработке. +- Каждая задача получает отдельное рабочее окружение, поэтому параллельные агенты не смешивают свои изменения в одной рабочей копии. +- Правила репозитория, документация и порядок работы становятся частью исполняемого процесса, а не рекомендацией «где-то в README». +- Можно ограничить число одновременных агентов и число их последовательных ходов. +- Результатом становится определённый проектом артефакт: изменение кода, pull request, исследование, план или передача задачи человеку. +- Человек остаётся владельцем решений: он принимает PR, меняет приоритеты и разбирает случаи, где агенту не хватает полномочий или контекста. + +Symphony не отменяет необходимость в хорошей инженерной среде. Напротив: чем лучше определены правила, тесты, границы ответственности и структура задач, тем полезнее становится оркестрация. + +## Как Symphony используется в Memory Bank + +В Memory Bank Symphony настроен через [`WORKFLOW.md`](../WORKFLOW.md) и запускает Codex для выбранных GitHub Issues. Поддержка GitHub Issues приходит из upstream-адаптера Symphony. + +При этом я использую собственный форк [`dapi/symphony`](https://github.com/dapi/symphony). Memory Bank — часть моего набора инструментов для автономной агентной разработки, и форк на моём GitHub-аккаунте даёт мне контроль над совместимыми версиями, изменениями и способом распространения всего комплекта. + +У задачи есть два ключевых состояния: + +```text +open + codex-ready + → Symphony берёт задачу в работу + → Codex работает в отдельном git worktree + → создаёт ветку и pull request + → human-review + → разработчик проверяет результат, мержит или запрашивает доработку +``` + +Метка `codex-ready` — явное разрешение агенту начать работу. Symphony не обрабатывает все открытые issue подряд. После успешного открытия pull request агент заменяет её на `human-review`, сохраняя остальные метки. Это предотвращает повторный запуск второго агента над той же задачей, пока изменение находится на ревью. + +Для каждой задачи создаётся отдельный worktree в `.symphony-workspace/`. Рабочая ветка имеет формат `codex/<номер-issue>`. Такой подход позволяет нескольким агентам работать параллельно, не смешивая незакоммиченные изменения. + +Symphony не превращает каждую задачу в безусловную команду «написать код». Memory Bank описывает разные процессы для дефекта, небольшого изменения, исследования или новой возможности. Получив issue, Codex сначала определяет подходящий процесс и проверяет, достаточно ли информации и полномочий для самостоятельной работы. Если требуется решение владельца проекта, агент останавливается и формулирует вопрос вместо того, чтобы угадывать. + +В текущей конфигурации допустимы до трёх параллельных агентов, каждый может сделать до восьми последовательных ходов. После создания PR агент: + +1. Оставляет в issue ссылку на PR и результаты проверки. +2. Меняет `codex-ready` на `human-review`. +3. Не закрывает issue, не мержит PR и не снимает `human-review`. + +Именно здесь проходит человеческая граница процесса: разработчик проверяет результат и решает, мержить ли изменение или вернуть задачу на доработку. + +## Как установить и запустить + +Для работы нужны: + +- Codex, уже авторизованный на машине; +- GitHub CLI `gh`, также авторизованный; +- Git и SSH-доступ на push в репозиторий; +- `direnv`; +- `mise` — он установит требуемые версии Elixir и Erlang; +- GitHub-токен для Symphony в переменной `SYMPHONY_GITHUB_TOKEN`. + +Токен не следует хранить в репозитории. Его достаточно предоставить процессу Symphony через переменную окружения `SYMPHONY_GITHUB_TOKEN`; конкретный способ зависит от принятого в проекте управления секретами. + +После этого достаточно выполнить: + +```sh +direnv allow +./bootstrap-symphony.sh +./run-symphony.sh +``` + +`bootstrap-symphony.sh` по умолчанию клонирует форк `dapi/symphony` в соседний каталог `../symphony`, подготавливает `.symphony-workspace/`, затем через `mise` устанавливает зависимости и собирает Elixir runner. + +Если Symphony уже находится в другом месте или нужен другой репозиторий, можно задать: + +```sh +export SYMPHONY_HOME=/path/to/symphony +export SYMPHONY_REPOSITORY=https://github.com/owner/symphony.git +``` + +После запуска Symphony начинает искать открытые GitHub Issues с меткой `codex-ready`. + +## Что важно не забыть + +Symphony запускает агента в доверенной среде, поэтому его не стоит сразу подключать к каждому issue и выдавать широкие учётные данные. В текущей схеме Codex может выполнять Git-операции, необходимые для создания ветки, коммита, push и PR; защита строится не на интерактивном подтверждении каждой команды, а на изоляции workspace, ограниченной очереди, правилах репозитория и обязательном human review. + +Хорошая первая практика — выбрать несколько небольших, хорошо описанных задач, пометить их `codex-ready` и посмотреть на качество PR, полноту проверок и корректность маршрутизации. Symphony особенно хорошо работает там, где у команды уже есть ясные issue, тесты и понятный процесс ревью.