Issue-Driven Development с ИИ: от задачи в трекере до пул-реквеста

Каждая новая сессия с ИИ-агентом начинается с чистого листа. Вчерашние три часа, за которые мы выясняли, почему хуки не запускаются на Windows, для него просто не существовали. Какое решение приняли, почему выкинули первый вариант — стёрто. И человек садится пересказывать всё заново: по памяти, с пропусками.

Issue-Driven Development убирает пересказ. Состояние работы лежит в трекере: задача, обсуждение, принятые решения, ссылки. Сессия начинается с чтения доски. Мой монолог больше не нужен.

Как выглядит цикл

У меня это описано в rules/workflow.md внутри репозитория ragastar/claude-config. Первый шаг агента в любой сессии:

1. Проверить доску: gh project item-list 2 --owner ragastar --format json
2. Есть задача в статусе In Progress — продолжить её
3. Задачи нет — спросить меня или предложить создать issue

Три строки в правилах. И они меняют характер разговора: агент приходит с вопросом «продолжаем #4?» вместо «чем займёмся?».

Issue как техзадание

Заголовок краткий, на русском. Тело — три блока: что сделать, зачем, acceptance criteria. Дальше задача попадает на доску, получает Priority и Type, едет в Todo или сразу в In Progress.

Acceptance criteria — самая полезная часть. Пока их нет, «сделано» остаётся вопросом вкуса. Когда они есть, агент сам понимает, где остановиться, и перестаёт из вежливости переписывать соседние файлы.

Плохая формулировка: «починить хуки». Хорошая: что именно ломается, на какой машине, как проверить, что починилось.

Комментарии по ходу работы

Правило простое. Важное решение — комментарий в issue. Упёрлись в проблему — комментарий в issue.

Живой пример из моего репозитория. Хук session-start падал, потому что дёргал внешний jq, которого на машине не было. Исправили через встроенный gh --jq — коммит 77e8c9e. Через несколько часов выяснилось, что хуки из settings.json на Windows вообще не срабатывают, работают только через плагины. Решение — выкинуть хуки и заменить их правилом в CLAUDE.md (129a588).

Если бы эта история жила только в чате, я бы через месяц снова полез настраивать хуки. Она лежит в issue, в разделе «Известные проблемы», и агент читает её каждый раз.

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

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

В сообщении коммита — номер issue через #N. GitHub сам связывает коммит с задачей, и в issue появляется история изменений. Дальше пул-реквест, где описание собирается из тела задачи и комментариев по ходу работы.

В моей истории коммитов это видно: 2188494 — «Обновить методичку и CLAUDE.md, закрыть issue #1». Задача, работа, закрытие — одна нитка.

Pinned issue про сам процесс

Отдельная закреплённая issue посвящена фундаменту: воркфлоу, CLAUDE.md, правила, хуки. Живой документ с двумя разделами — «Текущее состояние» и «Известные проблемы».

Там записано, что глобальный CLAUDE.md работает и проверяет доску при старте сессии. Что rules/machines.md описывает инфраструктуру Windows и Ubuntu. Что методичка лежит в docs/onboarding.md. Меняются правила — меняется и эта issue.

Почему в трекере? Файл никто не перечитывает. Issue приходит в уведомлениях и подталкивает вернуться.

PRD и правило его обновлять

Последний коммит на сегодня — 24c8e63, PRD-шаблон плюс правило обновлять PRD после изменений. Отдельная боль: документ пишется один раз и через месяц врёт.

Правило в CLAUDE.md заставляет агента после каждого значимого изменения возвращаться к PRD и приводить его в соответствие. Работы на минуту, а документ остаётся рабочим.

Что это даёт на практике

Три вещи, которые я почувствовал руками:

• Старт сессии занимает секунды. Агент читает доску и знает, где мы остановились.
• Решения перестали теряться. Причина отказа от хуков лежит в issue. Моя память тут больше ни при чём.
• Задачи стали меньше. Когда пишешь acceptance criteria, сразу видно, что «переделать конфиг» — это четыре задачи.

С чего начать

Минимальный набор: репозиторий, GitHub Project, установленный gh, файл с правилами, который агент читает при старте. Дальше одно правило — проверять доску первым действием.

Остальное нарастёт само, когда появятся первые грабли. У меня фундамент собрался за один день и пять коммитов. Дальше он живёт и правится по мере того, как я нахожу, что работает.