Scoped skills, MCP і memory

1. Від інструментів до знань: чотири шари можливостей

Коли ви вперше починаєте налаштовувати subagentʼів, дуже легко зациклитися на полі tools і вирішити, що робота майже завершена. Пастка зрозуміла: інструменти видно одразу, і вони створюють приємне відчуття контролю. Але хороший агент визначається не лише набором «рук» — ще й набором «знань». Read, Bash, Edit відповідають лише на питання про дії. Вони не кажуть, за якою процедурою агент працює, куди дивиться і що тягне з минулих задач.

Можливості агента зручно розкласти на чотири шари. Простими словами: tools — руки, skills — інструкція до роботи, MCP — вікна у зовнішній світ, memory — нотатки на полях.

test-strategy

Тут особливо важлива одна думка: принцип найменших привілеїв застосовується не лише до tools, а одразу до всіх чотирьох шарів. Reviewer не займається міграціями — migration-plan skill йому не потрібен. Tester не аналізує зовнішню документацію — не потрібен docs lookup. Роль не потребує памʼяті — відсутність memory не «недоналаштований агент», а дисципліна.

Хороший спосіб перевірити конфігурацію — поставити собі неприємне, але корисне питання: приберу цей skill, MCP або памʼять — агент перестане виконувати роль? Відповідь «ні, просто йому спокійніше, бо в валізі лежить усе підряд» означає зайвий контекст. А він для агента — як зайві вкладки в браузері: начебто все важливе, а зосередитися вже неможливо.

2. Scoped skills: свій workflow на роль

З skills особливо легко помилитися, тому що skill здається нешкідливим — «усього лише інструкція», не база даних, не запис у продакшені. І саме тут багато хто підключає агенту всі skills команди «про всяк випадок». Агент починає мислити занадто широко, вузька роль розповзається.

Згадайте, як влаштований Workflow Kit у команді. Там немає одного великого skill «роби все добре» — там окремі артефакти під різні типи повторюваної роботи: pr-review, test-strategy, migration-plan, release-notes, можливо, ще issue-analysis. У різних ролей різні процедури мислення. Reviewer читає diff, шукає ризики, повертає findings за severity. Tester думає рівнями тестів, edge cases, regression checks. Migration assistant читає changelog, шукає breaking changes, збирає compatibility picture. Дайте всім усе одразу — отримаєте агента з багатим внутрішнім світом і слабкою фокусованістю.

Усередині Workflow Kit:

workflow-kit/
  .claude/
    skills/
      pr-review/
      test-strategy/
      migration-plan/
    agents/
      reviewer.md
      tester.md
      migration-assistant.md

І далі важливо, щоб reviewer.md тягнув лише review-skill, а tester.md — лише тестовий workflow:

---
name: reviewer
tools: [Read, Grep, Bash]
skills:
  - pr-review   # чек-лист diff, evidence, severity
---

---
name: tester
tools: [Read, Grep, Bash, Edit]
skills:
  - test-strategy   # рівні тестів, edge cases, regression
---

Ці два приклади схожі зовні, але мислять по-різному. Reviewer не має радити міграційний план лише тому, що в проєкті лежить красивий skill migration-plan. Tester не має посеред перевірки refund diff перемикатися в автора release notes. Агент із десятьма skills схожий на студента перед іспитом: конспектів багато, ясності мало.

Тут є ще одна тонка, але дуже важлива грань: skill не дає нових прав. Reviewer підключений до pr-review, але без Edit — залишиться read-only. Skills описують, як думати, tools визначають, що можна зробити руками. Тому scoped skill — не заміна permission design, а його продовження.

3. Scoped MCP: зовнішні джерела привʼязані до ролі

З MCP хочеться вчинити як з power tools у гаражі: нехай лежать у всіх, раптом знадобляться. Зі зовнішніми джерелами це особливо небезпечно. Зайвий skill створює шум у мисленні. Зайвий MCP створює шум у мисленні і зайву поверхню ризику.

У межах цієї лекції нам не потрібна повна картина налаштування MCP, транспортів і авторизації. Зараз достатньо зафіксувати просту ідею: не потрібне ролі зовнішнє джерело — не підключайте жодного MCP. Порожній MCP-розділ — не образа для агента, а комплімент вашій інженерній зрілості.

Для звичайного reviewer на PR у Commerce OS зовнішні джерела найчастіше не потрібні: є diff, файли, тести, команда локальних перевірок. У tester вистачає коду, наявних тестів і локального Bash. А от migration assistant — зовсім інша справа: йому справді потрібен read-only доступ до docs lookup, щоб звірятися з офіційними changelogʼами і migration notes. Не база користувачів, не адмінка магазину, не платіжна система — один конкретний зовнішній канал для однієї конкретної ролі.

## MCP
- docs-lookup (read-only)
- без доступу до БД
- без зовнішніх write-actions

У такій формі межа видно особливо добре: агент отримує не «MCP загалом», а одне конкретне зовнішнє джерело у режимі читання. Read-only і write-capable — два різні світи. Read-only ризикує тим, що принесе в контекст занадто багато даних або сміття. Write-capable уже може змінити зовнішній стан системи. Звідси звичка: можна обійтися без MCP — обходимося; не можна — спочатку думаємо про read-only.

Уявіть: tester пише regression test для refund flow. Підключіть йому за замовчуванням docs lookup, DB MCP і зовнішній issue tracker — і він піде гуляти по зовнішньому світу там, де задача вирішується читанням двох test-файлів і одного service-класу. Розумнішим він не стане. Він просто відволікатиметься дорожче.

4. Scoped memory: без цифрового мотлоху

Memory здається найзатишнішою частиною конфігурації. Здається, ніби зараз ми навчимо агента «памʼятати важливе» — і далі все стане тільки краще. На практиці memory — місце, де особливо швидко накопичується втома системи. Хороша memory економить повторення стабільних фактів. Погана консервує випадкові здогадки і перетворює їх на звички.

Тому перше правило тут дуже просте: не кожному агенту потрібна памʼять. Новий агент без memory — нормальний старт. Особливо для reviewer: йому часто допомагає свіжий погляд, а не асоціації з минулих diffʼів.

Якщо памʼять усе ж потрібна, кладіть лише стабільні, перевірені, повторювані факти. Не «здається, payment tests сьогодні флакали, давайте їх більше не чіпати», а «integration tests лежать у такому-то каталозі» або «regression tests по refund шукаємо за префіксом Refund». Memory зберігає домовленості та стійкі патерни, а не емоційні спогади агента про важкий вівторок.

Локальна памʼять ролі tester:

# tester memory
- unit tests лежать в `backend/src/test/java`
- regression tests для refund шукаємо за префіксом `Refund`

Такий формат добрий тим, що він короткий і майже не залишає простору для фантазії. Але навіть тут важливо памʼятати: щойно памʼять стає спільною для команди, вона перестає бути особистою нотаткою і перетворюється на спільну поведінку — а вона має проходити review. Інакше у вас не «розумний агент команди», а розподілена система поширення застарілих переконань. Виглядає буденно: хтось одного разу додав у memory фразу про flaky tests, і через місяць tester обходить важливі перевірки з невинним виглядом «я так запамʼятав».

5. Приклад agents/tester.md: вузький контур знань

Теорія особливо швидко прояснюється, коли ви збираєте одного агента цілком. Візьмемо agents/tester.md із Workflow Kit: він допомагає на Commerce OS у задачах на кшталт bugfix у refund sorting або regression-перевірок навколо inbox. Потрібен агент, який читає код, запускає тестові команди, пропонує тест-дизайн і, якщо роль дозволяє, редагує лише test-файли. Йому не потрібні review-skill, migration-plan, зовнішній docs lookup і памʼять про всі інциденти компанії. Беремо зібраний набір tools і доводимо до робочого профілю: один scoped skill, локальна памʼять, ті самі жорсткі межі на редагування.

Такий файл виглядає так:

---
name: tester
description: проектує і запускає тести для поточного diff; production-код не змінює
tools: [Read, Grep, Bash, Edit]
skills:
  - test-strategy
memory:
  scope: agent-local
---

## Обмеження
Редагуй лише файли в `src/test` і `tests/`.
Не використовуй зовнішні MCP servers, якщо це не зазначено окремо.

У цьому прикладі видно одразу кілька інженерних рішень. Edit є, але це не «широке право на все підряд»: обмеження на test-файли закріплено в інструкції та, по можливості, технічними межами проєкту. Skill рівно один — test-strategy, цього достатньо, щоб мислити у правильній площині: unit, integration, API, regression, edge cases. Memory локальна: короткі ролеві нотатки можна, але все підряд в основну сесію не тягне і на інші ролі не впливає.

А от migration assistant, навпаки, буде зібраний інакше:

---
name: migration-assistant
tools: [Read, Grep, Bash]
skills:
  - migration-plan
mcp:
  - docs-lookup   # read-only
---

Тут уже немає Edit, зате зʼявляється одне зовнішнє read-only джерело — цій ролі справді потрібно читати офіційні керівництва і changelogʼи. Зверніть увагу, наскільки корисно порівнювати такі агенти поруч: не тому, що в них «різні професії», а тому що в них різний мінімально достатній контур знань. А якщо задачі потрібен лише read-only аналіз без правки test-файлів — це не новий агент з нуля, а вужчий режим того самого tester. У цьому і головна інженерна ідея scoped design.

6. Як це виглядає у Workflow Kit

Коли ви налаштовуєте одного агента, усе доволі зрозуміло. Справжня краса scoped-підходу видно на рівні набору ролей. Workflow Kit перестає бути звалищем «корисних штук для Claude» і стає системою: у кожної ролі свої tools, skill, зовнішнє джерело, підхід до памʼяті. Тут ви довіряєте не впевненості тону, а передбачуваності поведінки.

pr-review

test-strategy

migration-plan

Зверніть увагу: таблиця дуже нудна. І це чудово. Хороший Workflow Kit рідко виглядає ефектно — він виглядає так, ніби хтось занадто спокійно і педантично продумав межі. Reviewer не отримує migration-plan, щоб не бачити міграції в кожному rename. Tester не отримує DB MCP, щоб не шукати зовнішню причину там, де спочатку потрібно написати regression test. Migration assistant не отримує Edit, тому що його задача — зібрати картину сумісності, а не в пориві натхнення переписати півпроєкту.

Саме тому scoped capability майже завжди підвищує не лише безпеку, а й якість результату. Чим вужчий контур знань ролі, тим менше хибних спрацьовувань, контекстного пилу і спокуси «допомогти ще ось тут, раз уже відкрив файл». У хорошому Workflow Kit агент не почувається всемогутнім. Він почувається доречним. А це для інженерного результату набагато корисніше.