Уроки разработки Claude Code: как научиться видеть глазами агента

Тарик, один из разработчиков Claude Code, делится опытом проектирования инструментов для ИИ-агентов — от первых неудачных экспериментов до выработки работающих принципов дизайна.

Это AI-перевод статьи, сделанный каналом Про AI: Лучшие Статьи и Исследования.

Уроки разработки Claude Code: как научиться видеть глазами агента

Lessons from Building Claude Code: Seeing like an Agent Автор: Thariq Оригинальный текст:

Одна из самых сложных задач при создании агентной оболочки — конструирование пространства действий агента.

Claude действует через Tool Calling (вызов инструментов), но в Claude API существует множество способов конструирования инструментов с помощью таких примитивов, как bash, навыки (skills) и недавно появившееся выполнение кода (подробнее о программном вызове инструментов в Claude API можно прочитать в новой статье @RLanceMartin).

Учитывая все эти варианты, как проектировать инструменты для своего агента? Достаточно ли одного инструмента вроде выполнения кода или bash? А что, если дать 50 инструментов — по одному на каждый сценарий, с которым агент может столкнуться?

Чтобы мысленно поставить себя на место модели, я люблю представлять, что мне дали сложную математическую задачу. Какие инструменты вы бы хотели для её решения? Это зависело бы от ваших собственных способностей!

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

Это полезная рамка для проектирования вашего агента. Вы хотите дать ему инструменты, соответствующие его собственным способностям. Но как узнать, каковы эти способности? Нужно быть внимательным, читать выходные данные модели, экспериментировать. Нужно научиться видеть глазами агента.

Вот несколько уроков, которые мы извлекли, внимательно наблюдая за Claude в процессе разработки Claude Code.

Улучшение элиситации и инструмент AskUserQuestion

При разработке инструмента AskUserQuestion нашей целью было улучшить способность Claude задавать вопросы (это часто называют elicitation — элиситация, извлечение информации).

Хотя Claude мог просто задавать вопросы обычным текстом, мы обнаружили, что ответы на такие вопросы отнимали неоправданно много времени. Как снизить это трение и увеличить пропускную способность коммуникации между пользователем и Claude?

Попытка №1 — Редактирование ExitPlanTool

Первое, что мы попробовали, — добавить параметр к ExitPlanTool для массива вопросов вместе с планом. Это было проще всего реализовать, но это запутало Claude, потому что мы одновременно просили составить план и набор вопросов к плану. Что если ответы пользователя будут противоречить тому, что написано в плане? Придётся ли Claude вызывать ExitPlanTool дважды? Нужен был другой подход.

(подробнее о том, зачем мы создали ExitPlanTool, можно прочитать в нашем посте о prompt caching)

Попытка №2 — Изменение формата вывода

Затем мы попробовали изменить инструкции по выводу Claude, чтобы он использовал слегка модифицированный формат markdown для задавания вопросов. Например, мы могли попросить его выводить список вопросов в виде пунктов с вариантами ответов в скобках. Затем мы могли бы парсить и форматировать этот вопрос как UI для пользователя.

Хотя это было самое общее изменение, которое мы могли внести, и Claude, казалось, справлялся с таким выводом, гарантий не было. Claude добавлял лишние предложения, пропускал варианты или использовал совершенно другой формат.

Попытка №3 — Инструмент AskUserQuestion

В итоге мы остановились на создании инструмента, который Claude мог вызвать в любой момент, но особенно активно ему предлагалось использовать его в plan mode (режиме планирования). При срабатывании инструмента мы показывали модальное окно с вопросами и блокировали цикл агента, пока пользователь не ответит.

Этот инструмент позволил нам запрашивать у Claude структурированный вывод и обеспечить, чтобы Claude предоставлял пользователю несколько вариантов ответа. Он также дал пользователям возможность комбинировать эту функциональность — например, вызывать его в Agent SDK или обращаться к нему в навыках (skills).

Самое важное — Claude, похоже, охотно вызывал этот инструмент, и его выходные данные работали хорошо. Даже самый лучший инструмент бесполезен, если Claude не понимает, как его вызывать.

Является ли это окончательной формой элиситации в Claude Code? Мы не уверены. Как вы увидите в следующем примере, то, что работает для одной модели, может не быть лучшим решением для другой.

Обновление вслед за возможностями — задачи (Tasks) и списки дел (Todos)

Когда мы впервые запустили Claude Code, мы осознали, что модели нужен список дел (Todo list), чтобы не сбиваться с курса. Пункты можно было записать в начале и отмечать по мере выполнения работы. Для этого мы дали Claude инструмент TodoWrite, который записывал или обновлял пункты списка дел и показывал их пользователю.

Но даже тогда мы часто наблюдали, как Claude забывал, что ему нужно сделать. Чтобы адаптироваться, мы вставляли системные напоминания каждые 5 ходов, которые напоминали Claude о его цели.

Но по мере улучшения моделей они не только перестали нуждаться в напоминаниях о списке дел, но и могли находить его ограничивающим. Получая напоминания о списке дел, Claude начинал думать, что должен строго придерживаться списка вместо того, чтобы его модифицировать. Мы также заметили, что Opus 4.5 стал значительно лучше использовать субагентов, но как субагентам координироваться с общим списком дел?

Увидев это, мы заменили TodoWrite на Task Tool (инструмент задач) (подробнее о задачах можно прочитать здесь). Если списки дел были нужны для того, чтобы модель не сбивалась с пути, то задачи были больше направлены на помощь агентам в коммуникации друг с другом. Задачи могли включать зависимости, передавать обновления между субагентами, и модель могла изменять и удалять их.

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

Проектирование интерфейса поиска

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

Когда Claude Code только появился, мы использовали векторную базу данных RAG (генерация с дополнением из поиска) для нахождения контекста для Claude. Хотя RAG был мощным и быстрым, он требовал индексации и настройки и мог быть нестабильным в разных средах. Что ещё важнее, Claude получал этот контекст вместо того, чтобы находить его самостоятельно.

Но если Claude умеет искать в интернете, почему бы не искать в вашей кодовой базе? Дав Claude инструмент Grep, мы позволили ему самостоятельно искать файлы и формировать контекст.

Это паттерн, который мы наблюдаем по мере того, как Claude становится умнее: он всё лучше формирует свой контекст, если ему даны правильные инструменты.

Когда мы представили Agent Skills (навыки агента), мы формализовали идею progressive disclosure (постепенного раскрытия), которая позволяет агентам постепенно обнаруживать релевантный контекст через исследование.

Claude мог читать файлы навыков, а эти файлы, в свою очередь, могли ссылаться на другие файлы, которые модель могла читать рекурсивно. Фактически одно из распространённых применений навыков — добавление дополнительных поисковых возможностей для Claude, например, инструкции по использованию API или запросам к базе данных.

За год Claude прошёл путь от почти полной неспособности самостоятельно формировать контекст до умения выполнять вложенный поиск по нескольким слоям файлов, чтобы найти именно тот контекст, который ему нужен.

Progressive disclosure теперь стал стандартной техникой, которую мы используем для добавления новой функциональности без добавления инструмента.

Progressive disclosure — агент-руководство Claude Code Guide

В Claude Code сейчас около 20 инструментов, и мы постоянно спрашиваем себя, нужны ли все они. Планка для добавления нового инструмента высока, потому что каждый новый инструмент — это ещё один вариант, о котором модель должна думать.

Например, мы заметили, что Claude недостаточно знал о том, как использовать сам Claude Code. Если вы спрашивали, как добавить MCP или что делает та или иная слэш-команда, он не мог ответить.

Мы могли бы поместить всю эту информацию в системный промпт, но учитывая, что пользователи редко спрашивали об этом, это привело бы к «загниванию контекста» (context rot) и помешало бы основной задаче Claude Code: писать код.

Вместо этого мы попробовали форму progressive disclosure. Мы дали Claude ссылку на его документацию, которую он мог загрузить для поиска дополнительной информации. Это работало, но мы обнаружили, что Claude загружал множество результатов в контекст, чтобы найти правильный ответ, тогда как на самом деле нужен был только сам ответ.

Поэтому мы создали субагента Claude Code Guide, которого Claude получил инструкцию вызывать, когда пользователь спрашивает о самом инструменте. У субагента есть подробные инструкции о том, как эффективно искать в документации и что возвращать.

Хотя это решение не идеально — Claude всё ещё может путаться, когда вы спрашиваете, как его настроить, — оно значительно лучше, чем было раньше! Мы смогли добавить новые возможности в пространство действий Claude без добавления инструмента.

Искусство, а не наука

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

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

Подпишитесь на канал и каждый день читайте лучшие материалы про AI переведенные на русский!

Нашли интересную статью для перевода? Пришлите нашему боту: @ailongreadsbot