Маленький инструмент, вокруг которого выстраивается весь процесс

28 сентября 2026 · 7 минут чтения

Почему одна узкая CLI-команда стала исполнимой границей между выбранной GitHub issue и изолированной средой для coding-агента.

start-issue — самостоятельная CLI-утилита. Ей передаёшь номер GitHub issue, а она создаёт ветку, отдельный git worktree и запускает в нём выбранного coding-агента.

Её можно вызвать напрямую из shell или встроить во внешний workflow — повторяемый рабочий процесс, например запускать каждую задачу в новой вкладке Zellij или tmux. Эти программы — терминальные мультиплексоры: они отвечают за то, где живёт сессия и как за ней наблюдать. start-issue отвечает за то, что именно в ней будет запущено.

За время использования утилита научилась запускать Claude, Codex, Kimi и Pi, получила настройки, dry-run — режим предварительного просмотра, безопасное переиспользование worktree, установщик, обновление и отдельный режим для Codex. Внутри даже сменился runtime: сначала это был shell, теперь Go.

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

До утилиты был ритуал

Начало любой задачи состояло из знакомой последовательности:

1. Открыть GitHub issue и восстановить её контекст.
2. Определить репозиторий и базовую ветку.
3. Придумать имя новой ветки.
4. Создать отдельный worktree.
5. Перейти в него.
6. Запустить нужного coding-агента.
7. Передать агенту ссылку на issue, её содержание и правила работы.

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

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

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

Одна команда убирает не действия, а неопределённость

В обычном случае запуск теперь выглядит так:

start-issue 42

На входе — номер issue или полная ссылка на неё. На выходе — подготовленная рабочая среда:

GitHub issue
→ branch
→ git worktree
→ init.sh, если есть
→ prompt с контекстом
→ сессия выбранного агента

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

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

Это уже не сокращение для удобства. Это граница процесса.

Откуда берётся prompt

Важно разделить две вещи. Самой start-issue prompt не нужен: GitHub issue, ветку, worktree и запуск init.sh обрабатывает код утилиты. Prompt предназначен coding-агенту, которого она запускает в уже подготовленной рабочей среде.

Шаблон prompt выбирается по прозрачному приоритету: явно переданный параметр команды, настройка из окружения, проектный .start-issue/prompt.md, пользовательский ~/.config/start-issue/prompt.md, затем встроенный шаблон для выбранного агента. Перед запуском в него подставляются ссылка и номер issue, заголовок, описание, метки, репозиторий, ветка, путь worktree и базовая ветка. Источник выбранного prompt утилита печатает в терминал, а --dry-run позволяет проверить настройки без создания worktree и запуска агента.

Когда запускается init.sh

init.sh отвечает уже не за инструкции, а за подготовку окружения. Если файл лежит в корне — верхней директории — созданного или переиспользованного worktree, start-issue выполняет там bash ./init.sh перед запуском агента. Это место для установки зависимостей и другой локальной подготовки проекта. Параметр --no-init отключает этот шаг. Если скрипт завершится с ошибкой, утилита предупредит об этом, но всё равно запустит агента.

Инструмент-шарнир

Я называю такие утилиты инструментами-шарнирами. Это не отраслевой термин, а моя рабочая метафора.

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

Для start-issue эта граница проходит между двумя состояниями:

задача выбрана, но работа ещё не началась
                    ↓
у задачи есть изолированная среда и исполнитель

До этой границы живут приоритизация, постановка задачи, критерии приёмки и архитектурные решения. После неё — анализ репозитория, написание кода, тесты, code review и pull request.

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

GitHub issue получает номер и структуру, потому что этот номер станет входом в запуск. Проект хранит настройки агента и prompt, потому что они будут автоматически разрешены на границе. Worktree становится стандартной единицей изоляции, а не опциональным трюком Git. Другой агент может запустить задачу той же командой, которой пользуется человек.

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

Процесс строится вокруг точки входа, а не помещается внутрь неё

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

Я стараюсь двигаться в противоположную сторону. Сила start-issue именно в узкой ответственности.

Утилита не должна:

• становиться менеджером GitHub Issues;
• решать, какую задачу делать следующей;
• подменять внутреннюю работу coding-агента;
• владеть политикой code review и merge;
• превращаться в постоянно работающий фоновый процесс, сервер или ещё одну базу данных.

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

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

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

Почему это стало особенно важно с coding-агентами

Человек способен компенсировать рыхлый процесс памятью и контекстом. Он замечает, что находится не в той директории, вспоминает соглашение об именовании веток и догадывается, какой prompt нужно дать Claude или Codex.

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

Во втором случае вместо длинной инструкции появляется короткий вызов:

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

Так маленький CLI становится API — устойчивым программным интерфейсом организационного процесса.

Это не отменяет текстовые инструкции. AGENTS.md, prompt и документы проекта по-прежнему объясняют правила, ограничения и смысл задачи. Но повторяемую механику выгоднее один раз выразить кодом, чем просить каждую новую сессию интерпретировать её заново.

Как утилита росла и не перестала быть маленькой

start-issue не является частью Zellij, tmux или другого терминального мультиплексора. Она живёт отдельно и не знает, как устроен внешний процесс. Её ответственность заканчивается там, где у issue появились изолированная рабочая среда и запущенный coding-агент.

Именно поэтому утилиту легко встроить в любой workflow. Например, управляющему агенту можно сказать: «Запусти задачу #123 через start-issue в новой вкладке Zellij». Тот же сценарий работает с tmux или другим мультиплексором. Сессия остаётся перед глазами: за работой агента можно наблюдать и при необходимости вмешаться.

По мере использования появились разные агенты, настройки проекта и пользователя, dry-run, проверка безопасного переиспользования worktree, готовые бинарники для установки, самообновление и Codex human-gate. Летом реализация переехала с shell на Go.

Со стороны это похоже на обычное накопление функций. Но почти все изменения защищали ту же границу:

• несколько агентов — исполнитель можно заменить, не меняя способ начала работы;
• порядок выбора настроек — до запуска понятно, откуда взялись агент, модель и prompt;
• dry-run — переход можно осмотреть без побочных эффектов;
• безопасность worktree — существующая ветка или директория не переиспользуется на веру;
• установка — сама точка входа должна быть доступна без отдельного ритуала;
• human-gate — автоматический запуск обязан вернуть управление человеку перед реальным решением.

Маленький инструмент не обязан иметь мало кода. Он должен владеть маленькой и ясной ответственностью.

Что start-issue не исправляет

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

start-issue не сделает хорошую задачу из плохо описанной issue. Не выберет правильную архитектуру. Не проверит бизнес-смысл результата. Не гарантирует, что агент напишет качественный код. Не заменит проверку кода и решение о merge.

Она гарантирует другое: работа начнётся в предсказуемом месте, с видимой конфигурацией и воспроизводимым контекстом.

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

Вместо заключения

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

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

start-issue не является системой агентной разработки. Это маленький шарнир между задачей и исполнением.

Именно поэтому вокруг него эта система и выстраивается.

Ссылки

• start-issue — исходный код, установка и актуальное описание командной строки.

Автор: Данил Письменный · Дата: 28 сентября 2026