Написать в Telegram

pstack: как научить кодинг-агентов проверять свою работу и доверять им больше. Пошагово

Содержание
  1. Что получится в итоге
  2. Что понадобится
  3. Как выглядит путь: кривая доверия
  4. Шаг 1. Дайте агенту проверять работу самому
  5. Шаг 2. Соберите навык, который управляет приложением
  6. Шаг 3. Добавьте карту функций
  7. Шаг 4. Превращайте каждый сбой агента в навык
  8. Шаг 5. Проверяйте навыки оценками
  9. Шаг 6. Выпустите агентов в облако
  10. Шаг 7. Замените просьбы жёсткими правилами
  11. Если вы работаете из России
  12. Что важно знать до старта
  13. Что дальше

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

pstack снимает этот потолок. Это плагин с набором навыков для Cursor: его собирали постепенно, превращая каждую ошибку агента в навык. Идея простая: дать агенту способ проверять себя, а важные правила закрепить так, чтобы их нельзя было нарушить. Об этом говорят сейчас, потому что по такой схеме в примере дошли до агентов, которые сами сливают правки в основную ветку, а утром остаётся просмотреть результат.

Что получится в итоге

Система из нескольких уровней. Агент сам запускает приложение и проверяет, что изменение работает. Он знает, как добраться до любой функции. Навыки проверены оценками, как код тестами. А то, что нельзя нарушать, держит автоматическая проверка в CI, а не просьба в промте. Для примера возьмём десктопное приложение на Electron и React, но принцип тот же для веба и мобильных приложений.

Что понадобится

  • Кодинг-агент с поддержкой навыков. В примере это Cursor. Навык это обычный markdown-файл.
  • Приложение, которое агент может запустить сам. Веб, Electron или iOS-симулятор.
  • Время на старте. Первые навыки придётся наблюдать вручную: открывать вызовы инструментов и читать рассуждения агента.
  • Токены. Настройка кодовой базы под агентов стоит денег, подробнее в разделе о рисках.

Как выглядит путь: кривая доверия

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

Кривая доверия к агентам: сначала быстрый рост, затем выход на плато
Кривая доверия к агентам: сначала быстрый рост, затем выход на плато

С ростом доверия растёт и результат. В примере за пять месяцев набралось больше 3000 PR: в прошлом месяце около тысячи, в текущем к 12 числу почти 800. Бывает, что за ночь агенты вливают около двадцати PR, и утром остаётся просмотреть их уже на main. Вопрос про качество справедлив, ему посвящены шаги ниже.

График вклада в PR: рост совпадает с ростом доверия к агентам
График вклада в PR: рост совпадает с ростом доверия к агентам

Обойти эту кривую нельзя: она про ваш личный уровень доверия. pstack помогает пройти её быстрее, но слепо верить плагину не стоит. Берите его как основу и правьте под свои стандарты.

Шаг 1. Дайте агенту проверять работу самому

Главный навык при работе с агентами это проверка (verification). Агент должен уметь запустить код, снять трассу производительности или снимок памяти, открыть iOS-симулятор, то есть воспроизвести то, что видит пользователь. Это не гарантирует хороший код, но гарантирует правильный. Для доверия это большой шаг.

Без проверки проверяющим становитесь вы. Агент пишет код, вы запускаете сборку, видите ошибку и копируете скриншоты в чат. Вы остаётесь узким местом, и распараллелить работу нельзя.

В примере это видно на задаче про производительность окна агентов. Разработчик снимал трассу в Chrome DevTools и разбирал flame graph, не зная код. Агент тоже не знал: получал скриншот трассы, уверенно называл причину, а правка не помогала. Помог один из первых навыков, который научил агента управлять приложением самому.

Шаг 2. Соберите навык, который управляет приложением

Навык в примере называется control-glass. Он запускает работающую сборку и управляет ею через протокол Chrome DevTools с помощью Playwright. Агент смотрит DOM, делает скриншоты, нажимает и печатает, читает дерево доступности, выполняет JS, снимает профили, замедляет процессор и сеть, читает консоль. Для iOS по тому же принципу берут утилиты Apple для симулятора и трасс. Такой навык агент может написать для вас сам: достаточно объяснить, какое у вас приложение.

Навык control-glass: описание, что умеет, и команда со списком возможностей
Навык control-glass: описание, что умеет, и команда со списком возможностей

Детали из файла навыка. Одна команда выводит список возможностей и флагов. Для параллельной работы в отдельных рабочих деревьях (worktree) у каждого свой порт и каталог данных, чтобы агент не сломал основную сборку и не испортил вход в аккаунт. Команда doctor только читает и отвечает, стоит ли управлять этой копией приложения.

Быстрый старт для worktree: настройка, перезапуск, проверка состояния и очистка
Быстрый старт для worktree: настройка, перезапуск, проверка состояния и очистка

Шаг 3. Добавьте карту функций

Навык научил агента запускать приложение, но не объяснил, что это за приложение. Приходит жалоба: боковая панель тормозит или вкладка с PR не работает. Агент мечется, ищет по коду, где это находится, и не понимает, как добраться до этого в интерфейсе.

Решение: файл-карта функций (feature map) рядом с навыком. Для каждой функции там написано, как до неё добраться глазами пользователя, какие горячие клавиши ей соответствуют и какие DOM-атрибуты брать для выбора элементов через CDP. На примере боковой панели: как скрыть и показать её, как менять ширину, где меню настройки, как группировать список агентов.

Файл карты функций для боковой панели: как добраться, клавиши и действия
Файл карты функций для боковой панели: как добраться, клавиши и действия

В pstack есть навык create verification: он сам изучает код и строит первую карту функций. Навык maintain verification держит её в актуальном виде. Выигрыш виден на плохих отчётах: в Slack часто приходит скриншот с подписью из трёх вопросительных знаков. Без карты агент отвечает, что ничего не понял. С картой он понимает, о какой функции речь, и может её воспроизвести.

Шаг 4. Превращайте каждый сбой агента в навык

Навык это markdown с инструкциями и контекстом, которых у агента нет. Сравните с новым сотрудником: сильный программист, но без знания вашего бизнеса. Чтобы он стал полезным, ему нужно объяснить, как у вас принято.

pstack строился так: наблюдали за ошибками агента, и каждую превращали в навык. В примере в вызовах инструментов заметили, что агент даже не читает код, о котором уверенно рассуждает. По смыслу инструкция получилась такая:

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

На старте не наблюдайте пассивно. Открывайте вызовы инструментов, читайте код и рассуждения агента, спрашивайте, почему сделано так, как при парном программировании.

Шаг 5. Проверяйте навыки оценками

Оценка (eval) это юнит-тест для навыка. Специальный фреймворк не нужен, строгость вы выбираете сами. В pstack есть готовый eval playbook.

Порядок такой. Агент-координатор составляет рубрику: что навык должен делать. Затем запускает много субагентов, каждому делает свой каталог с нейтральным названием. Это нужно, чтобы субагент не понял, что его оценивают: заметив это, он меняет поведение. Прогон можно повторить на разных моделях. Агент-судья на другой модели проверит, что первая модель не завышает баллы.

Слайд про доверие: проверка, хорошие навыки, оценки и переработка архитектуры
Слайд про доверие: проверка, хорошие навыки, оценки и переработка архитектуры

Оценка даёт балл, значит, навык можно улучшать циклом. В Cursor для этого есть команда /loop. Задача в таком духе:

Повторяй прогон оценки, пока по всем пунктам не будет 10 из 10.

Так в примере собирали навык управления приложением, почти без участия человека. Но на старте понадобилось много итераций. Поддерживать навыки трудно: нужны вкус и наблюдательность.

Шаг 6. Выпустите агентов в облако

Начинайте локально: так видно, что делает агент и как вызывает инструменты. Облачных агентов подключайте, когда доверие появилось. Если один раз настроить окружение, навыки проверки окупаются для всей команды.

В примере агент Benny берёт отчёты об ошибках, открывает в облаке свой компьютер, запускает приложение теми же навыками и пытается воспроизвести ошибку. Он ответил в треде: воспроизвёл на прошлом коммите, на исправленном не воспроизводится. Значит, ошибка уже исправлена на main, и остаётся выпустить сборку.

Ответ агента в треде: ошибка воспроизведена, но уже исправлена на main
Ответ агента в треде: ошибка воспроизведена, но уже исправлена на main

Порядок пути такой: проверка и навыки, доверие локально, облачные агенты, и только потом автослияние PR. Этапы пропускать нельзя: сотни облачных агентов без доверия сожгут много токенов.

Шаг 7. Замените просьбы жёсткими правилами

Третья часть: архитектура кодовой базы под агентов. Самый рискованный случай это новое приложение, написанное в режиме vibe coding без ограничений. Агенты решают задачи самым удобным способом, и код выходит из-под контроля. Поэтому ограничения нужны с самого начала.

В примере для приложения Grok Bot всё переписали на архитектуру Dune. Это что-то вроде Next.js для Electron-приложений, рассчитанное на агентов. Принцип: самый короткий путь должен быть и самым правильным, ведь агенты любят короткие пути.

Описание архитектуры: агент копирует ближайший шаблон и выбирает кратчайший путь
Описание архитектуры: агент копирует ближайший шаблон и выбирает кратчайший путь

Как это выглядит на практике:

  • Фича в одной папке. Весь код функции лежит рядом, агенту не нужно искать по проекту.
  • Запреты в CI. В примере запрещён useEffect, частый источник проблем в React. Запрещены даже комментарии в коде: агенты пишут комментарии об истории правки, которые потом вводят в заблуждение.
  • Границы процессов. Каталоги главного и отрисовочного процессов Electron разделены. CI проверяет граф зависимостей и не пропускает импорт из одного в другой.
  • Пять правил архитектуры. Обычный путь требует меньше решений, чем обходной. Запрещённые зависимости ломают сборку. У каждого долговечного значения один явный источник записи. Новая работа добавляет отдельные файлы, а не правки в общих корнях. Исключения узкие, явные и проходят как изменения архитектуры.
Пять правил архитектуры Dune: условия, при которых агенту проще сделать правильно
Пять правил архитектуры Dune: условия, при которых агенту проще сделать правильно

Защита работает слоями: кодовая база, статический анализ (линтеры, компилятор, CI), правила и ревью-бот, навыки, руководство по стилю. Жёсткие только первые два слоя. Остальные мягкие: агент может забыть правило или применить его непоследовательно. Если держать порядок только на них, код рано или поздно превратится в мусор. Поэтому, если вы повторяете одно и то же замечание в ревью, превратите его в правило линтера или ошибку CI.

Ещё одна деталь: агенты делят работу на небольшие PR, от 50 до 1000 строк, без жёсткого предела. История в Git остаётся осмысленной, а ошибку проще откатить, чем искать в PR на 40 тысяч строк.

Список PR: слитые небольшие изменения и два, где CI не прошёл
Список PR: слитые небольшие изменения и два, где CI не прошёл

Если вы работаете из России

Cursor и модели, на которых работает пример, это зарубежные облачные сервисы. Доступ к ним из России может быть нестабильным и зависит от оплаты, поэтому условия лучше проверить заранее.

Основа метода от сервиса не зависит. Навык это markdown. Управление приложением идёт через открытые Chrome DevTools Protocol и Playwright. Оценки, проверки в CI, запреты линтеров, карта функций и небольшие PR работают с любой моделью. В качестве самого агента можно взять открытых кодинг-агентов, например Hermes Agent или Pi, с открытыми моделями на своём сервере или компьютере. Подойдёт ли модель, покажут оценки.

Что важно знать до старта

  • Это стоит токенов. В примере у команды их неограниченно много. Рефакторинг кодовой базы и оценки на разных моделях съедают много. Решайте как руководитель: нанять человека на такую настройку или потратить токены.
  • Проверка не гарантирует хороший код. Она даёт код, который делает то, что нужно. Качество держат правила и CI.
  • Этапы пропускать нельзя. Автослияние ставят в конце пути, а не в начале.
  • Навыки надо поддерживать. Продукт меняется, и навыки устаревают. Помогают навык maintain verification и оценки, но нужен человек со вкусом.
  • Новые проекты рискованнее зрелых. В зрелом проекте с хорошей инфраструктурой ограничения уже есть. Новый без них быстро превращается в клубок.

Что дальше

Главное в этом подходе не плагин, а порядок. Сначала агент учится проверять себя, потом правила закрепляются там, где их нельзя обойти, и только потом число агентов растёт.

Мы в Агентехе учим сотрудников строить такие системы вокруг ИИ-агентов: давать им проверку, правила и границы, чтобы им можно было доверять в реальной работе. Как устроено обучение.

Написать в Telegram