У спільноті AI-інженерів зараз точиться багато дискусій про те, як змусити кодових агентів коректно користуватися складними бібліотеками. Одні експериментують з довшими промптами, інші — з MCP-серверами й додатковою документацією. Інженер і співзасновник Effectful Майкл Арнальді пропонує радикально простіший підхід: перестати вмовляти модель читати документацію і просто дати їй сам код бібліотеки.
У воркшопі на каналі AI Engineer він демонструє це на прикладі Effect v4 — функціональної бібліотеки для TypeScript. Замість того щоб сподіватися, що модель «знає Effect» або вміє працювати з node_modules, Арнальді клонуює репозиторій Effect прямо в проєкт, документує для агентів, де шукати патерни, і будує навколо цього робочий процес. Результат — агент поводиться так, ніби бібліотека є частиною його «рідного» коду, і вчиться з неї так само, як з вашого застосунку.
Чому документація не рятує, а великий контекст може зашкодити
Ключ до підходу Арнальді — тверезий погляд на те, як насправді працюють сучасні LLM, орієнтовані на програмування.
Він нагадує: люди навчаються безперервно. Досвід перетворюється на довгострокову пам’ять, мозок відфільтровує шум, узагальнює патерни. З моделями інакше. Вони проходять три великі етапи: масове попереднє навчання на інтернеті, спеціалізацію на певних задачах і посттренінг. Для кодових моделей цей посттренінг включає проходи по кодових базах із підкріплювальним навчанням: система оцінює, чи компілюється код після змін, чи тести проходять, і коригує модель.
Після цього процес закінчено. Модель не продовжує вчитися від користувачів. Якщо сьогодні ви поясните їй «як правильно робити з Effect», завтра вона цього не згадає. Усе, що вона «пам’ятає» в межах сесії, — це вміст контекстного вікна, тобто масиву повідомлень фіксованого розміру, який щоразу подається в нейромережу.
На цьому тлі спокуса «вирішити все великим контекстом» виглядає логічною, але, за словами Арнальді, хибною. Навіть мільйон токенів не гарантують кращого результату. Навпаки, коли в одному контексті змішуються різні задачі, довгі логи, документація й код, модель легше заплутати. Вона намагається передбачити наступний токен на основі всього, що їй дали, і надлишок інформації часто знижує якість, а не підвищує її.
Звідси висновок: якщо модель не вчиться від сесій і погано масштабується з хаотично великим контекстом, то єдиний реалістичний шлях «дати їй нові знання» — це грамотно організувати той код, який вона бачить як свій робочий простір.
Моделі вміють читати код, а не документацію
Ще одна важлива теза Арнальді стосується того, на що взагалі натреновані кодові моделі. Попри популярні експерименти з MCP-серверами, зовнішніми базами знань і хитрими промптами, основна компетенція таких моделей — працювати з кодом у межах користувацького репозиторію.
Під час посттренінгу їх вчать:
- споживати й продукувати код;
- орієнтуватися в структурі проєкту;
- робити зміни в існуючій кодовій базі;
- наслідувати патерни, які вже є в цьому коді.
Натомість вони не оптимізовані на читання людської документації, не мають вбудованого досвіду роботи з конкретними MCP-серверами і не ставляться до node_modules як до першокласного джерела знань. Більше того, інструменти на кшталт Cursor свідомо не індексують файли, що потрапляють у .gitignore, а агенти загалом «привчені» ігнорувати те, що вважається службовим чи зовнішнім.
Це створює парадокс. Формально бібліотека є в node_modules, але з точки зору моделі вона — «чужа територія», до якої вона звертається рідко й неохоче. Документація, навіть якщо вона існує, — ще один окремий світ, який потрібно спеціально підсовувати в контекст, жертвуючи місцем для реального коду.
Арнальді формулює просту гіпотезу: якщо моделі найкраще працюють із власним кодом користувача, то чому б не замаскувати бібліотеку під частину цього коду?
«Просто клонуй репозиторій»: Effect як частина застосунку
Відповідь на це «чому б ні» виявилася настільки ефективною, що сам Арнальді жартує: сесію можна було б назвати «Just clone the repo and be done with it». Суть підходу — у прямому доступі агента до вихідного коду бібліотеки.
У своїх проєктах він дотримується чіткого патерну: клонувати репозиторій Effect у піддиректорію repos/effect всередині основного застосунку. З погляду Git це окремий код, але з погляду агента — просто ще одна частина робочої бази, яку можна читати, індексувати й використовувати як джерело патернів.
Мотивація тут подвійна.
По-перше, модель отримує «живий» приклад того, як автори бібліотеки самі її використовують. Для Effect це особливо важливо: бібліотека задає певний стиль безпечного, типізованого коду, який складно відтворити, спираючись лише на API-референс.
По-друге, це обхід усіх прихованих фільтрів і евристик, які змушують агентів ігнорувати node_modules чи git-ігноровані шляхи. Код Effect стає «своїм», а отже, потрапляє в основний фокус моделі.
Арнальді підкреслює, що цей трюк працює незалежно від мови. Він уже кілька місяців не пише код вручну — ні на TypeScript, ні на Rust — і значну частину часу працює саме з бібліотечним кодом, де документації мало або немає зовсім. Там, де MCP-сервери й надія на «модель, яка все знає», не спрацьовують, прямий доступ до вихідників виявляється єдиним стабільним рішенням.
agents.md: інструкція для машин, а не для людей
Самого факту наявності коду в репозиторії недостатньо. Щоб агент дійсно почав користуватися Effect як джерелом патернів, йому потрібно явно пояснити, що це дозволено й бажано. Для цього Арнальді вводить у проєкті спеціальний файл agents.md.
Це не чергова людська README, а радше маніфест для моделей. У ньому фіксуються:
- доступні команди проєкту;
- спеціальні правила роботи;
- перелік додаткових ресурсів, які агент має право й повинен використовувати.
Критичний фрагмент — явна вказівка, що в репозиторії є Effect за шляхом repos/effect, і що це джерело найкращих практик. Агенту прямо говорять: якщо потрібно зрозуміти, як будувати HTTP API, як працювати з SQL чи як організовувати ефекти, шукай приклади в цьому каталозі.
Тут же фіксуються й обмеження, покликані захистити агента від типових пасток. Наприклад, у agents.md Арнальді забороняє запускати команди в режимі watch — на кшталт bun test --watch чи дев-серверів. Для людини це зручно, але для агента, який працює в автоматичному циклі, такі процеси можуть стати «чорною дірою», з якої він не вибереться.
Таким чином, agents.md перетворюється на контракт між розробником і моделлю: тут описано, як поводитися в цьому конкретному репозиторії, які інструменти є, а які — табу, і де шукати знання, окрім основного коду застосунку.
Каталог patterns/: як змусити модель спершу вчитися, а потім писати
Ще один важливий елемент архітектури Арнальді — каталог patterns/. Якщо repos/effect — це «сирий» вихідний код бібліотеки, то patterns/ — це шар узагальнення, який сама модель створює для себе.
Робочий процес виглядає так. Спочатку агенту ставлять задачу не реалізувати фічу, а дослідити код Effect. Він проходиться по відповідних модулях, шукає, як там організовано HTTP API, як описуються SQL-операції, як будуються ефекти. На основі цього він пише стислі markdown-нотатки в patterns/, наприклад:
patterns/http-api.md— конспект того, як у Effect будуються HTTP-сервіси, які абстракції використовуються, як виглядають типові обробники;patterns/sql.md— опис того, як організовано роботу з Effect SQL, які патерни транзакцій, як описуються запити.
Ці файли не призначені для людей, хоча людина теж може їх прочитати. Їхня головна аудиторія — сама модель у наступних ітераціях. Коли пізніше агенту доручають реалізувати нову фічу — наприклад, ендпоінт для todo-списку з доступом до SQLite через Effect SQL, — він уже не змушений щоразу сканувати весь репозиторій бібліотеки. Замість цього він може спиратися на власні ж узагальнення в patterns/.
Це дає кілька переваг.
По-перше, зменшується навантаження на контекст. Замість того щоб підсовувати моделі десятки файлів із repos/effect, достатньо кількох стиснутих патернів.
По-друге, з’являється стабільний «локальний стильовий гайд», який модель сама для себе вивела з коду бібліотеки. Це підвищує послідовність рішень: нові частини застосунку краще узгоджуються з тим, як задумували автори Effect.
По-третє, такий підхід природно масштабується. Коли в проєкті з’являються нові домени — наприклад, черги, воркфлови чи кластери для бекграунд-операцій, — агент може повторити той самий цикл: дослідити відповідні частини repos/effect, написати новий patterns/*.md і вже з ним у руках братися до реалізації.
Від «магії LLM» до інженерії знань
Усе це разом — клонування репозиторію бібліотеки, agents.md як контракт, patterns/ як шар узагальнення — формує підхід, який можна описати як інженерію знань для кодових агентів.
Замість того щоб покладатися на «магію великої моделі», Арнальді виходить із припущення, що модель:
- має обмежене, стиснене й застаріле знання світу;
- не вчиться від ваших сесій;
- найкраще працює з кодом, який бачить як «свій»;
- погано масштабується з хаотично великим контекстом.
У такій реальності завдання розробника — не «навчити модель Effect», а побудувати для неї середовище, де вона сама зможе ефективно вчитися з вихідного коду бібліотеки, фіксувати ці знання в компактних патернах і застосовувати їх до конкретних задач.
Цікаво, що цей підхід народився не в «аплікейшн-ленді», де багато хто очікував найбільшої користі від LLM, а саме в «бібліотечному світі», де Арнальді працює з низькорівневим, складнотипізованим кодом без документації. Там, де людина витрачала б години на читання вихідників, модель, за умови правильної архітектури, може зробити ту саму роботу швидше й системніше.
Водночас він не ідеалізує моделі. Арнальді прямо говорить, що ставиться до них як до «тупої машини з великим потенціалом», яку потрібно правильно обмежити й спрямувати. Звідси й жорсткі налаштування типових діагностик у TypeScript, і заборона на watch-команди, і прагнення тримати контекстні вікна невеликими й сфокусованими.
Висновок: бібліотеки як перший клас громадян у світі AI-агентів
Підхід «просто клонувати репозиторій» може здатися грубим хаком у порівнянні з витонченими схемами RAG чи складними MCP-оркестраціями. Але в практиці Арнальді він виявився єдиним стабільним способом змусити кодових агентів дійсно опанувати бібліотеку, а не імітувати знання.
Ключові елементи цієї стратегії:
- трактувати вихідний код бібліотеки як частину власного застосунку, а не як зовнішню залежність;
- явно документувати для агентів, де шукати патерни й як із ними працювати;
- змусити модель спочатку дослідити бібліотеку й сформувати узагальнені патерни в
patterns/, а вже потім реалізовувати фічі на їхній основі.
У світі, де моделі не вчаться від ваших сесій і не здатні вмістити «весь інтернет» у свої параметри, саме така локальна, кодоцентрична інженерія знань може стати головним інструментом для тих, хто будує серйозні системи з участю AI-агентів. І, схоже, для цього справді інколи достатньо просто клонувати репозиторій.
Джерело
YouTube: Vibe Engineering Effect Apps — Michael Arnaldi, Effectful