В моём прошлом посте я показал, почему верификация — это основа всего, что я делаю с агентами, и как начать создавать собственные навыки верификации. Ключевой урок был таков: если агент не может проверить свою собственную работу, всё остальное не имеет значения. Вы остаётесь узким местом, и весь ваш день будет потрачен на присмотр за агентами.
https://x.com/poteto/status/2094457600259842065
Но как только верификация заработала, возникает следующий вопрос: как вообще понять, что строить?
https://x.ai/bot/plugin/9717366
В этом посте я проведу вас через то, как я провожу исследования, планирование, прототипирование и архитектуру с помощью pstack. Это тот самый рабочий процесс, который позволяет мне отправлять тысячи PR в месяц в продакшн, сохраняя при этом невероятно высокое качество кода.
Завершая август с 2 462 PR в продакшне
Искусство руководить тем, кто умнее тебя
В стародавние времена 2024 года, чтобы внести любое изменение в систему, нужно было сначала прочитать достаточно кода, чтобы сформировать мысленную модель происходящего. В зависимости от размера и сложности кодовой базы, это могло занять от нескольких часов до нескольких дней и даже месяцев. При небольшом изменении можно было обойтись локальным пониманием небольшой подсистемы. Однако, если вы рефакторили ядро, вам, вероятно, нужно было иметь мысленную модель всей системы, чтобы сделать рефакторинг правильно и эффективно.
Агенты, очевидно, устраняют этот барьер. Вы можете вносить изменения в системы очень легко, просто давая агенту указания, и он сделает это, независимо от того, сколько вы знаете о коде. Но поддерживать высокое качество кода и пользовательского опыта по-прежнему сложно, особенно если вы не являетесь экспертом в предметной области, который знает, на что обращать внимание и о чём спрашивать.
Несмотря на то, что前沿ные модели стали очень способными, я постоянно наблюдаю два типа сбоев:
- Они не могут полностью понять ваш замысел, потому что он недостаточно или плохо определён.
- У них недостаточно контекста о том, как правильно выполнить работу.
Обе эти проблемы связаны. Эффективное использование агентов сводится к тому, насколько хорошо вы можете наполнить контекстное окно агента высококачественным контекстом. Вы, безусловно, можете написать работающий код и без этого, но я обнаружил, что результаты и качество намного лучше, когда я проделал работу по предоставлению своим агентам всего необходимого для качественной работы.
Своими словами
前沿ные модели — очень способные программисты. В то время как со старыми моделями я мог давать очень конкретные указания, почти микроменеджмент, новейшие модели умеют писать код лучше, чем вы или я. Поэтому я стремлюсь найти тонкий баланс: сообщить агенту, чего я хочу достичь, предоставив ему свободу решать задачу способами, которые я, возможно, не рассматривал.
Это и есть искусство руководить тем, кто умнее тебя, работая с кодовой базой, которую ты сам не писал, и где люди больше не могут удерживать в голове полную мысленную модель кодовой базы.
Один из приёмов, который я люблю использовать, — это косвенная подсказка. Вместо того чтобы говорить агенту именно то, что я хочу, я пытаюсь вытянуть это из агента — его собственными словами.
Например, когда кто-то сообщает о проблеме в Slack, я часто прошу агента прочитать тред и переформулировать проблему своими словами, прежде чем делать что-либо ещё.
Например, я могу сказать:
/poteto-mode прочитай этот тред в Slack. переформулируй своими словами и простым языком, в чём, по твоему мнению, заключается основная проблема
Это позволяет достичь трёх целей:
Во-первых, это заставляет агента сжать шумный разговор в структурированную постановку проблемы. Во-вторых, это позволяет мне сразу же выявить недопонимание. Если агент зациклится на ложном следе в треде, я могу быстро его поправить, прежде чем он начнёт писать код.
И в-третьих, я не веду его потенциально по ложному пути, излагая свои собственные предположения и гипотезы, которые могут быть неверными или ограничивать то, чего агент мог бы в противном случае достичь.
Формирование мысленной модели
Просьба к агенту переформулировать что-то так, чтобы вы могли понять, — важная часть работы с тем, кто умнее вас. Это и было вдохновением для /teach — навыка, который помогает вашему агенту объяснять вам вещи интуитивно понятным способом. Я использую его всякий раз, когда мне нужно убедиться, что мой агент делает что-то, что имеет для меня смысл.
Под капотом /teach обращается к /how и /why.
/how отслеживает механику выполнения. Когда вы спрашиваете /how, агент оценивает сложность подсистемы. Если подсистема охватывает несколько каталогов или сервисов, он порождает параллельных агентов-исследователей на быстрых и эффективных моделях, таких как Grok.
/how реализована виртуализация?
/why исследует мотивацию и намерения. Код говорит вам, что происходит. Он редко говорит вам, почему кто-то написал его именно так. Когда вы запускаете /why, pstack параллельно запрашивает исторические свидетельства из нескольких источников: историю Git и комментарии к PR, тикеты Linear, дизайн-документы Notion, разговоры в Slack, мониторы Datadog, ошибки Sentry, происхождение кода и события из аналитического хранилища.
/why мы всё ещё застряли на старой версии Node.js?
Я использую /teach всякий раз, когда хочу, чтобы агент переформулировал что-то, чтобы я мог лучше понять и доверять его работе.
/teach меня, почему ты реализовал это так, а не <другим способом>. какие компромиссы ты сделал и почему?
На практике я также обнаружил, что исследование, проведённое навыком /teach, полезно не только людям, но и агентам. Даже с новейшими前沿ными моделями (это также зависит от качества обвязки), в целом я замечаю, что они всё ещё часто уверенно заявляют о чём-то, не подкрепляя это данными или фактическим чтением кода, необходимого для формирования мысленной модели того, как это работает. Таким образом, этот акт обучения вас тому, что он собирается сделать и почему, в конечном итоге помогает и самому агенту.
Учимся на истории
Многие мои проекты охватывают несколько разговоров. Например, несколько месяцев назад я работал над исправлением багов виртуализации и проблем с производительностью, о которых сообщали люди в Cursor. Я понял, что каждый раз, когда я начинал новый чат, мне приходилось по сути начинать с нуля, восстанавливая тот богатый контекст, который был у моего агента ранее, когда он решал похожую проблему.
Я понял, что ваши прошлые транскрипты часто являются золотой жилой для богатого контекста. pstack поставляется с навыком /recall, который извлекает ваш недавний контекст из истории чата, так что даже новые агенты получают правильный контекст, необходимый для возвращения в хорошее состояние.
/recall работу, которую я делал вчера по виртуализации, а затем прочитай этот отчёт об ошибке в Slack
Использование /teach, /recall, /how и /why — это то, как я поддерживаю свои собственные мысленные модели кодовой базы в актуальном состоянии, сжимая их в форму, которую я могу легко понять и запомнить. И это также помогает агентам!
Работа в обратном направлении
Как только вы поняли проблему, как определить решение?
На мой взгляд, большинство обвязок, имеющих режимы планирования, склонны переопределять детали реализации и недоопределять всё остальное. Вот почему в pstack я с хитринкой сказал, что "не верю в планирование". Правда в том, что я планирую, но делаю это через код.
Для определённых видов работы, например, создания общего кода или пакетов, которые будут использовать другие, я большой сторонник разработки через README. Если вы не знакомы с этим, это техника разработки, популярная в прошлом, когда вы начинаете с создания своего README в первую очередь. Это заставляет вас надеть шляпу разработчика, думая о пользовательском опыте: вы начинаете с описания API для гипотетического пользователя и работаете в обратном направлении к реализации и архитектуре.
Например, когда я создавал Dune, наш внутренний клиентский фреймворк для десктопных приложений, я начал с написания учебного пособия для него, чтобы понять, каково это — создавать с его помощью приложение. По крайней мере, я попытался. Это была настоящая борьба — заставить агента создать что-то хорошее или читаемое. Поэтому мне пришлось сначала потратить время на заточку своего инструмента, создав навык /technical-writing.
Первая версия README без навыка /technical-writing была мучительно читаема, потому что в ней смешивались разные цели. Она пыталась быть одновременно учебным пособием, практическим руководством, архитектурным объяснением и справочником по API в одном документе, написанном обычной AI-шелухой и манерной прозой.
/technical-writing использует фреймворк Diátaxis для разделения документации на четыре различных режима:
- Учебное пособие: Обучение через действие. Урок, который проводит новичка через серию шагов для создания чего-то видимого.
- Практическое руководство: Шаги для решения конкретной реальной проблемы для опытного пользователя.
- Справочник: Сухие, полные, авторитетные технические описания механизмов, API и флагов конфигурации.
- Объяснение: Обсуждение на высоком уровне, которое проясняет и освещает предысторию, дизайнерские решения и компромиссы.
Он также использует /unslop, поэтому создаёт очень читаемую документацию.
Написание плана таким образом очень полезно, потому что это также даёт вашим агентам конкретную цель и задачу, с которыми они могут сверять свою собственную работу. И, конечно, гораздо легче понять, что именно агент собирается построить.
Многие навыки pstack объединяются здесь, на этапе проектирования. Например:
(1) /recall мою работу по исправлению багов виртуализации и проблем с производительностью за последние 7 дней. используй /how и /why, чтобы понять, как работает наша текущая реализация виртуализации.
(2) затем используй /poteto-mode планирование и /technical-writing, чтобы придумать новый движок виртуализации, который категорически устранит мерцание и дрожание. давай начнём с написания учебного пособия о том, как я бы использовал этот новый пакет для виртуализации React-приложения
(3) после того, как напишешь план, /teach меня и докажи мне, почему этот новый подход превосходит наш текущий движок
Техника здесь заключается в том, чтобы извлечь интересный и богатый контекст, который даёт вашим агентам возможность видеть проблему так же, как и вы — не просто как маленький фрагмент:
- Первая часть подсказки извлекает соответствующий прошлый и настоящий контекст о том, как реализована виртуализация в моём приложении.
- Вторая часть направляет агента на использование этого контекста, например, багов, которые он исправлял ранее, чтобы придумать новый дизайн, полностью устраняющий эти проблемы.
- Последняя часть — попросить вашего агента доказать вам, что этот новый пакет превосходен. Вот где важны высококачественные инструменты, такие как навыки верификации.
Семь раз отмерь, один раз отрежь
При планировании две самые распространённые ошибки, которые я вижу, это:
- Принятие первого дизайна, предложенного агентом.
- Переваривание плана без эмпирических доказательств.
Когда люди писали код, мы часто сотрудничали друг с другом через дизайн-документы. Это были документы, в которых обсуждалась архитектура высокого уровня, рассмотренные альтернативы, компромиссы и любые необычные примечания по реализации. Было очень распространено пройти через несколько итераций этих документов, прежде чем остановиться на устоявшемся дизайне.
С агентами, хотя мы можем пропустить церемонию дизайн-документа, я часто вижу ошибку принятия первого же результата, который выдаёт агент. С pstack мы можем вместо этого довести подход «семь раз отмерь, один раз отрежь» до предела, используя параллельных агентов.
Мы делаем это с помощью плейбука прототипирования.
В pstack плейбуки — это не навыки, а справочные файлы внутри /poteto-mode. Эти плейбуки загружаются условно (для экономии токенов) в зависимости от типа задачи, над которой вы работаете. Эти 23 плейбука (по состоянию на версию 0.15.0) каждый содержат рабочий процесс, который я использую при выполнении задачи.
В отличие от навыков, плейбуки автоматически используются агентом как часть /poteto-mode. Например:
/poteto-mode создай прототипы нескольких вариантов для нового выпадающего меню /poteto-mode исправь этот баг /poteto-mode оцени это изменение навыка
Прототипирование — один из моих любимых плейбуков pstack. Он даёт множество попыток достижения цели и помогает агенту рассуждать о лучшем варианте. Это полезно не только для визуального прототипирования, но и для прототипирования различных решений для функций, исправления ошибок и так далее.
/poteto-mode создай прототипы нескольких вариантов для <запроса функции>. используй /control-app* и сделай видео/скриншоты для моего просмотра и выбора
\ примечание: /control-app — это навык верификации, который мы создали в [Части 1*](https://x.com/poteto/status/2094457600259842065
При прототипировании визуальных изменений агент создаёт одноразовые наброски в вашем приложении или в scratch-каталоге. Если он тестирует взаимодействие с UI, он помещает два или три варианта за простой переключатель. Затем он управляет взаимодействием с помощью навыка /control-app, делает скриншоты каждого варианта и измеряет фактическое время выполнения или расположение элементов.
Прототипирование — это планирование, но с помощью кода. Оно позволяет агентам свободно исследовать пространство проблемы и даёт им шанс удивить вас чем-то, о чём вы бы сами не подумали. Прототипы позволяют агентам отвечать на свои собственные вопросы с помощью эмпирических доказательств, вместо того чтобы ждать моего ввода.
Архитектура более крупных изменений
Как инженер в эпоху агентов, важнее тратить своё время на архитектуру, выбор правильных структур данных и размышления о том, как создаваемые мной системы будут работать вместе. Мои агенты заполняют детали реализации.
Ещё один полезный навык, который поставляется с pstack, — это /architect. Он структурирует дизайн в отдельные, дисциплинированные фазы:
- Обоснование проблемы. Агент запускает /how и /why для затронутых систем, чтобы построить точную мысленную модель существующей принадлежности и ограничений.
- Набросок. Агент входит на арену архитектуры. Он порождает независимых кандидатов параллельно, часто на разных семействах моделей. Каждый кандидат получает краткое описание проблемы и создаёт полный пакет дизайна: эскиз использования вызывающей стороны, основные определения типов, сигнатуры публичных функций и краткое обоснование. Обычно это делается путём наброска только сигнатур типов, которые вытекают из того, как мы хотим, чтобы выглядели места вызова. Каждый кандидат должен оценить глубину интерфейса, изучить режимы сбоев на слабых моделях и проверить на соответствие нашему каталогу красных флагов дизайна.
- Перекрёстная оценка и синтез. Агент перекрёстной оценки, использующий модель, отличную от основной, оценивает кандидатов по строгой рубрике.
- Реализация по наброску. Агент заменяет тела-заглушки наброска реальной логикой. Если в ходе реализации агент обнаруживает, что функции нужны неожиданные параметры или дополнительное состояние, он выявляет это несоответствие.
- Отказ от дизайна, если он неверен. Если в ходе реализации мы обнаруживаем, что наброски были неверны, агент выбрасывает всё и начинает заново.
Смысл здесь в том, чтобы дать агенту самодостаточный мини-цикл, в котором он может синтезировать несколько конкурирующих дизайнов от разных семейств моделей в один оптимальный подход, и быть тщательным, не боясь отказаться от своего дизайна, если окажется, что придуманная им архитектура неверна, основываясь на эмпирических доказательствах. Если одно и то же обходное решение появляется в несвязанных местах вызова, или если типы требуют аварийных люков, таких как 𝚊𝚗𝚢 или принудительные приведения, это эмпирическое доказательство того, что архитектура неверна.
/architect этот новый <запрос функции>
Большой урок здесь заключается в том, что гораздо эффективнее планировать с помощью кода, используя прототипирование /poteto-mode и /architect.
Вот почему я никогда не утруждаю себя оппонированием абстрактным планам. Агенты начинают галлюцинировать теоретические риски и выдумывать сложные крайние случаи, чтобы защититься от проблем, которые никогда не возникнут. Не переваривайте свои планы, когда они ещё абстрактны: позвольте агенту самостоятельно отвечать на открытые вопросы через прототипирование и проверку своей собственной работы.
Хорошо, но я действительно хочу документ с планом
Хотя pstack не поставляется с навыком планирования, он включает плейбук многофазного планирования. Обычно я использую его после того, как агент придумал дизайн, который меня устраивает, как способ создать тактический план выполнения.
/poteto-mode преврати этот дизайн в план
Каждая задача в плане структурирована вокруг доказательства и верификации. Плейбук говорит агентам, что одних тестов недостаточно для верификации. Она считается верифицированной только тогда, когда код был фактически запущен и проверен на работоспособность.
Каждый план проверяется автоматическим скриптом, который валидирует его структуру и форматирование. После утверждения план выполняется пункт за пунктом. Каждый PR невелик, самодостаточен и легко проверяется.
Для действительно больших проектов (например, таких, которые могут занять целую неделю) я иногда могу решить временно зафиксировать планы в кодовой базе, чтобы другие агенты знали о текущей работе. Но обычно я удаляю их по завершении, чтобы не оставлять кодовую базу в состоянии неразберихи. Я не считаю ценным постоянно хранить планы.
Рабочий процесс на практике
Чтобы увидеть, как все эти части сочетаются друг с другом, давайте рассмотрим три конкретных примера того, как я даю указания для этих рабочих процессов.
Пример 1: Исследование неоднозначного бага
Когда проблема появляется в продакшне, а первопричина неясна:
/poteto-mode расследуй, почему фоновые воркеры периодически падают с ошибками тайм-аута. предоставь разбивку того, что мы знаем, какие данные ты использовал и свои лучшие гипотезы.
Агент параллельно исследует код, проверяет метрики и исторические коммиты и выдаёт вам свои наилучшие обоснованные предположения о том, где может быть проблема.
Пример 2: Проектирование новой границы сервиса
При внедрении новой подсистемы, от которой будут зависеть другие модули:
/poteto-mode нам нужно добавить ограничение скорости для внешних вебхуков. сначала /architect это и ответь на любые открытые вопросы с помощью прототипов. дай мне просмотреть, прежде чем продолжить.
Агент обосновывает существующую архитектуру вебхуков, запускает конкурирующие потоки дизайна на нескольких моделях, проводит бенчмаркинг с одноразовыми прототипами и создаёт чистый, верифицированный интерфейс.
Пример 3: Выполнение миграции с несколькими PR
При выполнении сложного рефакторинга, затрагивающего множество файлов:
/poteto-mode создай план миграции всей нашей UI-библиотеки на StyleX. разбей миграцию на маленькие, проверяемые PR. каждый PR должен иметь свои тесты визуальных регрессий и шаги по проверке вживую. я хочу, чтобы конечный результат был на 100% идентичен оригиналу — включая баги
Агент разбивает работу на независимые шаги, пишет проверяемый контрольный список и подготавливает каждый блок так, чтобы его можно было безопасно собрать, проверить и запустить.
Пример 4: Исправление того, о чём сообщают люди в Slack
Если вы когда-нибудь видели меня в Slack в одном из наших каналов с проблемами или обратной связью, вы, вероятно, видели эти классические фразы:
# в треде уже достаточно контекста
/poteto-mode сделай это
/poteto-mode воспроизведи это с помощью /control-app. если это воспроизводится на main, исправь и покажи мне видео в качестве доказательства
Многие из навыков, о которых я здесь рассказал, уже автоматически используются /poteto-mode, поэтому в подавляющем большинстве случаев вы можете просто использовать /poteto-mode и жить своей жизнью!
Искусство планирования
Режим планирования часто используется как способ убедить себя, что агент собирается сделать всё правильно. Но реальность такова, что абстрактные планы дают вам лишь иллюзию прогресса. Длинный и подробный план создаёт впечатление, что вы и ваш агент были очень продуктивны, но, вероятно, ему не хватает содержательности.
pstack предоставляет вам инструменты для объединения тщательного исследования, эмпирических доказательств и строгой верификации. Когда вы планируете таким образом, разработка с агентами перестаёт быть игрой в рулетку. Она становится предсказуемой и повторяемой.
https://x.ai/bot/plugin/9717366
Спасибо за чтение, и следите за Частью 3!
