Інженер PostHog Даніло Кампос відповідає за PostHog Wizard — автономного агента, який генерує інтеграції PostHog у реальні проєкти. Щомісяця цей «чарівник» запускається близько 15 тисяч разів і за кілька хвилин робить те, що зазвичай забирає години ручної роботи. Але за цією «магією» стоїть дуже приземлена інженерія: боротьба з «model rot», обмеження імпровізації моделі, зворотний зв’язок від самого агента та сувора безпека довкола середовищ виконання.
Цей матеріал розбирає конкретні тактики, які PostHog застосовує, щоб LLM‑кодогенерація не перетворювалася на хаос: від ін’єкції свіжої документації до спеціальних інструментів для роботи з .env без витоку секретів.
Свіжі markdown‑доки проти «model rot»: коли модель не знає, що світ змінився
Базова проблема будь‑якої великої мовної моделі — вона зафіксована в часі. Навчання моделі — це не «вихідні заради експерименту», а капіталомісткий процес, тому оновлюються вони не щодня. Для швидкорухомих софтверних продуктів це означає одне: модель не в курсі останніх змін API, SDK чи патернів інтеграції.
PostHog зіткнувся з цим напряму. Користувачі просили своїх ранніх агентів на кшталт Cursor «інтегрувати PostHog», і ті вигадували ключі, неіснуючі ендпоінти та фантазійні API. Формально це виглядало як інтеграція, але на практиці — як зламаний телефон.
Щоб обійти «model rot», команда зробила ставку на максимально просту, але потужну ідею: замість покладатися на застарілі знання моделі, вони «заливають» в контекст свіжу документацію у вигляді markdown‑файлів з posthog.com.
Wizard побудований навколо текстових інструкцій: приблизно 90% його коду — це markdown, ще близько 8% — інструменти для доставки й обробки цього markdown, і лише невеликий залишок — власне «обв’язка» агента. Така структура не випадкова. Новіші моделі вміють дедалі краще витягувати користь із тієї ж самої прозової інструкції, тож інвестиція в якісний текст окупається з часом без переписування логіки.
Ключовий момент — агент сам обирає, які саме документи йому потрібні. Wizard запитує: що це за проєкт, який фреймворк і мову виявлено, що саме інтегрується? На основі цього агент через інструменти отримує доступ до меню markdown‑доків, специфічних для потрібної мови та фреймворку, і підтягує їх у контекст лише тоді, коли це справді потрібно.
Замість універсальної, але розмитої «пам’яті» моделі, агент працює з актуальним, вузько сфокусованим знанням. Це знімає більшу частину ризиків, пов’язаних із тим, що LLM «не знає, що світ змінився», і дає змогу отримувати інтеграції, які відповідають поточному стану продукту.
«Модельні літачки»: як прикладні проєкти задають правильну форму інтеграції
Навіть із актуальною документацією LLM може будувати дивні архітектури. Моделі тренувалися на проєктах дуже різної якості, і їхні уявлення про «нормальну» інтеграцію часто далекі від того, що хоче бачити продуктова команда.
Щоб не дозволити агенту вигадувати довільні схеми, PostHog підтримує флот так званих «model airplanes» — невеликих демонстраційних проєктів із вбудованою інтеграцією PostHog у різних мовах і фреймворках. Це не повноцінні продакшн‑додатки, а тонкі, спрощені симулякри реальних застосунків.
У цих «літачках» навмисно відсутні багато продакшн‑аспектів. Наприклад, аутентифікація може бути зроблена так, що будь‑який пароль працює. Важливо не те, наскільки реалістичний застосунок, а те, що його структура «правильної форми»: точки логіну, ідентифікації користувача, ключові бізнес‑події — усе розміщено саме так, як команда PostHog вважає коректним для інтеграції аналітики.
Wizard надає агенту код цих модельних проєктів як зразок. Модель може буквально зіставляти побачене в реальному коді користувача з патернами з «літачка»: ось де в демо‑проєкті ставиться трекінг логіну, ось як оформлюється ідентифікація, ось як називаються події. Далі агент переносить цю форму в живий проєкт, підлаштовуючись під конкретний стек.
Такий підхід вирішує одразу кілька проблем. По‑перше, він зменшує простір для дивних архітектурних рішень: модель не вигадує з нуля, а доповнює вже заданий патерн. По‑друге, це економить токени: замість тягнути в контекст величезний продакшн‑код, достатньо тонкого, але показового прикладу. По‑третє, це радикально знижує різноманіття інтеграцій у полі — підтримці не доводиться розбиратися з тисячами унікальних схем, які агент міг би «винайти», якби його не обмежували.
Крихти завдань замість великого плану: як обмежити імпровізацію агента
Якщо дати LLM‑агенту повний план інтеграції наперед, він часто намагається «перестрибнути» через кроки, заповнюючи прогалини власною уявою. У масштабі 15 тисяч інтеграцій на місяць це загрожує тим, що агент знайде 15 тисяч різних шляхів до однієї й тієї ж мети — і жоден із них не буде стандартним.
Щоб цього уникнути, PostHog застосовує стратегію breadcrumbing — «розсипання крихт». Агенту ніколи не показують повний сценарій одразу. Навпаки, його ведуть через послідовність дрібних, чітко окреслених завдань, які не дають можливості «пробити діру» до фіналу за один стрибок.
Перший крок взагалі майже не згадує PostHog. Wizard просить агента знайти файли з «бізнес‑цінністю»: місця, де відбувається логін, взаємодія зі Stripe, логіка, пов’язана з відтоком користувачів. Бізнес‑події зазвичай відкидають великий «тіньовий слід» у коді, тож агент досить надійно знаходить ці ділянки.
Далі йде ще один обмежувальний крок: агенту заборонено писати код. Замість цього його просять перелічити «цікаві події» в знайдених файлах і описати їх. Які дії користувача тут відбуваються? Що могло б бути корисним для аналітики? Результат — список подій із назвами та описами, який зберігається в окремому файлі.
Лише після цього Wizard «відкриває» наступну крихту: тепер, маючи перелік подій і розуміння бізнес‑контексту, можна почати впроваджувати інтеграцію PostHog. На цьому етапі агент отримує доступ до відповідної документації — знову ж таки, специфічної для мови та фреймворку — і на її основі вставляє трекінг‑код у потрібні місця.
Такий поетапний сценарій дає кілька переваг. Агент змушений спочатку осмислити бізнес‑події, а не просто «розкидати» виклики SDK навмання. Він не може перескочити через кроки, бо кожен наступний залежить від результатів попереднього. А команда PostHog отримує інтеграції, які не лише технічно коректні, а й відповідають реальній цінності для продукту.
Коли головна загроза — не модель, а люди: опитування агента на стоп‑хуку
Навіть найакуратніше спроєктований агент страждатиме від людських помилок. Інженери змінюють інструкції, додають нові інструменти, забувають про старі обмеження — і в якийсь момент система починає суперечити сама собі.
У PostHog це проявилося у вигляді проблем із MCP‑інструментами. Виявилося, що деякі інструкції до інструментів суперечать одна одній, а інші посилаються на тул, якого взагалі не існує. Агент доходив до кроку, де мав обов’язково викликати певний інструмент, а MCP‑шар відповідав: такого інструменту немає. Сотні прогонів проходили з цією прихованою помилкою.
Щоб виявляти такі ситуації системно, команда запровадила простий, але ефективний механізм: inference‑time опитування агента на стоп‑хуку кожного запуску. Коли агент завершує роботу, система ставить йому одне запитання: що ми могли зробити краще, щоб підготувати тебе до успішного виконання цього завдання?
Це свого роду «юзер‑ресерч», де користувачем виступає сам робот. Відповіді виявилися надзвичайно корисними. Саме так PostHog дізнався, що агенту не вистачає дозволів на певні інструменти, що деякі директиви суперечать одна одній, а інколи й те, що йому дають інструкції для JavaScript, коли він працює в Python‑проєкті.
Без цього опитування команда могла б довго не помічати, що агент постійно опиняється в «неможливих» ситуаціях. Моделі рідко «скаржаться» самі по собі — вони просто намагаються якось завершити завдання. Запитавши їх прямо, PostHog перетворив агента на джерело структурованого фідбеку про власну інфраструктуру.
Цей підхід підкреслює важливу зміну ролей: у складних агентних системах головним джерелом збоїв часто стають не моделі, а люди, які їх обгортають. Інструменти, дозволи, інструкції — усе це розвивається фрагментарно, і без постійного «допиту» агента важко побачити, де саме система почала суперечити сама собі.
Безпечна робота з .env: спеціальний інструмент замість повного доступу
Окремий клас ризиків виникає тоді, коли агент запускається на чужій машині. Теоретично він може зробити що завгодно з локальними файлами, включно з читанням секретів і відправкою їх у хмару разом із контекстом для інференсу. Для продукту, який позиціонує себе як безпечний інструмент інтеграції, це неприйнятно.
На ранніх етапах розвитку Wizard мав можливість читати .env‑файли напряму. Це було зручно: щоб щось записати, агенту потрібно розуміти поточний вміст файлу. Але це також означало, що вміст середовища міг опинитися в логах хмарного провайдера LLM — із усіма API‑ключами та секретами.
У PostHog вирішили радикально обмежити цей вектор. Завдяки тонкому контролю над інструментами агенту можна дозволити лише ті операції, які справді потрібні. Для роботи з .env команда створила спеціальний тул із двома жорстко обмеженими можливостями: перевірити наявність ключа та записати значення за ключем. Жодного читання повного файлу, жодної відправки його вмісту в модель.
Цей інструмент працює як «проксі» між агентом і середовищем. Модель може запитати: «чи існує змінна POSTHOG_API_KEY?» або «запиши ось це значення в POSTHOG_PROJECT_ID», але ніколи не побачить повний список змінних чи їхні значення. Вміст .env не потрапляє в контекст інференсу, а отже, не може опинитися в логах чи бути використаним моделлю для будь‑яких інших цілей.
Цей приклад показує, як важливо проєктувати інструменти з принципом мінімальних привілеїв. Навіть якщо агент формально «вирішує задачу», спосіб, яким він це робить, може поставити під загрозу довіру користувачів. Обмеживши доступ до чутливих файлів і надавши вузькоспеціалізований інструмент, PostHog зберіг функціональність, але прибрав головний ризик.
Висновок: надійна LLM‑кодогенерація — це інженерія, а не магія
Досвід PostHog із Wizard показує, що успішна автономна кодогенерація — це не про «розумніші моделі», а про правильну інженерію навколо них. Свіжа markdown‑документація в контексті компенсує «model rot» і дозволяє моделі працювати з актуальними знаннями. «Модельні літачки» задають правильну форму інтеграції, з якої агент може зчитувати патерни. Breadcrumbing обмежує імпровізацію й змушує модель спочатку осмислити бізнес‑події, а вже потім писати код. Inference‑time опитування агента допомагає виявляти людські помилки в інструкціях і конфігурації інструментів. А спеціальний тул для .env показує, як можна поєднати зручність і безпеку без компромісів.
У сумі ці практики перетворюють LLM‑агента з непередбачуваного «робота‑чаклуна» на керований інструмент, здатний стабільно генерувати інтеграції, які користувачі не просто приймають, а й цінують. І головний урок тут у тому, що надійність не виникає сама собою — її доводиться ретельно проєктувати на кожному рівні системи.
Джерело
LLM codegen fails and how to stop ’em — Danilo Campos, PostHog