VibeTrace (Observe → Understand → Intervene → Evolve): точечный откат траектории кодинг-агента и превращение правок человека в переиспользуемые скилы

ШАГ 1 (Observe — Наблюдение): Запись каждого шага агента как структуры (действие, входное состояние, артефакт, время/токены, итоговое состояние) → [Иерархическая карта траектории вместо простыни текста]
ШАГ 2 (Understand — Диагностика): Отслеживание связей между действиями и поиск красного узла, где план или команда пошли не так → [Точка расхождения]
ШАГ 3 (Intervene — Ветвление): Откат (fork) к шагу перед ошибкой с целевой корректировкой человека при сохранении валидного контекста → [Новая успешная ветка решения]
ШАГ 4 (Evolve — Дистилляция в скил): Сравнение ошибочной и исправленной веток и упаковка правила/стратегии человека в переиспользуемый скил → [Обновлённый пул скилов агента]

В системе VibeTrace (надстройка над OpenCode) все 4 шага работают через визуальный интерфейс, а в стандартных агентах (Claude Code, Cursor) шаги 3 и 4 воспроизводятся через ветвление сессии (/rewind / fork) и промпт дистилляции правки в SKILL.md.

Задача: Тимлид финтех-команды поручает кодинг-агенту добавить идемпотентную обработку вебхуков Системы быстрых платежей (СБП) в сервис оплаты на FastAPI. Первые 5 шагов агент делает отлично: находит нужные роуты, изучает схему БД и модели платежей. Но на 6-м шаге вместо блокировки строки в PostgreSQL (SELECT ... FOR UPDATE) агент начинает городить самописный кэш в оперативной памяти процесса, который развалится при запуске нескольких воркеров Gunicorn.

Промпт (для дистилляции вмешательства человека в переиспользуемый скил на шаге Evolve):

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

Контекст задачи:
Добавление идемпотентной обработки вебхуков оплаты СБП в FastAPI-бэкенд.

Валидный прогресс до точки ветвления (Шаги 1–5):
Агент корректно нашёл эндпоинт `/api/v1/sbp/webhook`, схему таблицы `payment_events` и тесты в `tests/test_webhooks.py`.

Ошибочное действие агента в узле ветвления (Шаг 6, старая ветка):
Агент попытался реализовать защиту от дублей вебхуков через глобальный `dict` в памяти Python-процесса (`_processed_ids = set()`).

Моё вмешательство и корректировка (Шаг 6', новая ветка):
Откат к Шагу 5 с инструкцией: «Сервис работает в нескольких воркерах Gunicorn, хранить состояние идемпотентности в памяти процесса запрещено. Используй уникальный индекс по `operation_id` в PostgreSQL (`INSERT ... ON CONFLICT DO NOTHING`) и транзакционную блокировку `SELECT ... FOR UPDATE`».

Сформируй из этого сравнения компактный переиспользуемый скил:
1. Название и условие активации (когда загружать скил).
2. Антипаттерн (какое решение агента было ошибочным и почему).
3. Проверенная процедура (пошаговый порядок действий, который привёл к успешной ветке).

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

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

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

Цикл VibeTrace объединяет эти свойства: он фиксирует каждый шаг в виде проверяемой пятёрки $(a_i, s_i, o_i, t_i, r_i)$ — действие, состояние до, артефакт, время/токены, состояние после — и превращает точку вмешательства человека в обучающий контраст «как агент хотел сделать vs как человек его направил». Дистилляция этого контраста прямо в момент починки создаёт живой скил, привязанный к реальному контексту выполнения.

Рычаги управления: - Гранулярность осмотра (Trace Cards vs узлы действий) → сначала смотрите на карточку этапа (расход токенов, стоимость, число вызовов LLM и красные флаги ошибок), и раскрывайте граф отдельных действий только там, где метрики или результат просели. - Точка ответвления (Fork) → откатывайтесь ровно к тому узлу, где разведка файлов уже завершена, но неверная правка кода ещё не внесена: это экономит токены на повторном чтении репозитория. - Онлайн-дистилляция после правки → превращайте вмешательство в скил только тогда, когда исправленная ветка прошла проверку и содержит повторяющийся паттерн проекта, чтобы не засорять пул скилов разовыми опечатками.

Ты — модуль онлайн-дистилляции опыта совместной работы разработчика и кодинг-агента (Online Trace-to-Skill Distillation).

Исходная задача:
{описание_задачи}

Общая валидная история до точки вмешательства (сохранённый контекст):
{валидные_шаги_до_форка}

Отклонённая ветка агента (действие, состояние, ошибка/причина отклонения):
{ошибочный_шаг_и_следствие}

Вмешательство человека и успешная ветка (корректировка и итоговые шаги):
{корректировка_человека_и_результат}

Сформируй переиспользуемый скил для пула навыков агента по следующей структуре:
- Имя скила: {короткий_глагольный_заголовок}
- Условия активации (When to use): при каких признаках задачи и состояния среды вызывать этот скил.
- Диагностика сбоя (What to avoid): какой шаг агента приводит к ошибке и по какому признаку его распознать в траектории.
- Рабочая процедура (Execution strategy): точная последовательность действий и проверок из успешной ветки.

Что подставлять в плейсхолдеры: - {описание_задачи} — формулировка тикета или задачи на разработку. - {валидные_шаги_до_форка} — какие файлы и состояния агент успешно собрал до ошибки. - {ошибочный_шаг_и_следствие} — действие, на котором агент свернул не туда. - {корректировка_человека_и_результат} — инструкция, которой вы перенаправили агента, и успешный исход новой ветки.

🚀 Быстрый старт — вставь в чат:

Вот шаблон дистилляции вмешательства в скил из метода VibeTrace. Адаптируй под мою задачу: [твоя задача]. 
Задавай вопросы, чтобы заполнить поля.

[вставить шаблон выше]

LLM спросит, на каком шаге ваш кодинг-агент свернул не туда и какой командой вы его поправили, после чего соберёт готовый блок для вашего SKILL.md или CLAUDE.md.

⚠️ Привязка готового визуального интерфейса к OpenCode: Готовая система визуализации графа и интерактивного форка VibeTrace построена поверх открытого агента OpenCode. При работе в закрытых средах (Claude Code, Cursor) визуального дерева веток из коробки нет — там метод применяется через штатный откат шагов (/rewind / чекпоинты) и сохранение скилов в .claude/skills/.

⚠️ Умеренный прирост точности при большой экономии токенов: На бенчмарке SWE-bench Verified накопленные скилы дают в первую очередь экономию ресурсов (снижение входных токенов на 23% и стоимости на 15,5%), тогда как итоговая доля решённых задач растёт умеренно (на 3 процентных пункта).

Команда из Университета Тунцзи (Шанхай) и Лундского университета (Швеция) начала с глубокого интервью 12 практиков со средним опытом разработки почти 5 лет (8 программистов, 2 продакт-менеджера и 2 UI/UX-дизайнера), которые больше года ежедневно работают в Claude Code, Codex, Cursor и OpenCode. Разбор реальных кейсов показал пять системных проблем: разработчики не доверяют текстовым самоотчётам агента без привязки к реальным вызовам инструментов, не видят причинно-следственной связи между ранним неверным допущением в плане и поздним падением теста, теряют валидный прогресс при перезапуске сбившегося агента и вынуждены из раза в раз вручную повторять одни и те же проектные правки. На основе этих находок авторы построили систему VibeTrace поверх OpenCode, которая группирует 12 базовых действий агента в 7 категорий (планирование, сбор контекста, модификация кода, коммуникация, работа со скилами, исполнение команд и сжатие контекста), строит иерархические карточки с расходом токенов и временем каждого шага, позволяет форкать выполнение с любой точки и автоматически дистиллирует успешные правки человека в скилы. Проверка на бенчмарке SWE-bench Verified показала, что дистиллированные из траекторий скилы сокращают расход входных токенов на 23,0% и стоимость прогона на 15,5%, одновременно повышая долю решённых задач с 65,0% до 68,0%, а лабораторное исследование с пользователями и экспертные интервью подтвердили, что визуальные карточки траекторий позволяют находить причину ошибки агента быстрее и точнее, чем чтение обычных логов чата.

🔧 Техника: Правило «Чекпоинт после разведки» в CLAUDE.md → дешёвый откат без потери контекста в любом консольном агенте

Поскольку в исследовании показано, что главная потеря при перезапуске агента — сгорание уже собранного контекста репозитория (Information Acquisition), разделите работу агента в CLAUDE.md на два явных этапа:

Copy

Перед внесением первых правок в код (после чтения файлов и поиска по репозиторию) всегда выводи краткую сводку найденных файлов, зависимостей и план изменений одним сообщением. Это точка чекпоинта: если при написании кода или прогоне тестов ветка зайдёт в тупик, мы сделаем откат к этому сообщению без повторного чтения проекта.

Экстраполяция на командную базу знаний (Team Skill Pool): В конце рабочего дня или при закрытии сложного пул-реквеста прогоняйте сессии, где разработчику пришлось вручную поправлять агента, через шаблон дистилляции VibeTrace и коммитьте полученные файлы скилов в общую папку репозитория (.claude/skills/ или .cursor/rules/). Так удачная правка одного сеньора мгновенно страхует агентов всей команды от повторения той же ошибки.

[From Watching to Steering: Enabling Human–Coding Agent Collaboration through Execution Traces] [https://arxiv.org/abs/2611.04466, код системы VibeTrace: https://github.com/idvxlab/VibeTrace] [Xiaoke Yan, Jiaying Lei, Danqing Shi, Zichen Wang, Nan Cao — Tongji University, Lund University]