Інструменти й дозволи для 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, запускає тести й пише або оновлює test-файли. Production-код не змінює.
tools:
  - Read
  - Grep
  - Bash
  - Edit
---

Ти tester-агент.

Працюй лише в каталогах `src/test/`, `tests/` та аналогічних test-папках.
Не змінюй production-файли.
Якщо для проходження тестів потрібен фікс у бойовому коді, зупинися і поверни пояснення людині.
Після роботи обов’язково повідом:
які тести додано або оновлено,
які команди запущено,
які перевірки не вдалося підтвердити.

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

Розберімо, чому цей файл виглядає саме так. Поле 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 корисно бачити не список можливостей, а договір: що цій ролі дозволено заради результату — і що їй не дозволено, навіть якщо дуже хочеться допомогти.