У моєму попередньому дописі я показав, чому верифікація є основою всього, що я роблю з агентами, і як почати створювати власні навички верифікації. Ключовий урок полягав у тому, що якщо агент не може перевірити власну роботу, все інше не має значення. Ви залишаєтеся вузьким місцем, і весь ваш день буде витрачено на догляд за агентами.
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
Під час прототипування візуальних змін агент створює одноразові начерки у вашому додатку або в тимчасовому каталозі. Якщо він тестує взаємодію з інтерфейсом, він розміщує два-три варіанти за простим перемикачем. Потім він керує взаємодією за допомогою навички /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!
