Агенты Claude Code: как разделить исследование, правку и проверку

Агенты Claude Code помогают разделить большую работу на отдельные задачи. Одному можно поручить изучить модуль, другому проверить изменение, третьему собрать карту файлов.

Это не способ обойти проверку результата. Если задача маленькая и последовательная, обычно достаточно одного рабочего диалога. На большом проекте разделение помогает не тащить длинные логи исследования в основной разговор. Базовый порядок начала работы описан в статье о Claude Code; здесь речь только об отдельных агентах.

Факты о настройке ниже сверены 25.10.2026 с официальной документацией Claude Code. Возможности и названия полей могут меняться, поэтому перед применением проверьте действующую страницу. Она описывает файл агента в .claude/agents/ для проекта и ~/.claude/agents/ для личного использования. В учебном примере ограничим агента чтением, чтобы он возвращал карту связей без изменений кода.

Когда разделение действительно помогает

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

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

Передавать задачу дальше удобно по короткому списку:

• Назовите поле и ожидаемое поведение.
• Попросите исследователя показать чтения и записи.
• Проверьте ссылки на файлы сами.
• Передайте исполнителю утверждённое правило.
• Сверьте результат с исходным сценарием.

Создайте роль для чтения проекта

Ниже пример файла .claude/agents/field-map.md. Указанный набор инструментов в официальном примере ограничивает роль чтением и поиском. Не добавляйте к ней изменение файлов, если цель лишь составить карту. Описание должно говорить, когда роль уместна; текст после frontmatter определяет формат результата.

---
name: field-map
description: Ищет все чтения и записи поля перед изменением модели данных
tools: Read, Grep, Glob
---

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

После создания файла проверьте, что он читается как обычный текст и не содержит клиентских данных. Затем в диалоге попросите применить field-map к конкретному полю и дайте корень нужного проекта. Не просите «проверь всё»: роль лучше работает с измеримым вопросом. Если инструмента или роли нет в текущей среде, остановитесь и проверьте путь файла и доступную документацию, вместо того чтобы изображать успешную проверку.

test -f .claude/agents/field-map.md
rg -n 'client_status' app lib bot
git status --short

Это пример для проекта, где есть папки app, lib, bot и поле client_status. Замените их своими именами после просмотра структуры. Команда rg нужна для независимой сверки результатов роли: вы видите хотя бы прямые упоминания. Косвенные связи, например сериализация или таблица базы, всё равно требуют чтения кода.

Пример задачи из моей практики

В проекте Deyvo пользователь создаёт дела голосом, видит их в дневном списке и получает сводку. Если менять поле времени задачи, надо проверить распознавание голосовой фразы, хранение даты, экран «Сегодня» и время уведомления. Я использую такой маршрут как пример карты связей до правки: роли агентам можно разделить по чтению кода, изменению и проверке результата.

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

Как проверять работу нескольких ролей

Главный исполнитель собирает выводы, сравнивает их с кодом и отвечает за итог. Для проверки попросите отдельную роль смотреть только diff и назвать рискованные места. Затем сами запустите сборку и пройдите путь пользователя. Если оба агента повторяют одну ошибочную гипотезу из задания, независимости не получилось. Поэтому дайте проверяющему ожидаемое поведение и сам diff, но не готовый вывод «всё хорошо».

git diff --stat
npm run build

В другом проекте команда сборки может отличаться; прочитайте package.json или инструкцию репозитория. Перед правкой сохраняйте понятное состояние файлов. Если исходное состояние уже содержит чужие изменения, отделите их от своей задачи. После правки посмотрите diff целиком: проверка агентом не гарантирует, что побочный файл не был переписан.

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

Перед запуском проверяющей роли:

• Дайте ей diff и ожидаемый результат.
• Попросите назвать рискованные места.
• Сравните замечания с исходным кодом.
• Запустите проверку проекта сами.

Частые вопросы

Нужно ли создавать агента для каждой задачи?

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

Может ли проверяющий агент сам утверждать результат?

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

Где хранить файл агента для команды?

Проектную роль помещают в .claude/agents/ внутри репозитория, если команда согласовала её правила. Личную роль размещают в пользовательской папке. Проверьте актуальное описание этих областей в официальной документации.

Что делать, если роль видит лишние файлы?

Сузьте задачу и доступные инструменты, затем проверьте, какие каталоги доступны процессу. Не полагайтесь только на фразу «не читай секреты» в тексте роли. В настройках Claude Code добавьте запрет чтения .env через deny-список и проверьте его пробным запросом. Секреты также не должны попадать в доступные файлы и журналы.

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