Мой дэйли дайджест

одно техническое понятие в день

Мастер Claude · Блок 3. Субагенты

Урок 22 из 93 · ~10 мин чтения

.claude/agents/: создаём первого агента

Урок пока закрыт

Курс проходится последовательно.

К текущему уроку

Почему это важно именно вам

Вы уже неделю работаете с CLAUDE.md и умеете раскладывать правила по модулям. Это хорошая база. Но CLAUDE.md решает одну задачу: он говорит Claude, кто он такой и как себя вести. Он не решает другую задачу — распределение специализаций. Когда вы в одном сеансе просите Claude сначала проверить договор, потом написать письмо партнёру, потом разобрать таблицу расходов — он переключается между задачами, и каждый раз немного теряет фокус. Инструкции из CLAUDE.md применяются ко всему сразу. Нет разницы между «режимом юриста» и «режимом аналитика».

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

Для директора по развитию это особенно ценно, потому что задачи разнородные: сегодня аналитика по воронке, завтра подготовка к совету директоров, послезавтра реакция на письмо от подрядчика. Один универсальный Claude-с-CLAUDE.md тянет всё, но тянет средне. Три специализированных агента тянут каждый своё и делают это заметно лучше. Сегодня создадим первого — и поймём механику, которая лежит в основе всей Фазы 3.

Что это такое

Агент в Claude Code — это обычный текстовый файл с расширением .md, который лежит в папке .claude/agents/ внутри вашего проекта. Файл начинается с frontmatter (блок между ---), где описаны параметры агента: имя, назначение, доступные инструменты, модель. Ниже frontmatter идёт системный промт — инструкции, которые Claude получает при вызове этого агента.

Аналогия из жизни: должностная инструкция. В компании есть юрисконсульт, финансовый директор, PR-менеджер. У каждого — своя роль, своя область ответственности и свой набор инструментов. Юрисконсульт работает с договорами и законами, финансовый директор — с цифрами и бюджетами. Когда вам нужен совет по контракту, вы идёте к юрисконсульту, а не к PR-менеджеру. Агенты работают точно так же: вы вызываете нужного специалиста под нужную задачу.

Второй момент, который важно понять сразу: агент — это не отдельный процесс и не программа. Это набор инструкций, который Claude Code загружает вместо или дополнительно к стандартному контексту. Когда вы вызываете агента по имени, Claude читает его файл, берёт системный промт оттуда и начинает работать в этой роли. Никакой магии, никакой сложной инфраструктуры. Просто файл с правильной структурой в правильном месте.

Агент и CLAUDE.md — разные слои

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

Как работает на практике

Шаг 1. Структура папки

Агенты живут в .claude/agents/ — это скрытая папка внутри вашего рабочего каталога. Если её нет, создайте:

~/Документы/Работа/
├── CLAUDE.md
├── .claude/
│   └── agents/
│       └── letter-editor.md   ← ваш первый агент
└── claude_modules/

Имя файла — латиницей, без пробелов, с расширением .md; совпадать с именем агента оно не обязано. Идентификатор задаёт поле name внутри файла: только строчные латинские буквы и дефисы.

Почему папка скрытая

Папка .claude/ начинается с точки — по соглашению Unix-систем это означает «системная/служебная папка, не для ручного просмотра». В Finder она не видна по умолчанию. Открыть её: Cmd+Shift+. в Finder или напрямую через терминал. В Claude Code она обрабатывается автоматически.

Шаг 2. Минимальный рабочий файл агента

Создайте файл .claude/agents/letter-editor.md со следующим содержимым:

---
name: letter-editor
description: "Редактирует деловые письма и email: тон, структура, чёткость. Вызывай когда нужно доработать или написать деловое письмо."
tools: Read
---

Ты опытный редактор деловой переписки. Твоя задача — делать письма чёткими, вежливыми и профессиональными.

Правила работы:
- Обращение к партнёрам — «Уважаемый [Имя Отчество]»
- Заканчивай каждое письмо конкретным следующим шагом или предложением
- Убирай слова-паразиты: «в принципе», «по большому счёту», «как бы»
- Запрещённые слова: «уникальный», «эффективный», «инновационный»
- Структура: приветствие → суть → детали → следующий шаг → подпись
- Если письмо больше 5 абзацев — предложи сократить

При получении текста письма: сначала коротко скажи что исправишь, потом дай исправленную версию.

Разберём frontmatter по полям:

name — идентификатор агента: строчная латиница и дефисы (letter-editor, data-analyst). По нему агент вызывается (@agent-letter-editor) и по нему же его видят хуки. Кириллица и пробелы недопустимы — файл с таким name Claude Code пропустит.

description — описание назначения агента. Важное поле: Claude Code использует его, чтобы понять, когда предложить этого агента. Пишите конкретно: что агент делает и когда его вызывать.

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

Шаг 3. Поле tools — что давать агенту

Инструменты — это то, что агент может делать помимо генерации текста. Основные варианты:

tools: Read                      # может читать файлы
tools: Read, Write               # читать и писать
tools: [Read, Write]             # может читать и писать файлы
tools: [Read, Write, Bash]       # может читать, писать и выполнять команды
tools: [Read, WebSearch]         # может читать файлы и искать в интернете

Для агента-редактора писем инструменты не нужны — он работает с текстом, который вы ему передаёте. Но если создаёте агента-аналитика, который должен читать таблицы из файлов — нужно добавить Read.

Принцип минимальных прав

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

Шаг 4. Поле model — когда менять

По умолчанию агент использует ту же модель, что настроена в Claude Code. Вы можете явно указать другую:

model: opus

или

model: haiku

Когда это полезно: если у вас много простых агентов для рутинных задач (форматирование, краткое резюме, исправление орфографии) — им хватит более лёгкой и быстрой модели. Сложные задачи (анализ договоров, стратегические рекомендации) — оставляйте на Opus или Sonnet. Это и быстрее, и дешевле, если у вас API-доступ.

Если не указывать поле model вообще — агент наследует текущую модель по умолчанию. Для начала это нормально.

Шаг 5. Как вызвать агента

Есть два способа:

Способ 1. @-mention по имени агента:

В диалоге наберите @ и выберите агента из подсказки. Вручную то же самое пишется как @agent-letter-editor — префикс agent- плюс значение поля name, а не имя файла. Claude Code поймёт, что вы обращаетесь к агенту из .claude/agents/letter-editor.md, загрузит его промт и начнёт работать в этой роли.

Пример:

@letter-editor вот черновик письма партнёру, посмотри:

«Привет, мы хотели бы обсудить условия нового контракта.
Давайте встретимся когда-нибудь на следующей неделе.
С уважением»

Способ 2. Natural language — описание задачи:

Claude Code умеет сам определять, какой агент подходит под задачу, на основе поля description в frontmatter. Если вы напишете «отредактируй это письмо» — Claude Code может предложить агента-редактора, потому что его description содержит «редактирует деловые письма».

Когда работает автоопределение

Автоматическое определение агента работает лучше, когда description написан конкретно и с глаголами действия. «Помогает с текстами» — плохое description. «Редактирует деловые письма и email: тон, структура, чёткость» — хорошее. Чем точнее описание, тем надёжнее автовыбор.

Шаг 6. Команда /agents

В диалоге Claude Code есть встроенная команда для управления агентами:

/agents

С версии 2.1.198 команда /agents списка не выводит — она печатает напоминание создавать и править агентов через чат или прямым редактированием файлов. Проверить, что Claude Code видит агента, можно иначе: наберите @ в чате и посмотрите, появился ли он в подсказке; а файлы с испорченным frontmatter найдёт claude plugin validate .claude/agents. Полезно, когда агентов уже несколько и вы хотите вспомнить, кто что умеет. Если агент появился в подсказке после @ — файл структурирован правильно.

Шаг 7. Второй агент — для разнообразия

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

---
name: data-analyst
description: Анализирует таблицы, сводки, цифры. Вызывай когда нужно разобрать данные, найти закономерности или подготовить выводы.
tools: [Read]
model: opus
---

Ты аналитик данных с опытом работы с бизнес-метриками. Твоя задача — находить смысл в цифрах и объяснять его простым языком.

Правила работы:
- Начинай с ключевого вывода, потом детали
- Указывай конкретные числа, не «значительно выросло» а «выросло на 23%»
- Выделяй аномалии и выбросы — они важнее средних значений
- Если данных недостаточно для вывода — прямо скажи об этом
- Не высказывай оценочных суждений о причинах, если причины не видны в данных

Формат вывода: Ключевой вывод → Что видим в данных → Аномалии → Вопросы для дополнительного анализа.

Сохраните в .claude/agents/data-analyst.md. Теперь наберите @ в чате — оба агента появятся в подсказке.

Частые ошибки

Ошибка 1. Агент создан, но не появляется в подсказке по @

Самая частая причина — ошибка в frontmatter. YAML строгий к синтаксису. Лишний пробел перед ---, кавычки не там где нужно, неправильное имя поля — и Claude Code не распознаёт файл как агента.

Как исправить: проверьте, что frontmatter начинается ровно с --- на первой строке, заканчивается --- без лишних символов. Обязательных полей два: name и description. Если tools не указать, агент унаследует весь набор инструментов, доступный субагентам; пустой список задавать нельзя — агент с нулём инструментов не запустится . Если файл всё равно не виден, скопируйте frontmatter из примера выше и замените только значения.

Ошибка 2. Слишком широкое описание в поле description

Вы написали description: помогает с задачами. Агент работает, но Claude Code не знает, когда его предлагать автоматически. Вы сами забудете через неделю, зачем этот агент.

Как исправить: description должен отвечать на два вопроса — «что конкретно делает» и «когда вызывать». Формула: «[Что делает]: [конкретика]. Вызывай когда [ситуация].»

Ошибка 3. Системный промт слишком общий

Агент создан, называется «Редактор», но в системном промте написано: «Помогай редактировать тексты». Результат — агент ведёт себя как обычный Claude, только с другим именем. Смысла в агенте нет.

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

Ошибка 4. Давать всем агентам полный набор инструментов

Рефлекторно добавляете tools: [Read, Write, Bash] «на всякий случай, вдруг понадобится». Агент-редактор с доступом к Bash — это агент, который теоретически может изменить что-то в файловой системе, пока редактирует письмо.

Как исправить: определите для каждого агента минимальный набор. Агент, работающий только с текстом в диалоге — tools: Read. Агент, которому нужно читать документы — tools: [Read]. Добавляйте инструменты только когда без них конкретная задача невыполнима.

Когда нужно / когда нет

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

Агенты нужны, когда задачи разнородные и смешивать их вредно. Правила делового письма и правила анализа данных — разные, иногда противоречащие. Лучше держать их в разных ролях.

Агенты не нужны для разовых задач. Если вам один раз нужно перевести документ — нет смысла создавать агента-переводчика. Дайте инструкции прямо в запросе. Агент — это инвестиция, которая окупается на повторении.

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

Не создавайте агентов наперёд

Соблазн велик: сразу создать десять агентов «под все задачи». В реальности половина из них будет вызываться раз в полгода, а правила в них устареют и начнут мешать. Создавайте агента тогда, когда почувствовали потребность в переключении режима — и поняли, что объясняете одно и то же повторно. Не раньше.

Связь с другими уроками

Задание на сегодня

Создайте одного агента под задачу, которую вы решаете регулярно.

Конкретные шаги:

  1. Определите задачу — ту, которую вы объясняете Claude повторно каждый раз. Это хороший кандидат.
  2. Создайте папку .claude/agents/ в вашем рабочем каталоге, если её ещё нет.
  3. Создайте файл агента по шаблону из урока: frontmatter с name, description, tools, и системный промт с конкретными правилами — не менее трёх конкретных инструкций.
  4. Наберите @ в Claude Code — убедитесь, что агент появился в подсказке.
  5. Вызовите его через подсказку по @ или вручную: @agent-<значение поля name> и дайте реальную задачу из вашей работы.

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

Резюме

Следующий урок откроется после отметки.