Что я поняла о разработке с агентами

Мой основной инструмент для разработки - Codex. Есть много задач, которые решаются клодом или обоими инструментами вместе, но где пишется основная часть кода - это кодекс. Поэтому опираюсь на его особенности и функциональности.* Пост применим не только к разработке - а к любой задаче при организации работы с агентами

1️⃣ Доки

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

1. должен быть единый не слишком длинный центр навигации со сводом правил, в каких случаях куда идти, где и как писать код,
2. чтобы этот центр навигации не был избыточным, добавляются кастомные, по-разному устроенные, детализирующие проект пояснения.

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

Должно быть конкретно, без противоречий и повторов. За актуальностью доков важно следить. Это базовая база организации работы с агентами.

Примеры доков:

1. agents.md / claude.md - центр, который описывает что вообще происходит на проекте и как устроен репо. Тот самый центр навигации
2. продуктовые доки, описывающие как работает продукт, путь пользователя и пр.
3. технические доки, описывающие архитектуру, стек, деплои и пр.
4. ревью доки, описывающие правила ревью кода,
5. командные вики, чтобы не писать вручную,
6. доки с бэклогом задач с чеклистом, в идеале разбитые на этапы. Модель берет последовательно этапы и проставляет галочки в чеклисте, всегда есть актуальный статус разработки и куда движется проект.
7. док со стилем кода, описывающий вкусовые предпочтения и правила написания кода с примерами, и пр.

2️⃣ Ценность планирования

Если нужна автономия - нужна детальнейшая декомпозиция плана. Более того, модель должна понимать цели работы, границы, критерии приёмки. Можно потратить дни на это планирование еще до начала разработки, если хочется потом отдать агенту самостоятельно работать с минимальным личным участием. И этого все равно бывает недостаточно. Где-то чуть-чуть недодуманная деталь = простор для самостоятельного принятия кодексом отстойного решения. А кодекс в отличие от клодика, очень даже любит принимать решения и не упоминать об этом. Так 6 итераций спустя становится понятно, что дом горит.

Истории "ночного сотрудника" очень воодушевляют, но не всегда кажутся реалистичными. Я так оставляю только те задачи, которые ну максимально понятны и декомпозированы. То есть совсем не так часто, как хотелось бы. И оставляю с надсмотрщиком (об этом в конце)

3️⃣ Ценность контроля

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

1) Контроль человеком:

Повторю уже упомянутый контроль человеком плана, описания ожидаемых результатов, критериев приёмки.

При этом при планировании разработка должна биться на части, между которыми требуется человеческий инпут: чаще всего проверка через человекочитаемый интерфейс, например, проверка пути пользователя. А так ли работает, как задумывалось? Тут человек лучше модели может оценить соответствие результата своим ожиданиям.

2) Контроль моделью:

Тесты! Модель пишет код и тут же тесты для проверки написанного куска кода, написанной функции и пр. Тут чатик лучше меня сформулировал, какие уровни автономной проверки нужны для четкой разработки и могут быть выполнены им самим:

1. dry run — пройти сценарий без реальных изменений;
2. static checks — проверить типы, линтер и сборку;
3. smoke — убедиться, что приложение запускается и основные функции работают;
4. unit — проверить отдельные функции;
5. integration — проверить взаимодействие компонентов;
6. E2E — пройти пользовательский сценарий целиком;
7. regression — убедиться, что исправленные ошибки не вернулись;
8. edge cases — проверить границы и нештатные ситуации.

🙌 И бонусом про надсмотрщика

Считаю супер фичей кодекса то, что он может из одного чата контролить другие. Вот вы уже хотите пойти спать, и хочется оставить работу, но под присмотром. Просим кодекс из соседнего чата поставить себе таймер, раз в час просыпаться и проверять - ок ли идет работа.

Но опять же - нужно сильно подумать над критериями, а что есть “ок”? Где тот момент, когда кодекс должен вмешаться и прервать работу. И, наоборот, каковы критерии запуска следующего этапа разработки.

Резюмирую: для разработки, да и любой работы с агентами, нужны: актуальный контекст, план и контроль.

Вывод: очевидно, но в любой сфере жизни, чтобы получить желаемый результат, надо очень, ОЧЕНЬ, хорошо формулировать хотелки.