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

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

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

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

Frontmatter агента: полный разбор

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

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

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

День 23: Frontmatter агента: полный разбор

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

На День 22 вы создали своего первого агента — файл в .claude/agents/ с несколькими строками описания. Он работал. Но скорее всего вы заметили: агент делал то, что вы написали в описании, но вёл себя как Claude по умолчанию — с теми же разрешениями, теми же инструментами, той же моделью. Это как нанять специалиста по договорному праву, но не дать ему доступ к базе договоров и попросить работать с теми же инструментами, что и рядовой менеджер.

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

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

Что это такое

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

---
name: contract-analyst
description: Проверяет договоры на типичные риски
model: opus
tools: [Read, Bash]
---

Всё между первыми --- и вторыми --- — это frontmatter. Всё после вторых --- — это системный промпт агента, то, что определяет его личность и логику работы.

Хорошая аналогия — должностная инструкция в паре с трудовым договором. Должностная инструкция описывает, что человек делает (системный промпт). Трудовой договор определяет условия: режим работы, доступ к ресурсам, зону ответственности (frontmatter). Без второго документа первый работает, но неконтролируемо.

Frontmatter определяет контекст выполнения, а не содержание

Системный промпт отвечает на вопрос «что агент делает». Frontmatter отвечает на вопрос «в каких условиях он это делает». Оба важны, но путать их — частая ошибка.

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

Разберём каждое поле. Не теоретически — через конкретные задачи директора.

name

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

name: kc-analyst

Правило одно: имя должно однозначно описывать функцию. Не «Помощник» или «Агент-1», а «Аналитик звонков» или «Редактор писем партнёрам». Когда у вас будет десяток агентов, вы скажете себе спасибо за внятные имена.

description

Тоже обязательное. Одна-две строки — что делает агент. Это поле используется двумя способами: во-первых, оркестратор (если вы его настроили) читает description, чтобы решить, какому агенту передать задачу. Во-вторых, это ваша собственная документация.

description: Анализирует записи звонков КЦ, выявляет проблемные паттерны, готовит отчёт по скрипту B1-D11

Хорошее description отвечает на три вопроса: что делает, с чем работает, что выдаёт. Если в description написано «помогает с аналитикой» — это плохое description.

model

Какую модель Claude использует этот агент. Если не указать — будет использована модель по умолчанию вашего проекта.

model: haiku

Это поле непосредственно влияет на стоимость и скорость. Для директора практическое правило такое:

Версии моделей

В поле model можно указать псевдоним (haiku, sonnet, opus, fable), полный идентификатор вроде claude-opus-5 или inherit — брать модель родительской сессии. Псевдонимы предпочтительнее: они сами переезжают на новое поколение. Актуальный список всегда на docs.anthropic.com.

tools

Список инструментов, которые агент может использовать. Если не указать — агент получает все инструменты по умолчанию.

tools: [Read, Write, Bash]

Доступные инструменты: Read (читать файлы), Write (создавать и изменять файлы), Edit (редактировать фрагменты файлов), Bash (выполнять команды в терминале), WebFetch (загружать страницы), WebSearch (искать в интернете), TaskCreate, TaskGet, TaskList, TaskUpdate (управление списком задач; старый TodoWrite по умолчанию отключён), mcp__* (инструменты MCP-серверов).

Для директора полезная практика — давать агентам минимально необходимый набор инструментов. Агент, который только анализирует документы и пишет отчёты, не должен иметь Bash — зачем ему терминал? Агент для написания писем вообще может работать только с Read (прочитать контекст) и Write (сохранить черновик). Меньше инструментов — меньше поверхность для неожиданных действий.

disallowedTools

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

disallowedTools: [Bash, Write]

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

permissionMode

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

permissionMode: acceptEdits

Варианты (default он же manual, плюс auto, dontAsk, plan):
- default — стандартный режим, агент спрашивает разрешение на потенциально опасные действия
- acceptEdits — агент автоматически принимает правки файлов без запроса, но всё ещё спрашивает про Bash-команды
- bypassPermissions — агент работает полностью без подтверждений

bypassPermissions — только для проверенных агентов

Режим bypassPermissions означает, что агент будет выполнять все действия без вашего подтверждения — включая удаление файлов, выполнение скриптов, запись данных. Используйте только для агентов, которые вы хорошо протестировали и которым полностью доверяете. Для нового агента всегда начинайте с default.

maxTurns

Максимальное количество шагов (итераций), которое агент может сделать в рамках одной задачи.

maxTurns: 10

По умолчанию — не ограничено. Это важный параметр безопасности и экономии: агент, который «завис» в цикле или столкнулся с неожиданной проблемой, не будет делать 100 шагов, потребляя токены и время. Для агентов, выполняющих хорошо ограниченные задачи (проанализировать один документ, написать одно письмо), достаточно 5-10 шагов. Для сложных многоэтапных задач можно поставить 20-30.

skills

Список навыков, содержимое которых целиком загружается в контекст агента при старте. Это не список разрешений: без этого поля агент всё равно может вызвать любой доступный навык через инструмент Skill. Это более специализированные наборы инструкций, которые вы разберёте на Дне 31.

skills: [report-formatter, contract-checker]

Пока достаточно знать: если у вас есть готовые skills, здесь вы указываете, какие из них доступны конкретному агенту.

mcpServers

Список MCP-серверов, к которым агент имеет доступ. MCP — это протокол подключения внешних инструментов (Notion, Google Sheets, базы данных). Подробно — в Фазе 6.

mcpServers: [notion, google-sheets]

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

hooks

Хуки — действия, которые выполняются автоматически в определённые моменты работы агента. Подробно разбираем в Фазе 5, здесь краткое введение.

hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "echo 'Агент использует Bash' >> ~/agent.log"
  PostToolUse:
    - matcher: "Write"
      hooks:
        - type: command
          command: "echo 'Файл изменён' >> ~/agent.log"

PreToolUse — выполняется до того, как агент применит инструмент. PostToolUse — после. Для директора практическое применение: логировать все изменения файлов, уведомлять в Telegram при создании важных документов, автоматически делать резервные копии перед правкой.

memory

Должен ли агент помнить контекст между сессиями. По умолчанию агенты не помнят предыдущие разговоры.

memory: project

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

Память и конфиденциальность

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

background

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

background: true

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

effort

Уровень усилий при рассуждениях. Влияет на то, насколько глубоко агент «думает» перед ответом.

effort: high

Варианты: low, medium, high, xhigh, max — какие доступны, зависит от модели. Более высокий уровень — более качественный результат, но медленнее и дороже. Для агентов, занимающихся быстрыми операционными задачами, low или medium вполне достаточно. Для аналитических агентов, которые должны замечать нюансы и противоречия в документах, high оправдан.

isolation

Уровень изоляции агента от основного проекта.

isolation: worktree

Единственное значение — worktree: агент работает во временной git-копии репозитория, и его правки не касаются вашей рабочей копии (копия удаляется сама, если он ничего не изменил). Отдельного поля «изоляция контекста» нет — контекст у субагента изолирован всегда. Прежние варианты none/partial/strict не существуют. Для агентов, работающих с внешними данными или выполняющих рискованные операции, разумный выбор — isolation: worktree.

color

Цвет метки агента в интерфейсе. Чисто визуальный параметр, но полезный, когда агентов много.

color: blue

Допустимые значения: red, orange, yellow, green, blue, purple, pink, cyan. Например: аналитические агенты — синий, редакторские — зелёный, агенты с высоким уровнем доступа — красный.

initialPrompt

Первое сообщение, которое агент получает при запуске. Позволяет автоматически начать задачу без вашего участия.

initialPrompt: "Проверь входящие письма за сегодня и подготовь список задач"

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

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

Ошибка 1: Не указывать model и удивляться цене

Без явного указания model агент берёт модель из CLAUDE_CODE_SUBAGENT_MODEL, если она задана, а иначе — модель основного разговора. Если вы строите небольшого агента для форматирования текстов и он использует Opus — это в 15-20 раз дороже, чем если бы он использовал Haiku. Всегда явно указывайте модель, соответствующую сложности задачи.

Ошибка 2: Давать слишком широкий набор tools

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

Bash — самый опасный инструмент

Инструмент Bash позволяет агенту выполнять любые команды в терминале: удалять файлы, запускать скрипты, обращаться к сети. Включайте его только если это действительно необходимо, и всегда тестируйте такого агента с permissionMode: default перед переходом к acceptEdits или bypassPermissions.

Ошибка 3: Включать bypassPermissions с самого начала

Логика «не хочу каждый раз кликать подтверждение» понятна. Но bypassPermissions — это для агентов, которые вы хорошо проверили. Новый агент с этим режимом и широким набором инструментов — это приглашение к неожиданным результатам. Протокол такой: начать с default, протестировать на нескольких задачах, убедиться, что агент действует предсказуемо, — и только тогда переходить к менее ограниченным режимам.

Ошибка 4: Путать description с системным промптом

description — это один-два коротких предложения для оркестратора и для вашей документации. Системный промпт — это подробные инструкции агенту. Часто люди пишут огромный description на 10 строк, а системный промпт оставляют почти пустым. Результат: оркестратор читает огромный description и плохо выбирает агента, а сам агент получает мало инструкций. Держите description кратким и содержательным, а детали переносите в тело файла.

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

Нужно настраивать frontmatter детально, если:

Можно оставить минимальный frontmatter, если:

Принцип постепенного ужесточения

Хорошая стратегия для нового агента: минимальный frontmatter → наблюдение за поведением → добавление ограничений там, где замечаете проблемы. Это лучше, чем пытаться с первого раза предусмотреть все сценарии.

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

День 22 — вы создали первого агента и познакомились с базовой структурой файла в .claude/agents/. Сегодня мы разобрали, как управлять поведением этого агента через frontmatter. Если на Дне 21 агент появился — сегодня он стал настраиваемым.

День 24 — тема tools в системном промпте: как описать агенту, каким образом использовать инструменты, в какой последовательности, с какими проверками. Frontmatter разрешает инструменты, системный промпт объясняет, как ими пользоваться.

День 41 — подробный разбор хуков: PreToolUse, PostToolUse, Stop, SubagentStop. Сегодня вы увидели поле hooks в frontmatter, через 18 дней разберёте его полностью — с реальными примерами уведомлений, логирования и автоматических действий.

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

Возьмите агента, которого создали на Дне 22 (или создайте нового с нуля). Добавьте в его frontmatter четыре поля: model (выберите подходящую модель под его задачу), tools (минимальный список нужных инструментов), maxTurns (разумное ограничение — поставьте 10), permissionMode: default.

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

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

Резюме

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