Как подготовить кодовую базу к работе с агентом

Очередная интересная статья от Антропика. На этот раз – о том, как подготовить свою кодовую базу к работе с агентом.

И одно дело, когда у тебя небольшой проектик, а другое – когда у тебя миллионы-миллионы строк кода, причём некоторые из них последний раз трогались в 2007-м.

Как агенту во всём этом ориентироваться? Индустрия много крутилась вокруг индексирования кода – у того же Cursor есть такой функционал. Но ребята идут в другую сторону.

И говорят: успех – в качественной обвязке, она же harness. В неё входят: CLAUDE.md (он же AGENTS.md), hooks, skills, plugins, поддержка LSP и MCP-серверы.

То есть если подготовить проект, агент сможет хорошо в нём ориентироваться. Дальше – чеклист, как это сделать:

1. Подготовьте CLAUDE.md для своего проекта. Если у вас огромный проект или монорепа – имеет смысл сделать отдельный CLAUDE.md для разных директорий, а в корневом оставить только общую картину мира. Обычно агент сам разбирается в структуре, но если вы знаете, что ваш проект – клубок, в корневом CLAUDE.md стоит сделать навигацию: коротенько, где что смотреть. Частая ошибка – класть в CLAUDE.md информацию, которая нужна не всегда, а под конкретный сценарий. По сути это то, что можно вынести в скилл.

2. Настройте hooks. Можно повесить хуки на подгрузку нужного контекста, на запуск линтеров и форматтеров. И в целом сделайте так, чтобы агент умел гонять проверки и тесты только по той части проекта, над которой идёт работа, – это быстрее и не засоряет контекст. Частая ошибка здесь – пытаться сделать промптом то, что можно было сделать обычной автоматикой. Если можно автоматикой – всегда делайте автоматикой.

3. Для повторяющихся, понятных задач сделайте скиллы. А также подключите к агенту LSP-сервер.

4. Поддерживайте .ignore-файл, чтобы в контекст агента не попадала ненужная информация – например, autogenerated или third-party код.

5. Раз в несколько месяцев пересматривайте CLAUDE.md и подобные артефакты. Это живой документ, который нужно периодически чистить: что-то становится неактуальным, модели становятся умнее, и какая-то информация им уже просто не нужна. Я помню времена, когда все автогенерировали эти артефакты – получалась такая фигня, что лучше уж их отсутствие, чем помойка.

6. У всего этого хозяйства должен быть ответственный – тот, кто поддерживает и следит за актуальностью.

Обратите внимание: пункты 5 и 6 – процессные. И, пожалуй, они самые сложные и самые важные (и скучные). По сути это всё про классические процессы в команде, в которые нужно встроить новые практики. Так что если у вас процессы уже настроены и вы знаете, как это делать – вам будет проще :)

#ai

Периодически я рассказываю о классных мероприятиях – и вот одно из них – infra.conf'26 – конференция про создание и эксплуатацию высоконагруженных систем и инфраструктуры.

Мне конечно же интересны темы, связанные с ИИ.

Активное развитие ИИ внесло существенные коррективы: послушаем, с какими новыми вызовами сталкиваются ребята и как с этим справляются.

Мероприятие пройдёт 4 июня. Приходите – будет классно :)

В курсе СТО от Стратоплана есть такая штука – База.

И несмотря на название, для меня именно эти темы оказались самыми интересными. Формат такой: раз в месяц – занятия на все выходные, суббота и воскресенье по 5 часов в день. За это время успеваешь довольно глубоко нырнуть в одну базовую тему.

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

По сути всё сводится к нескольким последовательным шагам:
1. Суть проблемы и цель – чётко сформулировать, в чём проблема, что будет, если её не решать, и какого результата хочешь от разговора.
2. Анализ собеседника – понять его поведение, позитивные намерения и скрытые потребности, чтобы говорить на его языке.
3. Формулировка и аргументация – подобрать слова и аргументы, которые показывают важность проблемы с учётом мотивов другой стороны.
4. Пожелание и проверка согласия – выбрать форму подачи (требование / просьба / вопрос / пожелание) и убедиться, что собеседник признаёт проблему и готов её решать.
5. Варианты решения с обоснованием – предложить конкретные выходы и аргументы в их пользу.
6. Закрепление и план Б – зафиксировать договорённости с контрольными точками и заранее продумать действия, если договориться не вышло.

Знаете, ещё иногда бывает – после встречи остаётся осадочек: "эх, вот тут надо было сказать по-другому" или "а вот ещё аргумент можно было привести". Так вот, чтобы схема заработала, к встрече надо готовиться заранее – буквально прописывать каждый пункт – и это прям важно. Тут как с любым навыком: я раньше реально всё фиксировал и расписывал, а теперь хватает просто черновичок накидать.

Отдельно на занятии разбирали медиацию – это когда ты как руководитель управляешь чужим конфликтом. Но это уже совсем другая история :)

Интересные практики работы с агентами

Любопытно читать, как люди, которые сами разрабатывают известных агентов, используют их в своей работе.

Зачастую такой опыт противоречив. Кто-то советует одно, кто-то – почти противоположное. Но это позволяет вдохновиться, попробовать что-то на практике.

В статье разработчик из OpenAI рассказывает, как он с использованием агента выстраивает рабочий процесс.

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

Отдельно автор подсвечивает управление голосом. Я уже рассказывал про Handy: можно быстрее выражать мысль и не тратить время на аккуратные формулировки. Еще прикольный use case – когда агент уже работает, можно прямо голосом быстро накидывать ему уточнения по ходу дела: что проверить, куда посмотреть и что сделать следующим шагом.

Много внимания в статье уделяется памяти. Многие сейчас копают в сторону сохранения контекста агентом, и автор предлагает использовать для этого Obsidian. По сути, это просто папка с файлами, куда агент постепенно заносит важную информацию.

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

Дальше автор переходит к доступу агента к браузеру и компьютеру. Иногда агенту недостаточно файлов и терминала. Ему нужно открыть локальную страницу, проверить UI, посмотреть залогиненный сервис или вообще покликать интерфейс, если нет нормального API.

Сюда же классная фича в Codex – remote control. Агент может продолжать работать на вашей машине, где уже есть окружение, доступы и локальные файлы, а вы можете подключаться к этому процессу с телефона. Запустил задачу, отошел, потом посмотрел прогресс, ответил на вопрос агента или поменял направление.

Еще одна интересная мысль – heartbeats. Это когда агент периодически просыпается и что-то делает без отдельного запроса от пользователя. Например, автор предлагает сценарий, где агент раз в 30 минут проверяет Slack и Gmail, находит сообщения, на которые нужно ответить, собирает контекст и готовит черновики. Сам он ничего не отправляет, но, когда вы возвращаетесь – рыба уже есть.

Меня очень привлекает идея дать агенту доступ к перепискам, накручивать вокруг этого автоматизации, но пока не могу переступить через порог и отдаться полностью 🙂

#ai