Работа с агентами для кода

Мой любимый коллега никогда не спит

Я пользуюсь агентами для кода каждый день и скажу вслух то, о чём обычно молчат: разница между волшебным опытом и разочаровывающим почти никогда не в модели. Она в том, как вы работаете с агентом. Люди, которые жалуются, что «программирование с ИИ не работает», обычно дают агенту расплывчатую задачу, никакого контекста, а потом вливают в проект всё, что вернулось. Этот урок — рабочий процесс, который мне хотелось бы получить в первый же день.

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

Слова, которые вы встретите

Дайте контекст раньше, чем он спросит

Агент ничего не знает о вашем проекте, пока что-нибудь не прочитает. Можно позволить ему всё выяснять через grep — медленно и шумно, — а можно записать главное в файл AGENTS.md или CLAUDE.md в корне репозитория.

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

1# Проект
2 
3API менеджера задач. TypeScript, Fastify, Postgres, Vitest.
4 
5## Команды
6 
7- npm run dev — запустить сервер разработки
8- npm test — запустить тесты (всегда запускай перед завершением)
9- npx tsc --noEmit — проверка типов
10 
11## Соглашения
12 
13- Маршруты в src/routes, один файл на ресурс
14- Все обработчики проверяют ввод схемами zod
15- Только мягкое удаление: выставляй deletedAt, никогда не делай DELETE строк
16- Тесты: блоки describe называются по имени маршрута

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

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

Небольшие задачи с чёткими границами

Самый сильный рычаг — размер задачи. «Добавь аутентификацию в приложение» даёт большой комок, который трудно проверить. «Добавь эндпоинт входа, который проверяет email и пароль по таблице пользователей, с тестами» даёт результат, который можно проверить.

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

Просматривайте каждый дифф. Каждый.

Дифф — это просто список изменений: добавленные строки, удалённые строки, изменённые строки — то, что вы пролистываете, прежде чем нажать «слить».

Читайте каждое изменение, которое вносит агент, — целиком, строку за строкой. Агенты пишут правдоподобный код, а нужен правильный. Диффы агента я проверяю так же, как pull request начинающего разработчика, с одним отличием: я быстрее отклоняю и переформулирую задачу, потому что сгенерировать заново дешевле, чем спорить с диффом.

Когда изменений становится много, этот подход держится на тестах. Если в репозитории хороший набор тестов, я могу больше доверять зелёной галочке — и сосредоточить проверку на том, что тесты не покрывают: граничные случаи, безопасность, дизайн.

Git — ваша страховочная сетка

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

Шаблон промпта, который работает

После сотен сессий мой самый надёжный шаблон состоит из трёх фаз:

1. Исследование. «Прочитай нужные файлы и объясни, как сейчас работает X. Пока не пиши код». Вы получаете ответ в виде плана и можете поправить понимание агента, пока это ещё дёшево.
2. План. «Предложи план реализации. Перечисли файлы, которые ты затронешь». Небольшие планы утверждаются, большие — разбиваются.
3. Реализация. «Выполни шаг 1 плана. Когда закончишь, запусти тесты».

Для небольших задач всё это сворачивается в одно сообщение: исследуем неявно, затем действуем. Для всего, что затрагивает три файла и больше, я настаиваю на разделении.

Ваш первый промпт — готов к вставке

Вот весь шаблон одним сообщением. Замените задачу и имена файлов на свои, вставьте в своего агента — и вы сразу почувствуете разницу:

Ты — старший инженер, работающий в этом репозитории.

ЗАДАЧА: добавить эндпоинт POST /login, который проверяет email и пароль
по таблице users, с тестами.

КОНТЕКСТ:
- Следуй шаблону из src/routes/auth.ts
- Проверяй ввод схемой zod
- Только мягкое удаление: выставляй deletedAt, никогда не делай DELETE строк

ПРЕЖДЕ ЧЕМ ПИСАТЬ КОД:
1. Прочитай нужные файлы и объясни, как вход работает сейчас.
2. Предложи короткий план и перечисли файлы, которые ты затронешь.
Дождись моего одобрения. Пока не пиши код.

КОГДА Я ОДОБРЮ:
- Реализуй шаг за шагом.
- Запусти: npm test
- Исправь сбои самостоятельно, затем снова запусти тесты.

В КОНЦЕ: кратко опиши, что именно изменено и что осталось нетронутым.

Что агент на самом деле видит

Одна картина связывает всё это воедино: всё, что делает агент, — каждый прочитанный файл, каждый запуск тестов — попадает в его окно контекста. Размер этого окна ограничен: это рабочая память агента на эту сессию, и когда она заполняется, самые старые реплики сжимаются.

Вот сессия, разыгранная по шагам. Нажмите «▶ запуск» и следите за полосой:

Из этой картинки два вывода. Во-первых, преобладают чтение файлов и вывод тестов — поэтому так важны чётко ограниченные задачи: меньше прочитанных файлов — меньше потраченного бюджета. Во-вторых, длинным сессиям рано или поздно требуется сжатие: старые реплики пересказываются, чтобы сессия могла продолжаться. Отметьте под шкалой пункт «симулировать сжатие контекста»: останется то, что вы хотите видеть после сжатия, — ваши соглашения, задача, ключевые файлы, план, итоговый дифф и зелёный прогон тестов. Лишние крюки и шум пропадут.

Когда не стоит поручать

Кое-что я по-прежнему делаю руками, и думаю, что вам тоже стоит:

• Проектные решения. Именование, архитектура, моделирование данных — размышления, которые и есть настоящая работа. Агент может перечислить варианты; выбираете вы.
• Новые области, которые вы осваиваете. Если поручить это агенту, вы ничему не научитесь. Печатайте код сами, когда цель — ваше собственное умение.
• Код, критичный для безопасности. Аутентификация, криптография, платежи. Агент делает черновик, а вы сверяете каждую строку с чек-листом — или, ещё лучше, со специалистом.
• Расплывчатые задачи. «Сделай лучше» — это не задача. Если вы не можете сказать, как проверить успех, то и агент не сможет.

Проверьте себя

Что унести с собой

Если после прочтения вы измените что-то одно, пусть это будет порядок действий:

1. Потратьте десять минут на AGENTS.md сегодня. Команды, соглашения, жёсткие правила. Файл окупается в первой же сессии, а с каждой следующей отдача только растёт.
2. Сократите следующую задачу до трёх предложений. Назовите файл, шаблон, которому следовать, и команду, которая докажет, что всё работает.
3. Сначала просмотрите — потом запускайте. Прочитайте дифф, затем запустите сами. Зелёные тесты — это свидетельство, а решение остаётся за вами.
4. Делайте коммит после каждого завершённого шага. Небольшие контрольные точки превращают «агент пошёл не туда» из спасательной операции в откат за две секунды.

Сделайте эти четыре вещи — и агент станет тем коллегой, которого обещает заголовок.