Очередь задач для агента: как я перевёл работу через issue и перестал объяснять всё заново

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

Решение оказалось скучным. Задачи живут в issue, issue висят на доске, доска — первое, куда агент лезет при старте.

Почему issue, а долгие промпты проигрывают

Issue — это внешняя память, и видим её оба: я и агент. У неё есть свойства, которых чат не даёт:

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

Чат так не умеет. Чат — это разговор, который заканчивается.

Как это устроено у меня

В репозитории 168fz-bot (телеграм-бот по 168-ФЗ) в CLAUDE.md есть секция Workflow. Она короткая и начинается с одной команды:

gh project item-list 2 --owner ragastar --format json

Дальше — простая логика:

1. Есть задача в статусе In Progress — продолжай её.
2. Нет — спроси меня или предложи создать issue.

Всё. Никакой магии. Агент запускается, дёргает доску, видит «переписать парсер реестра, In Progress», подтягивает тело issue с acceptance criteria, читает комментарии и продолжает с того места, где мы остановились.

Правила создания issue тоже прописаны: заголовок краткий и на русском, в теле — что сделать, зачем и по каким критериям считаем готовым. Добавить на доску, проставить Priority и Type, двинуть в Todo или In Progress. Когда правило записано, агент заводит задачи сам и в нужном формате.

Комментарии как журнал решений

Отдельный пункт в правилах: важное решение уходит комментарием в issue. Уперлись в проблему — тоже комментарий.

Выглядит бюрократией ровно до первого возврата к задаче через неделю. Открываешь issue и читаешь: «выбрали long polling, потому что на VPS нет валидного сертификата для вебхука». Восстанавливать логику по коду уже не нужно.

Есть ещё одно правило, до которого я дошёл на практике: данные из БД в issue не дублировать. Вместо «в таблице 340 записей» пишем, как эти данные достать. Цифра протухнет за день. Запрос останется рабочим.

Коммит закрывает круг

После завершения работы коммит содержит #N — номер issue. GitHub сам связывает их. В истории 168fz-bot видно, как это работает на реальных задачах: SEO-правки, схема разметки, страница 404, мобильная навигация. Каждый кусок привязан к задаче, и в логе нет одиноких строк «Fix stuff».

Последний коммит в этом репозитории как раз добавляет секцию Workflow в CLAUDE.md. Схему я сначала обкатал руками, потом записал агенту как инструкцию.

Хуки я попробовал и убрал

В отдельном репозитории claude-config я собираю конфигурацию Claude Code: CLAUDE.md, правила, методичку. Там же была попытка автоматизировать проверку доски через session-start хук — скрипт дёргает gh при старте сессии и подсовывает результат в контекст.

Сначала пришлось чинить сам хук: внешний jq в окружении подводил, переехал на встроенный gh --jq. А потом я хуки просто выкинул и заменил правилом в CLAUDE.md. Причина простая: хук — лишний слой, который ломается молча. Правило в тексте агент читает и выполняет. Забил на правило — это видно сразу.

Ленивое решение оказалось надёжнее умного.

Где схема буксует

Честно про минусы.

Мелочёвка. Заводить issue ради правки опечатки — перебор. Такие вещи я делаю прямо в чате.

Дисциплина на старте. Первые дни приходится напоминать: «проверь доску». Пока правило не устоялось, агент иногда бросается кодить с места.

Качество формулировок. Issue вида «доделать бота» одинаково бесполезна для человека и для агента. Acceptance criteria — обязательная часть. Без них агент решит сам, что считать готовым, и вы удивитесь результату.

С чего начать

Минимальный набор занимает вечер:

• заведите проект в GitHub Projects, добавьте поля Priority и Type;
• перенесите текущие задачи в issue, каждой — критерии готовности;
• добавьте в CLAUDE.md секцию Workflow: команда для чтения доски, что делать с In Progress, правила создания issue и формат коммита;
• поработайте так неделю и допишите правила там, где агент повёл себя странно.

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