Перейти до основного вмісту

Агентна інженерія — контрольний список впровадження

Зміст​

  1. Налаштуйте файл правил
  2. Спроєктуйте контекст
  3. Побудуйте верифікацію
  4. Виконуйте роботу
  5. Рев'ю та випуск
  6. Контролюйте вартість
  7. Виводьте агентів у продакшн
  8. Зробіть це командним стандартом

1. Налаштуйте файл правил​

  • Створіть CLAUDE.md / AGENTS.md у корені репозиторію. Почніть із 10 рядків.
  • Охопіть чотири аспекти:
    • Стек і версії
    • Конвенції (структура папок, іменування, патерни, які ви реально використовуєте)
    • Жорсткі правила, які агент не повинен порушувати ніколи (заборонені пакети, робота з секретами, шарування)
    • Робочий процес, якого слід дотримуватися перед генерацією коду
  • Додавайте нове правило щоразу, коли агент робить те, що ви не хочете повторювати.
  • Перелічте інструменти, які агент може викликати, і коли їх використовувати (API, скрипти, схеми БД).
  • Приймайте архітектурні рішення самостійно; дозволяйте агенту їх реалізовувати, а не обирати.

2. Спроєктуйте контекст​

  • Визначте, що є статичним (завжди завантажується) і що динамічним (завантажується за потребою):
    • Статичне: файли правил, системні інструкції, глобальна пам'ять
    • Динамічне: навички, результати інструментів, отримані документи, нещодавня історія
  • Тримайте статичний контекст коротким і щільним. Видаляйте все, що агенту не потрібно в кожному виклику.
  • Переносьте повторювані знання в навички, які завантажуються лише коли завдання відповідає їм.
  • Ніколи не вставляйте весь репозиторій у промпт. Отримуйте лише те, що релевантно.

3. Побудуйте верифікацію​

  • Пишіть тести до того, як генерувати функціональність. Тести — це специфікація.
  • Пишіть евали для недетермінованих частин:
    • Чи пройшов агент розумним шляхом?
    • Чи вибрав він правильні інструменти?
    • Чи відповідає результат планці якості?
  • Перевіряйте як результат (компілюється, тести проходять), так і траєкторію (як він туди дістався).
  • Налаштуйте цикл зворотного зв'язку:
    • Запускайте проти набору бенчмарків
    • Кластеризуйте збої за першопричиною
    • Виправляйте промпт або інструмент, що їх спричинив
    • Повторно запускайте регресійний набір
    • Відстежуйте нові збої в продакшні

4. Виконуйте роботу​

  • Обирайте режим для кожного завдання:
    • Диригент (в реальному часі, в IDE) для складної логіки, налагодження, незнайомого коду
    • Оркестратор (асинхронно, делегуйте й перевіряйте) для виправлення помилок, міграцій, генерації тестів
  • Обирайте місце агента для кожного завдання:
    • Агент у редакторі — редагування та пропозиції в потоці роботи
    • Агент у терміналі — робота з кількома файлами, запуск і реакція
    • Фоновий агент — завдання, описані в абзаці, від яких можна відійти
  • Запускайте генерацію коду всередині пісочниці з використанням лише затверджених інструментів.
  • Беріть останні 20% на себе: крайні випадки, обробка помилок, точки інтеграції, бізнес-логіка. Саме в коді, який «виглядає правильно», ховаються баги.

5. Рев'ю та випуск​

  • Використовуйте агента як рецензента першого проходу (баги, стиль, безпека, продуктивність).
  • Переглядайте кожен рядок, який іде в продакшн:
    • Ставтеся скептично до хитромудрого коду
    • Перевіряйте, що імпортовані пакети реально існують
    • Перевіряйте обробку помилок для реальних збоїв
  • Додавайте хуки в точках коміту/редагування (наприклад, блокуйте коміти з жорстко закодованими секретами).
  • Увімкніть спостережуваність: трейси, результати евалів, токени/затримки/вартість, дрейф.
  • Направляйте агента на легасі-код, якого ви уникали: рефакторинг, міграції, застарілі API.

6. Контролюйте вартість​

  • Вимірюйте сукупну вартість володіння, а не лише швидкість.
  • Підвищуйте успішність першого проходу за допомогою щільного файлу правил, щоб уникнути циклів повторних спроб.
  • Маршрутизуйте моделі за завданням:
    • Фронтирні моделі для архітектури та складної реалізації
    • Дешеві моделі для генерації тестів, рев'ю, моніторингу CI
  • Використовуйте динамічний контекст і навички, щоб платити лише за потрібні токени.

7. Виводьте агентів у продакшн​

  • Визначте, що саме ви будуєте:
    • Скрипт — агент є кінцевою точкою
    • Продукт для реальних користувачів — агенту потрібна інфраструктура
  • Для продуктів додайте: постійну пам'ять, обмежені дозволи, покриття евалами в CI, трасування повних запусків.
  • Використовуйте пакет навичок, щоб ваш наявний агент-кодер міг будувати → оцінювати → розгортати → спостерігати.
  • Для мультиагентних налаштувань координуйтеся через спільний стан, MCP для інструментів, A2A для делегування.

8. Зробіть це командним стандартом​

  • Версіонуйте файли правил, промпти, набори евалів і навички. Переглядайте їх у PR. Призначайте власників.
  • Ставте умовою випуску проходження набору евалів із чітким рубриком, а не лише працюючу демо.
  • Навчайте рецензентів того, як генерований код дає збої.
  • Чітко визначайте межу між прототипом і продакшном (репозиторії, гілки, середовища).
  • Побудуйте харнес один раз і постійно його вдосконалюйте.
  • Наймайте та просувайте тих, хто здатний приймати рішення: специфікація, оцінювання, архітектура.

Джерело​

На основі The New SDLC With Vibe Coding (Google): https://www.kaggle.com/whitepaper-the-new-SDLC-with-vibe-coding