Хендбук по Agentic Engineering

Вы поручили агенту добавить отчёт для врача. Он изменил код, написал тесты и сообщил, что всё готово. На ревью выяснилось: тесты проверяют средний балл, но не проверяют, попадает ли в отчёт телефон из заметки пациента. Теперь нужно разобраться и с кодом, и с тем, почему задача прошла проверку.

В этом хендбуке мы будем разбирать такие ситуации. Как описать задачу до запуска агента, что дать ему прочитать, как ограничить доступ и по каким проверкам принимать результат. Затем соберём небольшой harness: программу, которая запускает работу и проверяет её результат.

Материал рассчитан на разработчиков и технических руководителей, которые уже пользуются агентами и отвечают за изменения в общем репозитории. Для практики понадобятся Git, Python и умение читать тесты. Подробности есть на странице «Перед чтением».

Что получится в команде

Возьмём ту же задачу с отчётом. До начала работы в ней записаны состав отчёта, ограничения на данные и примеры для проверки. Агент получает нужные файлы и отдельную рабочую копию. После запуска остаются изменения, результаты тестов и журнал команд. На ревью разработчик проверяет спорные места: например, достаточно ли выбранного способа удаления личных данных. Решение о выпуске остаётся за назначенным владельцем.

На небольшом проекте для этого хватит задачи в трекере, файла правил, скрипта запуска и существующего CI. Отдельная платформа понадобится, когда появятся задачи, которые этот набор уже не обслуживает: очередь, параллельные запуски, управление доступами нескольких команд.

Оглавление

Глава	О чём пойдёт речь
1. Agentic Engineering	Кто задаёт работу, кто её выполняет и кто принимает результат.
2. Спецификация поведения	Как описать функцию так, чтобы из описания можно было получить тест.
3. Постановка задачи	Как ограничить одно изменение и определить условия остановки.
4. Инструкции проекта	Где хранить правила и что делать, если они противоречат друг другу.
5. Подготовка контекста	Какие материалы нужны агенту для конкретной задачи.
6. Память проекта	Какие решения сохранять между запусками и как их обновлять.
7. Первый harness	Разбор ручного runner и сборка следующей версии.
8. Доступ к инструментам	Проверка команд и путей перед выполнением.
9. Безопасность агентов	Инструкции в чужих данных, изоляция процессов и утечки через инструменты.
10. Проверка результата	Как найти ошибку, которую пропускают зелёные тесты.
11. Журнал запуска	Что произошло, где остановилась работа и чего не хватает в логах.
12. Проверка самого harness	Ошибки входных данных, отказы policy и повторные запуски.
13. Очередь задач	Зависимости, отдельные рабочие копии и объединение изменений.
14. Ревью в команде	Что приложить к PR и на чём сосредоточить проверку.
15. Проверки для разных проектов	Особенности интерфейсов, серверного кода, мобильных приложений и инфраструктуры.
16. Права и автономность	Какие действия разрешать и как оценивать стоимость работы.
17. Эксплуатация агента	Владелец, версии, обновления и остановка при сбое.
18. Как harness дорабатывает себя	Сборка новой версии предыдущей и независимая приёмка изменений.
Финальный проект	Самостоятельная доработка harness и задача, выполненная с её помощью.

Практика

В практической части две связанные линии. Мы начинаем с runner v01, который можно написать вручную, собираем через него v02 с журналом событий, а затем v03 с проверкой команд и путей. Полученные версии применяем к ALGI, учебному дневнику боли: сначала добавляем записи и сводку, затем отчёт для врача.

В репозитории есть запускаемая цепочка до v03. Роль ответа агента в ней выполняют fixtures, заранее подготовленные файлы. Модель при этих запусках не вызывается. Это позволяет всем получить одинаковый результат и разобрать ошибки runner отдельно от ошибок модели. Очередь задач, автоматическое ревью и следующие версии harness предлагаются как самостоятельные доработки.

Начать можно с полного запуска цепочки, а затем читать главы с полученными файлами перед глазами. Если сейчас важнее наладить командную работу, начните с постановки задач, проверки результата и ревью.

Шаблоны и справочные страницы

В главах есть ссылки на заготовки документов. Чаще всего понадобятся задача, спецификация, контекст задачи, отчёт о запуске и описание PR.

Отдельно собраны глоссарий, задания для самопроверки, описание ALGI, устройство учебного runner и источники.

Адаптацию курса и внедрение в вашей команде можно обсудить на странице «Контакты».