Інженер Даніло Кампос працює в PostHog і відповідає за PostHog Wizard — інструмент, який автоматизує інтеграцію аналітики PostHog у проєкти розробників. За його словами, близько 15 тисяч людей щомісяця запускають цей «чарівник», щоб замінити приблизно дві години рутинної ручної роботи на вісім хвилин напівавтоматизованого процесу. Попри те, що всередині це повноцінний агент на базі LLM, архітектура Wizard виглядає зовсім не як складна система з десятків сервісів. Вона радше нагадує добре організований набір текстових інструкцій.
Цей матеріал розбирає, як влаштований PostHog Wizard, чому він майже повністю побудований на markdown-документах, як працює контекстна стратегія зі «skill-файлами» та «модельними літачками» (model airplanes), і чому ставка на простий текст виявляється виграшною в епоху швидкого прогресу LLM.
Markdown як ядро: чому 90% системи — це просто текст
Якщо дивитися на PostHog Wizard як на програмний продукт, його структура нетипова для інструмента, який щомісяця генерує інтеграції для тисяч проєктів. Кампос описує її як систему, де приблизно 90% — це markdown-файли, ще близько 8% — інструменти для доставки й обробки цього markdown, а решта — тонкий «harness» для агента, який з’єднує все разом.
Фактично Wizard — це не стільки «кодова база», скільки ретельно написаний корпус інструкцій у звичайному тексті. Саме ці інструкції визначають, що агент робить із проєктом користувача, як він шукає важливі файли, які події варто відстежувати й як правильно вставляти виклики PostHog.
Ключова ідея полягає в тому, що сучасні LLM дедалі краще «витискають» користь із одного й того самого тексту. PostHog свідомо робить ставку на plain-text-прозу: замість того, щоб постійно ускладнювати кодову логіку агента, компанія вкладається в якість і структуру текстових інструкцій. Коли з’являється нова, потужніша модель, вона просто краще інтерпретує вже наявний текст — і система покращується без змін у коді.
Це радикально відрізняється від традиційного підходу до інженерії, де поліпшення якості зазвичай означає додавання нових гілок логіки, умов, конфігурацій. У випадку Wizard основний «важіль» розвитку — це документація, а не програмний код.
Як Wizard бореться з «model rot»: свіжа документація як контекст
Одна з базових проблем будь-якого LLM-агента — «model rot». Моделі тренуються на знімку світу, який швидко застаріває, особливо для швидкорухомих софтверних продуктів. PostHog постійно змінюється: API, SDK, найкращі практики інтеграції — усе це оновлюється значно частіше, ніж виходять нові версії великих моделей.
Щоб компенсувати це відставання, Wizard агресивно підживлює модель свіжим контекстом у вигляді markdown-документації з posthog.com. Замість того, щоб покладатися на те, що модель «колись читала» про PostHog під час тренування, система під час кожного запуску підтягує актуальні інструкції.
Механіка побудована навколо інструментів, які дозволяють агенту самостійно обирати потрібні документи. Wizard спочатку визначає, що саме інтегрується — які фреймворки й мови використовує проєкт. Після цього агент отримує можливість викликати спеціальні «markdown-інструменти» й завантажувати у свій контекст відповідні фрагменти документації: наприклад, інструкції для React, Next.js, Django чи іншого середовища.
Завдяки великим контекстним вікнам сучасних моделей PostHog може буквально «заштовхувати» в промпт великі шматки тексту й таким чином латати прогалини в знаннях моделі. Це простіше й надійніше, ніж будувати складні retrieval-системи, принаймні для задачі інтеграції аналітики.
Результат — агент працює не з застарілою уявою про PostHog, а з поточними, «гарячими» інструкціями. Це критично важливо, якщо згадати, з чого все починалося: користувачі просили ранні інструменти на кшталт Cursor інтегрувати PostHog, і ті вигадували ключі, API та патерни, яких ніколи не існувало. Wizard фактично став відповіддю на цю хвилю невдалих інтеграцій.
«Модельні літачки»: як приклади коду задають правильну форму інтеграції
Одна лише документація не вирішує іншої проблеми LLM-кодогенерації: дивної архітектури. Моделі тренувалися на величезній кількості відкритих репозиторіїв, і далеко не всі з них були зразком інженерної культури. У результаті агент може зібрати інтеграцію, яка формально працює, але виглядає дивно, важко підтримується й не відповідає очікуванням команди продукту.
Щоб задати агенту «правильну форму» інтеграції, PostHog підтримує флот так званих model airplanes — невеликих прикладних проєктів із вбудованою інтеграцією PostHog. Вони покривають різні фреймворки та мови, але принципово не є повноцінними продакшн-додатками. Це тонкі, спрощені симулякри реальних застосунків.
У цих «літачках» може бути, наприклад, фейкова аутентифікація: будь-який пароль проходить, але структура коду нагадує справжню систему логіну. Важливо не те, щоб застосунок був реалістичним з точки зору бізнес-логіки, а те, щоб він демонстрував правильне місце й спосіб вставки подій PostHog.
Ці проєкти виконують одразу кілька ролей.
По-перше, вони слугують зразком для патерн-матчингу. Агент отримує доступ до коду з model airplanes і може зіставляти його з проєктом користувача: де в реальному коді є аналогічні місця, куди в прикладі вставлено виклики PostHog. Це дозволяє відтворювати інтеграцію не як абстрактну інструкцію, а як конкретний, перевірений шаблон.
По-друге, вони економлять токени. Повноцінний продакшн-додаток із десятками модулів і складною бізнес-логікою був би надто важким для регулярного завантаження в контекст. Спрощений «літачок» дає ту саму форму інтеграції, але в компактному вигляді.
По-третє, вони стандартизують результат. Якщо агент щоразу вигадував би новий спосіб підключити PostHog, команда підтримки стикнулася б із хаосом із тисяч унікальних конфігурацій. Model airplanes задають вузький коридор допустимих рішень: інтеграції різних користувачів виглядають подібно, що спрощує діагностику та супровід.
Контекстна служба та skill-файли: як зшиваються документація й приклади
Щоб усі ці текстові інструкції й прикладні проєкти працювали як єдина система, PostHog використовує окрему контекстну службу. Її завдання — зібрати розрізнені джерела знань у форму, з якою агент може ефективно працювати під час одного запуску Wizard.
Ця служба генерує так звані skill-файли — структуровані markdown-документи, які описують конкретні «вміння» агента. Наприклад, інтеграція PostHog у React-додаток або налаштування подій у бекенді на Python. У кожному такому файлі поєднуються кілька типів контенту.
Перший — це власне документаційна проза: пояснення, кроки, зауваження, які зазвичай живуть на сайті документації. Вони дають моделі семантичне розуміння того, що саме потрібно зробити, які обмеження врахувати, які параметри важливі.
Другий — це код із model airplanes. Контекстна служба «сплющує» всі модельні проєкти в один великий markdown-файл, який потім референсується з кожного skill-файла. Таким чином агент завжди має під рукою не лише текстові інструкції, а й конкретні фрагменти коду для різних фреймворків і мов.
Третій — це допоміжні пояснення, які зв’язують документацію й приклади. Вони підказують моделі, як саме використовувати код із «літачків» у реальному проєкті, на що звернути увагу, які частини є обов’язковими, а які можуть змінюватися.
Завдяки такій організації контексту Wizard не покладається на одну-дві великі підказки. Замість цього агент працює з набором «навичок», кожна з яких має власний, ретельно зібраний контекст. Це зменшує ризик того, що модель «загубиться» в надто загальному описі задачі й почне імпровізувати.
Як Wizard працює для розробника: один CLI-запуск поверх агентної платформи
З точки зору користувача PostHog Wizard виглядає максимально просто: це CLI-інструмент, який запускається однією командою в корені проєкту. Усередині ж він обгортає Claude Agent SDK — агентну платформу від Anthropic, яка забезпечує планування кроків, виклик інструментів і роботу з контекстом.
CLI-шар виконує роль зручного інтерфейсу між локальним середовищем розробника й хмарним агентом. Він знає, де знаходяться файли проєкту, як їх читати й змінювати, як передавати потрібні фрагменти коду в контекст моделі й як застосовувати згенеровані зміни назад до репозиторію.
Над цим шаром працює власне агент, який керується markdown-інструкціями й skill-файлами. Він поетапно виконує завдання: спочатку шукає файли з бізнес-цінністю (логін, платежі, потенційні точки відтоку користувачів), потім формує список подій, які варто відстежувати, а вже після цього, спираючись на документацію й код із model airplanes, вставляє виклики PostHog у відповідні місця.
Завдяки тому, що більшість логіки описана в тексті, а не зашита в код CLI чи SDK, Wizard залишається гнучким. Оновлення документації, додавання нових «літачків» або зміна структури skill-файлів дозволяють змінювати поведінку агента без втручання в інфраструктурний код. Це важливо для продукту, який обслуговує близько 15 тисяч запусків щомісяця: будь-яка помилка в низькорівневій логіці могла б масштабуватися миттєво.
Чому ставка на текст працює краще, ніж складний код
Архітектура PostHog Wizard виглядає майже парадоксальною для традиційного інженера: замість того, щоб писати дедалі розумніший код, команда свідомо робить систему «плоскою» й текстоцентричною. Але в контексті LLM це виявляється раціональною стратегією.
По-перше, текст — це те, що моделі вміють інтерпретувати найкраще. Кожне нове покоління LLM краще розуміє інструкції, тонкі нюанси формулювань, контекстні підказки. Якщо ядро системи — це проза, то з виходом нової моделі вона автоматично стає «розумнішою», не вимагаючи переписування логіки.
По-друге, текст легше підтримувати. Оновити інструкцію в markdown-файлі простіше, ніж змінювати код агента, тестувати нові гілки логіки й уникати регресій. Для продукту, який живе в тісному зв’язку з документацією, це особливо важливо: зміни в API чи SDK можна відобразити одночасно і в публічній документації, і в контексті Wizard.
По-третє, текст прозоріший. Розробники PostHog можуть читати ті самі інструкції, які читає модель, і розуміти, чому агент поводиться саме так. Це знижує «магічність» системи й полегшує діагностику проблем: якщо інтеграція поводиться дивно, часто достатньо подивитися на відповідний skill-файл або фрагмент документації.
Нарешті, текст добре масштабується через приклади. Model airplanes — це теж, по суті, текст, просто у вигляді коду. Вони дозволяють навчити агента не лише «що робити», а й «як це має виглядати», не вдаючись до складних правил чи AST-перетворень.
Висновок: інтеграція як редакторська задача
PostHog Wizard показує, що побудова надійного LLM-агента для коду — це не обов’язково про складні алгоритми планування чи хитромудрі пайплайни. У випадку інтеграції аналітики ключовою виявляється редакторська робота: написання чітких інструкцій, підтримка актуальної документації, створення хороших прикладів коду й організація всього цього в керований контекст.
Те, що близько 15 тисяч розробників щомісяця запускають Wizard і отримують робочі інтеграції за лічені хвилини, свідчить: ставка на markdown, «модельні літачки» та контекстні «навички» може бути не менш потужною, ніж складні інженерні надбудови. У світі, де моделі швидко еволюціонують, така текстоцентрична архітектура дає ще одну перевагу — вона старіє повільніше, ніж код, і автоматично виграє від кожного нового покоління LLM.
Джерело
LLM codegen fails and how to stop ’em — Danilo Campos, PostHog