Ты пишешь задачу. Агенты планируют, пишут код, делают ревью, проверяют безопасность и присылают уведомление в Telegram. Ты открываешь готовый результат.
Именно это делает AIF Handoff. Но чтобы понять, почему это работает, нужно разобраться с тем, что обычно идёт не так.
Часть 1. Почему вайб-кодинг ломается
Давайте рассмотрим эволюцию вайб-кодеров
Стадия 1. Лотерея
Один большой промпт, Enter, молишься. Иногда везёт. Потом начинаешь фиксить, добавлять фичи и постепенно приходишь к состоянию, которое невозможно поддерживать.
Причина банальная: у модели нет контекста о проекте. Она генерирует правдоподобный код, а не рабочий. LLM оптимизирует под «похоже на правильное решение», каждый новый запрос начинается без истории предыдущих решений.
Стадия 2. Бабушкины промпты
Системные инструкции в духе «ты опытный senior с 15-летним стажем, пиши только clean code» - не работают. Промпт задаёт тон ответа, но не меняет качество решений. LLM начинает отвечать в стиле человека, который так себя описывает. В Summary напишет «всё по best practices» - потому что ты так сказал.
Про контекст: главное
Не формулировать требования к модели, а формулировать контекст задачи.
Плохо:
Сделай авторизацию через JWT, используй best practices
Хорошо:
Вот AuthService (код), вот как хранятся сессии (код), вот middleware (код).
Нужно добавить refresh token. Используем Laravel Sanctum, менять нельзя.
Вот тест который должен пройти.
Во втором случае у модели нет пространства для изобретений. Конкретные файлы, явные ограничения, критерий успеха. Чем меньше неизвестного в промпте, тем предсказуемее результат.
Стадия 3: свои промпты, свой workflow
Бабушкины промпты не работают - это понимаешь быстро. Начинаешь разбираться как LLM реально обрабатывает запросы. Главный инсайт: модель не читает мысли, она работает с тем что ты ей дал. Чем точнее контекст - тем предсказуемее результат. Декомпозируешь задачи, сохраняешь рабочие промпты, собираешь свой процесс. Начинаешь руками таскать нужные файлы и куски кода в контекст. Подключаешь MCP. Уже лучше. Но ты всё ещё:
вкидываешь слишком большие куски и ждёшь хорошего результата
что-то забываешь передать в контекст - агент изобретает на пустом месте
вручную вызываешь команды одну за другой - как обезьяна
Ты сделал шаг вперёд. Но рутина никуда не делась. Делать вручную утомительно и ненадёжно. Нужна система, которая управляет контекстом автоматически.
Часть 2. AI Factory
AI Factory - это CLI и система скиллов, которая решает проблему контекста системно. Работает с любым кодинг-агентом: Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI и другими.
npm install -g ai-factory
ai-factory init
При инициализации система сканирует проект, определяет стек, устанавливает скиллы из маркетплейса skills.sh или генерирует кастомные, настраивает MCP-серверы. Создаётся структура:
your-project/
├── .claude/
│ └── skills/ ← markdown-файлы с инструкциями для агента
├── .ai-factory/
│ ├── DESCRIPTION.md ← описание проекта, стек, архитектура
│ ├── PLAN.md ← текущий план
│ ├── patches/ ← патчи самообучения
│ └── evolutions/ ← логи эволюций скиллов
└── .ai-factory.json
Скилл - это markdown-файл в .claude/skills/ с конкретными инструкциями для агента: как планировать, как делать ревью, какие правила соблюдать в этом стеке. Не «ты опытный разработчик», а «вот как именно делается план для этого проекта».
После инициализации открываешь агента (Claude Code, Cursor или любой другой) и используешь slash-команды:
/aif - инициализирует контекст сессии: читает DESCRIPTION.md, подключает скиллы и MCP. Не пишет код.
/aif-plan - составляет план фичи, создаёт git-ветку, анализирует кодовую базу.
/aif-implement - выполняет план по задачам с коммитами в чекпоинтах. Перед стартом читает все патчи из .ai-factory/patches/.
/aif-fix - фиксит баг и создаёт патч самообучения: что сломалось, почему, как исправили.
/aif-evolve - анализирует накопленные патчи, находит паттерны повторяющихся проблем, обновляет скиллы.
/aif-verify - валидирует что всё из плана сделано, ничего не пропущено.
Про самообучение стоит сказать отдельно. Каждый /aif-fix создаёт патч. Накопилась пачка - запускаешь /aif-evolve: система смотрит на паттерны ошибок и обновляет скиллы под твой проект. При каждом /aif-implement агент читает все патчи перед стартом - система учится постоянно, не только при явном вызове /aif-evolve.
Подробнее про Ai Factory можно посмотреть в статьях на Habr:
Часть 3. AIF Handoff
AI Factory мощный инструмент, но ты всё ещё вручную вызываешь команды и переключаешься между задачами. AIF Handoff убирает этот луп полностью.
Handoff - это веб-приложение (React + Hono API + SQLite) с Kanban-доской, которое запускает агентный пайплайн автономно. Построен поверх AI Factory, использует Claude Agent SDK.
Backlog → Planning → Plan Ready → Implementing → Review → Done
Ты создаёшь задачу в UI. Дальше система сама двигает её по статусам через WebSocket в реальном времени.
Агентный пайплайн
plan-coordinator - не просто генерирует план. Внутри цикл: plan-polisher итеративно рафинирует план до тех пор пока не пройдут критерии качества. В итоге план проходит несколько раундов проверки прежде чем уйти в реализацию.
implement-coordinator - вычисляет слои зависимостей между задачами и запускает параллельные воркеры там, где задачи независимы. Каждый воркер работает в отдельном git worktree.
review-sidecar + security-sidecar - запускаются параллельно после реализации. Ревьюер проверяет качество кода и соответствие плану. Аудитор безопасности проходит по чек-листу: XSS, SQL-инъекции, утечки данных, некорректная авторизация. Если настроен MCP Playwright - будет браузерная проверка.
Если ревью нашло проблемы, задача автоматически возвращается в Implementing с конкретными замечаниями:
Implementing → Review
↓ fix items найдены
→ Implementing → Review
↓ окей
→ Done (ждёт Approve)
Есть лимит итераций. Без него агент может крутиться по кругу и уничтожить весь бюджет подписки за ночь.
Human-on-the-Loop, не Human-in-the-Loop
Два паттерна работы с агентами.
Human-in-the-Loop: человек участвует в каждом переходе. Максимальный контроль, минимальная скорость.
Human-on-the-Loop: человек задаёт задачу и критерии, система работает автономно, человек принимает или отклоняет финальный результат. Именно так работает AIF Handoff.
Финальный Approve всегда за тобой. Но ты перестаёшь быть диспетчером который переключает этапы вручную. Запускаешь задачу, закрываешь ноутбук, получаешь уведомление в Telegram когда всё готово.
Два режима выполнения
Subagents (по умолчанию) - полный пайплайн с координаторами, итеративным уточнением плана, параллельными воркерами и quality sidecars. Выше качество, больше токенов.
Skills - однопроходное выполнение через /aif-plan, /aif-implement, /aif-review. Быстрее и дешевле, без итеративного рафинирования. Подходит для простых задач.
Переключается глобально через AGENT_USE_SUBAGENTS или per-task в UI.
Часть 4. Установка
git clone https://github.com/lee-to/aif-handoff
cd aif-handoff
npm install
npm run init
npm run dev
Запускает три сервиса через Turborepo:
Сервис | URL | Описание |
|---|---|---|
API |
| Hono REST + WebSocket |
Web |
| React Kanban UI |
Agent | background | Координатор + субагенты |
Агент реагирует на события задач через WebSocket и фоллбэчит на 30-секундный polling.
Docker (рекомендую для изоляции):
docker compose up
Агенты работают только внутри директории проекта. При первом запуске нужно залогиниться в Claude Code - в терминале появится ссылка для OAuth.
По умолчанию используются ~/.claude/ credentials от активной Claude подписки. Для отдельного API-ключа - скопируй .env.example в .env и выставь ANTHROPIC_API_KEY.
Ключевые переменные .env:
AI_LANGUAGE=ru # язык агентов
MAX_REVIEW_ITERATIONS=3 # лимит итераций ревью
AGENT_USE_SUBAGENTS=true # режим выполнения
AGENT_BYPASS_PERMISSIONS=true # если агент жалуется на permissions
# Telegram уведомления
TELEGRAM_BOT_TOKEN=...
TELEGRAM_CHAT_ID=...
После запуска открываешь http://localhost:5180, создаёшь проект с указанием пути до директории. Система инициализирует Git и запускает ai-factory init.
Часть 5. Двунаправленная синхронизация
Handoff и AI Factory работают в обе стороны через MCP.
Запустил задачу в Handoff, решил продолжить в Claude Code напрямую - Claude Code видит атрибут handoff-task в plan.md и через MCP автоматически обновляет статусы в Kanban. Работаешь в AI Factory как обычно - Handoff отражает изменения в реальном времени.
Через MCP к Handoff подключается любой совместимый агент.
Часть 6. Paperclip и AIF Handoff: разные инструменты для разных задач
Наверняка уже слышали про Paperclip - инструмент для создания агентских пайплайнов.
Но это инструмент для агентской оркестрации: маркетинг, контент, SEO-пайплайны. Задачи где нужно прогнать информацию через цепочку специализированных агентов. Для своей аудитории работает хорошо.
AIF Handoff для другого. Он знает твой стек, накапливает опыт конкретного проекта через патчи и скиллы, проверяет код а не текст, запускает параллельные воркеры с изоляцией через git worktrees.
Часть 7. Реальный пример
Создаёшь задачу в UI:
Создай landing для github.com/lee-to
Включаешь автомод, запускаешь. Дальше только наблюдаешь по уведомлениям в Telegram:
Задача → Planning
plan-coordinator создаёт план, plan-polisher рафинирует
Задача → Implementing
implement-coordinator вычисляет слои зависимостей,
запускает параллельные воркеры
Задача → Review
review-sidecar: найдено 2 замечания
security-sidecar: окей
→ автоматически возвращается в Implementing
Задача → Review (итерация 2)
review-sidecar: окей
security-sidecar: окей
Задача → Done. Ожидает Approve
Открываешь UI, смотришь результат, нажимаешь Approve или Request Changes.
Для тех, кто больше любит контент в формате видео, записал обзор:
Часть 8. Roadmap
Для больших задач: создаёшь Roadmap в UI, вводишь описание, жмёшь «Генерировать». Система разбивает на фазы и конкретные таски с зависимостями.
Если roadmap.md уже есть в проекте - импортируется одной кнопкой.
Часть 9. Стек и текущее состояние
Технический стек Handoff:
Слой | Технологии |
|---|---|
Runtime | Node.js + TypeScript, Turborepo монорепо |
База данных | SQLite (better-sqlite3 + drizzle-orm) |
API | Hono + WebSocket |
Frontend | React + Vite + TailwindCSS + @dnd-kit |
Планировщик | node-cron |
Доступно сейчас: Kanban + list view с real-time обновлениями, полный агентный пайплайн, самообучение через AI Factory, двунаправленная MCP-синхронизация, Telegram-уведомления, Roadmap для декомпозиции, метрики потребления токенов, Docker + production compose.
В бэклоге: JetBrains-плагин (в разработке) и интеграция с CI/CD.
Сам Handoff разрабатывается внутри Handoff. Разделён на изолированные слои (shared → data → api/agent/web), покрыт тестами с минимальным порогом 70%, ESLint guards запрещают прямые DB-импорты в api и agent минуя @aif/data.
Вайб-кодинг эволюционирует: от лотереи с промптами к осознанному процессу, от ручного воркфлоу к автопилоту с человеком на выходе.
AIF Handoff - это Human-on-the-Loop на практике. Ты пишешь задачу. Всё остальное система.
AI Factory: github.com/lee-to/ai-factory
AIF Handoff: github.com/lee-to/aif-handoff
Сайт: aif.cutcode.dev