📖 О чём этот гайд
Этот текст — не пересказ одного запуска, а рабочая схема, которую можно повторять на следующем крупном проекте. В основе лежит реальный опыт: неправильная доска, сломанный worker path, stalled review-gates, delayed checks, Telegram notify и финальный closeout. Но ниже всё сведено к форме, пригодной для повторного использования.
Главная идея простая: Hermes Kanban хорош не сам по себе, а как дисциплинированный контур управления. Источник истины — board и CLI, уведомления — отдельный слой, а возвращение агента “через 10 минут” — ещё один отдельный слой. Если смешать их в одну магию, проект быстро теряет управляемость.
Не путайте три механизма: board state, user notifications и delayed follow-up. Это разные контуры, которые надо проектировать отдельно.
🧭 Когда Kanban вообще нужен
Kanban имеет смысл там, где задача больше одного линейного прохода. Если работа распадается на discovery, implementation, review, validation, docs, self-check и publish, обычный чат быстро превращается в свалку из контекста. Карточки нужны не для красоты, а чтобы у каждого шага был свой статус, assignee, acceptance и evidence.
Хороший признак, что пора переходить на board: пользователь уже задаёт не единичное действие, а цель уровня “сделай рефакторинг”, “доведи проект до релиза”, “разложи план на рабочий граф”, “перестрой CLI/MCP слой”. В такой задаче важнее не скорость первого ответа, а долговечность управления хвостом.
🪜 Короткий decision rule
| Ситуация | Обычный чат | Kanban |
|---|---|---|
| Один файл, один фикс, одна проверка | да | не обязательно |
| Много зависимых шагов | плохо | да |
| Нужны review-gates | плохо | да |
| Нужно вернуться позже | неудобно | да |
| Нужны уведомления пользователю | частично | да |
| Нужен self-check → commit → push | хрупко | да |
🛠️ Шаг 1. Сначала зафиксировать board и project root
Первая ошибка в больших запусках почти всегда организационная: не тот board, не тот workdir, не тот assignee. Поэтому до первой содержательной карточки надо подтвердить, что board уже существует или создать его один раз и потом везде использовать явно.
Безопасное правило: во всех командах указывать --board <slug> явно. Не полагаться на boards switch, не надеяться на “текущую доску”, не принимать dashboard за источник истины. Для конкретного проекта достаточно один раз определить slug и дальше всё делать через него.
🔧 Минимальный preflight
hermes kanban boards list
hermes kanban --board <slug> list
hermes kanban --board <slug> stats| Что проверить | Почему это важно |
|---|---|
| board slug | исключает работу не в той доске |
| project root / default workdir | worker не уйдёт в соседний repo |
| assignee | dispatch не зависнет на пустом назначении |
| исходный backlog | не создадите дубль существующего графа |
Если этот preflight не сделан, дальше очень легко получить ложный прогресс: карточки уже создаются, а работают не там. Для большого проекта это хуже, чем медленный старт, потому что ошибка обнаруживается поздно.
🧱 Шаг 2. Собрать граф в правильном порядке
Для большого проекта не надо сразу плодить двадцать карточек без защитного слоя. Практически лучше сначала завести короткий стартовый контур: baseline, smoke/probe, synthesis/decomposition, а уже потом строить основной execution graph. Это даёт ранний ответ: board жива, worker жив, runtime жив, project context верный.
Декомпозиция бывает двух типов. Ручная — когда план ещё сырой и надо руками удерживать структуру. И plan-driven — когда уже есть текст плана и можно создать extraction/synthesis cards, которые сами превратят его в рабочий граф. Оба режима нормальны; выбирать надо по стабильности входного плана, а не по вкусу.
🧩 Два режима декомпозиции
| Режим | Когда брать | Плюсы | Минусы |
|---|---|---|---|
| Ручной | план сырой, recovery, много неопределённости | высокий контроль | больше рутины |
| Plan-driven | план уже стабильный | воспроизводимость | нужен хороший root brief |
🚦 Шаг 3. Разделить execution, review и fix
Критическая ошибка больших графов — считать review-required почти эквивалентом done. На практике это отдельная фаза. Карточка может иметь зелёные targeted tests и всё равно оставаться stop-signal для графа, пока кто-то не закроет её как done или не выделит один точный blocker.
Рабочий шаблон такой: implementation cards делают код и narrow verification; stalled review-gates собираются в review-card; если review находит один реальный дефект, создаётся fix-card. Это гораздо чище, чем заново гонять весь граф или вручную перечитывать четыре blocked карточки без структуры.
🔍 Review-card и fix-card
implementation slices
-> review-card
-> exact blocker
-> fix-card
-> close verified review-gates
-> dispatch| Тип карточки | Задача | Когда создавать |
|---|---|---|
| implementation | сделать slice и приложить evidence | всегда |
| review-card | закрыть / локализовать stalled review-gates | когда blocked стало несколько |
| fix-card | снять один точный defect | когда review сузил проблему |
| self-check | проверить весь хвост перед публикацией | перед commit |
Главный operational выигрыш здесь в том, что граф не теряет причинность. Пользователь и агент видят, где именно инженерная работа, а где уже процедурное закрытие gate-ов.
🔔 Шаг 4. Развести notify, delayed checks и автоматическое продолжение
Telegram notify — это не перенос сессии в Telegram. Это подписка task-level событий пользователю. Она полезна, когда нужно вовремя узнать про blocked/completed/self-check/commit/push, но board state всё равно остаётся в CLI. Поэтому подписывать надо не всё подряд, а running/review-critical/final cards до их следующего terminal event.
Delayed check — другой механизм. Он нужен, когда пользователь остаётся в живой CLI-сессии и хочет, чтобы агент вернулся через 10–15 минут, перепроверил board и продолжил. А cron closeout — третий механизм: для unattended-хвоста, когда надо пережить отсутствие пользователя и присылать короткие сигналы наружу.
📡 Три разных контура
| Контур | Что делает | Когда использовать |
|---|---|---|
| Kanban graph | двигает саму работу | всегда |
| Telegram notify | сообщает пользователю о milestone/blocker | на key cards |
| Delayed check / cron | возвращает агента позже | короткий live-check / долгий unattended |
Простой выбор: до 20 минут и чат живой — delayed check. Долгий unattended хвост — cron. Уведомить пользователя о milestone — notify-subscribe.
✅ Шаг 5. Делать closeout лестницей, а не одной надеждой
Закрытие большого проекта надо проектировать как отдельную последовательность шагов. Недостаточно “ну если всё ок, оно само доползёт”. Практически надёжнее явная лестница: закрыть подтверждённые review-gates, сделать dispatch, дождаться downstream, потом self-check, потом commit, потом push, потом закрыть master-card и финально проверить list/stats.
Важный нюанс: часть tail work после середины проекта уже не инженерная, а процедурная. Это надо говорить прямо. Пользователь иначе легко воспринимает blocked review-cards как ещё четыре больших разработки, хотя по факту там может остаться только human go-ahead и board mutation.
🏁 Шаблон closeout
hermes kanban --board <slug> stats
hermes kanban --board <slug> show <blocked-review-card>
hermes kanban --board <slug> complete <verified-card> --summary "..."
hermes kanban --board <slug> dispatch --max 6 --json| Этап | Что считается готовым |
|---|---|
| review closure | карточка либо done, либо blocker точный |
| downstream dispatch | появилась следующая running/ready работа |
| self-check | хвост графа проверен целиком |
| commit | зафиксирован итог |
| push | внешняя публикация завершена |
| final stats/list | todo=0, running=0, blocked=0 |
⚠️ Частые ошибки и анти-паттерны
Первая ошибка — считать browser/dashboard источником истины. Он полезен как обзор, но каноническая картина берётся из CLI. Вторая — пытаться разморозить граф до того, как доказан startup probe worker-а. Третья — не различать настоящий технический blocker и procedural review-gate. Четвёртая — подписывать карточку на Telegram уже после того, как её terminal event случился.
Ещё один болезненный анти-паттерн — обещать полную автоматическую мутацию доски без учёта safety-gates. Даже если код готов, worker может упереться в side-effect guard на complete / dispatch. Для длинных графов полезно заранее понимать, где нужен явный human go-ahead, а где можно двигаться автономно.
🧪 Мини-чеклист перед следующим большим запуском
- Board проверен и slug фиксирован.
- Project root совпадает с нужным repo.
- Worker path жив и не падает на startup.
- Runtime/provider не упирается в лимиты.
- Notify подписан на critical cards заранее.
- Review-gates имеют closure policy.
- Closeout оформлен как self-check -> commit -> push.
🔗 Что держать в памяти между проектами
Главное, что стоит унести из этого гайда, — не список конкретных task id, а форму процесса. Для большого проекта Hermes Kanban лучше работает как сочетание явного board control, небольших проверяемых slices, review/fix loops и аккуратного closeout. Именно это превращает агентную работу из длинного хрупкого чата в управляемый проектный контур.
Если повторять этот шаблон, то следующий крупный запуск будет не “как бы автоматическим”, а прозрачным и отлаживаемым. А это для большого кода ценнее красивой автономности: видно, что делает система, где она встала, чем это отличается от реальной инженерной работы и в какой момент уже можно честно закрывать проект.