Tools и permissions для subagent

1. Инструкция без замка

Когда вы впервые проектируете агента, очень легко влюбиться в красивую инструкцию: «ты tester, проверяешь тесты и не трогаешь production-код» — и кажется, что дальше всё сложится само. Это как повесить табличку «не входить» на дверь без замка и удивляться, почему кто-то всё-таки вошёл.

Представьте ситуацию из Commerce OS. Вы починили баг в refund flow — один сценарий возврата обрабатывался неверно — и хотите поручить tester-агенту написать regression test. Если у него есть всё подряд — чтение, поиск, команды, полное редактирование проекта, — он может решить, что быстрее «помочь» правкой боевого кода, а не тестом. Проблема формально исчезнет. А у вас вместо tester — очень инициативный соавтор, которого никто не просил.

Вот здесь и появляется ключевой принцип. Роль отвечает на вопрос «зачем агент существует». Набор инструментов — на вопрос «что именно он имеет право делать руками». Оставите только первое — агент выйдет свободным. А свободный агент — это лишний diff, лишние риски и тот момент, когда вы открываете изменения: «Я же просил проверить тесты, а не переставить мебель во всей квартире».

У роли должна быть не только инструкция, но и техническая граница.

Важная мысль: tools — это не декоративное поле во frontmatter, а граница ответственности роли.

2. Два слоя прав: L1 и L2

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

flowchart LR
    A["L1: права текущей сессии"] --> B["L2: tools конкретного агента"]
    B --> C["Что агент реально может сделать"]

    D["Например: только чтение / планирование"] -. ограничивает .-> C
    E["Например: Read + Grep + Bash"] -. сужает .-> C

Если говорить совсем просто, L1 — режим сессии, в котором вы работаете вместе с Claude. L2 — права конкретного subagent внутри неё. Важнейшее правило: L2 не может сделать агента сильнее, чем позволяет L1. Только сузить, не расширить.

Это удобно увидеть в небольшой таблице:

Сегодня нас интересует именно L2. И да, здесь легко споткнуться о буквы и цифры: одинаковые ярлыки в разных схемах любят маскироваться под знакомые вещи. У инженерных сокращений иногда характер сложнее, чем у Spring Security.

Полезно посмотреть и на практические комбинации:

Read, Grep, Bash, Edit

Read, Grep, Bash

Read, Grep, Bash, Edit

Из этого следует очень практический вывод. Хотите агента безопаснее — не надейтесь на «будь осторожен» в инструкции. Сначала спросите себя: а нужен ли этой роли такой инструмент? Не нужен — не выдавайте. Самая сильная защита от лишнего редактирования — отсутствие Edit, а не просьба «не редактируй ничего лишнего».

3. tools как инженерный договор

Теперь можно смотреть на само поле tools не как на мелочь, а как на инженерный договор: допустимый радиус действий роли. Как хороший API-контракт: границы ясны — поведение предсказуемо; границ нет — догадки, расширение scope и хаос с уверенным лицом.

Обычно инструменты, которые вы даёте агенту, делятся на естественные группы:

С Read и Grep всё относительно спокойно — это естественная база почти для любого аналитического или ревью-агента. А Bash — инструмент взрослый: им можно запустить ./gradlew test, а можно выполнить совсем не ту команду, после которой вы внезапно полюбите резервные копии. Поэтому Bash почти никогда не живёт один: рядом нужны текстовые ограничения и понятные stop conditions, знакомые вам с прошлого уровня.

Ещё важнее история с Edit. Это частая ловушка новичка: кажется, лучше выдать чуть больше прав — вдруг пригодится. На практике это превращается в «вдруг он решил помочь сильнее, чем мы просили». Reviewer с Edit — уже не reviewer, а автор правок. Tester с Edit без каталоговых границ начнёт «чинить» production-код под видом борьбы за зелёные тесты.

Если инструмент не нужен роли для получения её результата, этого инструмента не должно быть в tools.

И ещё один важный нюанс этого курса: точные имена инструментов и способ их объявления могут немного отличаться между версиями Claude Code. Суть — нет: нужен явный allow-list, а не надежда на здравый смысл модели.

4. Least-privilege на живых ролях Workflow Kit

Теперь перенесём принцип least privilege в живые роли из Workflow Kit. Разница видна не на «агенте вообще», а на нескольких ролях рядом — тогда сразу ясно, почему «одинаковый набор tools всем подряд» — плохая идея.

Read, Grep, Bash

Edit

Read, Grep, Bash, Edit

Read, Grep, Edit

Read, Grep

С reviewer всё проще всего: прочитать diff, посмотреть связанные файлы, запустить безопасные проверки, вернуть findings. Как только reviewer получает Edit, идея ревью размывается — уже не взгляд со стороны, а второй автор, который ломает трассируемость: где закончился review и началось авторство.

С tester ситуация тоньше. Ему действительно часто нужен Edit: работа не только запускать тесты, но и писать test-файлы. Но даже здесь least privilege не исчезает, а становится точнее: редактирование разрешено только внутри test-каталогов. Агент работает в src/test/, tests/ и аналогичных зонах, но если для проверок нужно менять production-код — обязан остановиться и вернуть объяснение человеку. Это зрелая роль tester, а не «почти разработчик, но называется иначе».

Documenter — ещё один показательный случай. Edit ему нужен для документации, а Bash часто вообще не нужен: не выдавайте команды «про запас». Лишний Bash — лишний соблазн и лишняя поверхность риска.

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

5. Собираем agents/tester.md для Workflow Kit

Теперь давайте превратим теорию в рабочий артефакт. Представим, что в репозитории Workflow Kit вы открываете workflow-kit/.claude/agents/tester.md. Задача — не «самый умный tester в мире», а первый безопасный вариант, который работает с Commerce OS и не расползётся по проекту. Нас интересует роль только с tools: без scoped skills, памяти и других слоёв. Этого хватит, чтобы зафиксировать границу редактирования.

Точный синтаксис frontmatter и имена инструментов могут отличаться в вашей версии Claude Code — поэтому воспринимайте этот пример как инженерный шаблон, а не как священный YAML с горы.

---
name: tester
description: Проверяет текущий diff Commerce OS, запускает тесты и пишет или обновляет тестовые файлы. Production-код не меняет.
tools:
  - Read
  - Grep
  - Bash
  - Edit
---

Ты tester-агент.

Работай только в каталогах `src/test/`, `tests/` и аналогичных test-папках.
Не меняй production-файлы.
Если для прохождения тестов нужен фикс в боевом коде, остановись и верни explanation человеку.
После работы обязательно сообщи:
какие тесты добавлены или обновлены,
какие команды запущены,
какие проверки не удалось подтвердить.

В таком виде конфигурация намеренно узкая: минимальный набор действий, но ещё не весь контур знаний роли.

Разберём, почему этот файл выглядит именно так. Поле description задаёт рамку: production-код уже не зона агента. Edit в tools — только потому, что tester действительно пишет тесты. Собирали бы reviewer — Edit исчез бы сразу.

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

Для контраста полезно посмотреть на reviewer:

---
name: reviewer
description: Проводит локальный review diff перед PR. Только чтение.
tools:
  - Read
  - Grep
  - Bash
---

Ты reviewer-агент.
Не редактируй файлы.
Проверь diff, связанные тесты и команды проверки.
Верни findings с evidence и уровнем серьёзности.

Разница здесь принципиальная. Оба смотрят на один и тот же refund bugfix в Commerce OS, но у одного Edit нет вовсе, у второго он связан по рукам и ногам границами каталогов. Вот это и есть least privilege в живом виде, а не лозунг на стене.

Если вы хотите быстро понять, хорошо ли собран agents/tester.md, задайте себе один вопрос: сможет ли этот агент случайно улучшить то, что вы не просили улучшать? Ответ «да» — набор инструментов всё ещё широкий.

6. Собирай от результата, а не от прав

Когда вы проектируете нового агента, очень хочется начать с tools: что бы выдать? Но на практике надёжнее двигаться наоборот — от результата к минимальным действиям. Иначе выйдет типичный инженерный фокус: «сначала выдали права, потом придумали, зачем».

Здесь удобно работать по простой последовательности из четырёх шагов.

1. Начните не с инструментов, а с результата.
   Что именно агент должен вернуть? Findings по diff? Набор тестов? Документацию? Пока этого нет, поле tools — угадайка.

2. Для каждого результата выпишите минимальные действия.
   Review findings — чтение кода, поиск и, возможно, запуск проверок. Написать тесты — появляется редактирование, но не раньше.

3. Для каждого инструмента задайте неприятный вопрос: что плохого случится, если агент использует его неидеально?
   С Read вред ограничен. С Bash можно устроить приключение. С Edit — полноценный выход за роль. Этот шаг охлаждает избыточный энтузиазм.

4. Уберите всё, без чего роль всё ещё справляется.
   Documenter не запускает команды — убирайте Bash. Reviewer не должен править код — убирайте Edit. Tester пишет только тесты — сужайте редактирование до test-каталогов.

Эта последовательность особенно хорошо работает на нашем agents/tester.md. Начали с результата — дописать тесты и показать, что проверено, — и из этого выросли Read, Grep, Bash и осторожный Edit. Не больше. Не «на всякий случай». Не «вдруг пригодится».

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

1

Задача

Claude code, 12 уровень, 0 лекция

Недоступна

Урезание прав over-permissioned `reviewer`

Урезание прав over-permissioned `reviewer`

Открыть

1

Задача

Claude code, 12 уровень, 0 лекция

Недоступна

Ограничение `tester` только test-файлами

Ограничение `tester` только test-файлами

Открыть