П’ять шарів у Claude Code: пам’ять, навички, гачки, підагенти та плагіни.
Claude Code розглядається як середовище виконання агентів: пам’ять CLAUDE.md, надані за запитом навички, детерміністичні гачки, ізольовані підагенти та плагіни, які об’єднують усе це для команди.
Джерела: **Claude Code’s 5-Layer Agent Development Kit: The Architecture Most Engineers Are Missing**
Багато інженерів вважають Claude Code дуже здатним асистентом для програмування: відкривається термінал, передається завдання, пристрій читає файли та виконує команди, і можна спостерігати, як робота просувається вперед. Цей опис є точним, але неповним. Документація Anthropic представляє його як інструмент для програмування з агентною функціональністю, який працює в терміналі, розуміє кодову базу, виконує рутинні завдання та підключається до зовнішніх систем за допомогою механізмів на кшталт MCP. Якщо уважно прочитати, стає зрозуміло, що цей продукт — радше структуроване середовище виконання агентів із кількома окремими інтерфейсами керування, ніж модель, загорнута в оболонку командного рядка.
До цих елементів належать файл CLAUDE.md, який зберігається у пам’яті, багаторазово використовувані навички, детерміністичні хуки, підагенти, яким делегується робота, плагіни, які можна встановити, та посилання MCP на зовнішні системи. Тож корисне запитання змінюється: запитувати, що може створити Claude Code, менш важливо, ніж запитувати, як можна сформувати, обмежити, спеціалізувати та поділитися його поведінкою в межах команди.
Стек у п’яти шарах
Базова модель може писати код, пояснювати зміст файлів та відповідати на запитання. Однак сама по собі вона залишає кілька проблем нерозв’язаними: зберігання інформації про проект між сеансами, повторне використання експертизи у виконанні завдань, забезпечення контролю на рівні інфраструктури, обмеження того, що може бути делеговано, та забезпечення послідовної роботи команди. Ці проблеми не стосуються безпосередньо запиту, і дизайн Claude Code все більше враховує це. У документації постійні файли інструкцій, розширювані функції Skills, користувацькі підагенти, механізми hooks, діапазони налаштувань, плагіни та можливості з’єднання через MCP описуються як окремі механізми. Разом вони не є просто набором функцій — вони утворюють шари, які роблять поведінку агента більш надійною, перевикористовуваною та керованою:
- CLAUDE.md — це шар пам’яті та політик.
- Skills — це шар знань, який надає експертизу за потреби.
MCP та патерни агентських команд оточують цю структуру як системи, що пов’язують її із зовнішнім світом.
Цей опис пояснює проблему, яка траплялась у невдалих проектах агентів: проблемою рідко була сама модель. Бракувало певного шару. Одна команда повністю покладається на запити без постійної пам’яті про проект. Інша має детальні інструкції, але не має детермінованих механізмів контролю за використанням ризикованих інструментів. Третя перевантажує одного універсального агента, хоча роботу слід було розділити між спеціалістами. Більшість невдач агентів є архітектурними, а не проблемами запитів. Кожен шар розглядається нижче, починаючи з основи.
Чому архітектурний підхід кращий за список функцій
Якщо розглядати Claude Code як список функцій, виникає запитання про те, що він може робити. Якщо ж розглядати його як архітектуру, виникає краще розуміння: які шари він надає для контролю над тим, як формується, обмежується, делегується та ділиться поведінка агента? Як тільки запитання змінюється, стає легше аналізувати структуру системи, а також діагностувати проблеми під час її використання.
З документації випливають два моменти. По-перше, жоден з цих механізмів не знаходиться всередині самого моделювання; вони розташовані навколо нього — у файлах, обробниках подій, сферах конфігурації та форматах пакетування. По-друге, кожен з них вирішує іншу проблему: пам’ять допомагає боротися з забуванням, навички — з генеричною поведінкою, хуки — з ненадійністю, підагенти — з перевантаженим контекстом, а плагіни — з необхідністю повторювати правильну налаштування вручну.
Перший рівень: CLAUDE.md як пам’ять
Основою є CLAUDE.md. У документації його описують як місце для постійних інструкцій щодо роботи над проектом, тоді як окрема функція автоматичної пам’яті зберігає нотатки, які Claude пише для себе після багаторазових корекцій та встановлення уподобань.
Цей розподіл має значення. CLAUDE.md — це не тимчасовий блокнот для промптів. Команди зберігають тут довгостроковий контекст: стандарти кодування, попередні архітектурні рішення, улюблені бібліотеки, списки перевірок та обмеження робочого процесу, все, що має бути видимим перед першим повідомленням у сеансі.
Цікавою технічною складовою є спосіб завантаження. Це не просто читання одного файлу з поточної директорії. Claude просувається по ієрархії директорій від робочої директорії та завантажує кожен файл CLAUDE.md та CLAUDE.local.md, які знаходить. Файли об’єднуються у єдиний контекст замість того, щоб перезаписувати один одного, а інструкції, розташовані ближче до директорії запуску, читаються пізніше.
Це робить його системою пам’яті з визначеним діапазоном, а не окремим файлом конфігурації. Файл верхнього рівня може містити правила, що стосуються всього репозиторію, такі як правила найменування, очікування щодо тестів чи архітектурні межі, а файл на глибшому рівні ієрархії може обмежити функціонування певної підсистеми. Уявіть собі монорепозиторій: кореневий файл визначає, як називати тести та де знаходяться межі сервісів, тоді як файл у каталозі payments додає більш суворі правила, які застосовуються лише там. Той, хто розпочинає сесію в цьому каталозі, отримує обидва набори правил, причому більш конкретні інструкції читаються останніми.
Імпорти забезпечують можливість складання компонентів. Синтаксис @path/to/import дозволяє командам розділяти великі набори інструкцій на менші, повторно використовувані модулі, щоб один файл Markdown не перетворювався на сукупність непотрібних елементів. Функція Launch розгортає імпортовані файли в контекст, причому сам імпорт може імпортувати інші файли, до п’яти рівнів глибини. На практиці CLAUDE.md більше схожий на меморію проекту, яку можна складати з компонентів, ніж на статичну шаблонну форму для запитів.
Автоматична пам’ять відрізняється за функціоналом. Обидві завантажуються на початку кожної розмови, але CLAUDE.md містить те, що люди навмисно написали, тоді як автоматична пам’ять зберігає власні нотатки Claude у локальному каталозі машини, індексовані через MEMORY.md. На початку сеансу завантажуються лише перші 200 рядків або 25 КБ цього індексу. Натомість файли CLAUDE.md завантажуються повністю, незалежно від довжини, хоча компанія Anthropic відзначає, що коротші файли обробляються краще. Одна з форм пам’яті є контрольованою та декларативною; інша — адаптивною та емергентною.
Кращою ментальною моделлю, ніж „контекст вставляється один раз, щоб Claude запам’ятав стиль“, є робочий документ-чартер для агента. Anthropic навіть визначає загальноорганізаційні місця зберігання файлів CLAUDE.md, які керуються централізовано на основних операційних системах для десктопів, що свідчить про те, що цей рівень призначений для стабільної операційної політики, а не лише для особистих уподобань. Це дозволяє командам не повторювати одні й ті самі обмеження на кожній сесії та надає агенту стабільну основу перед початком роботи над конкретним завданням.
Практичною наслідком правил завантаження є те, що CLAUDE.md потребує регулярного управління. Оскільки кожен знайдений файл завантажується повністю, це призводить до збільшення об’єму даних у кожній сесії, тому рекомендація Anthropic щодо використання коротших файлів є підставою для їх регулярного скорочення. Процедури, які вже не вміщуються у файл, є першими кандидатами на видалення, що безпосередньо призводить до наступного рівня.
Другий рівень: Навички як знання за запитом
Якщо CLAUDE.md є постійною пам’яттю та політикою, то навички забезпечують модульні знання, які стають доступними у момент потреби. Згідно з документацією, запис інструкцій у файл SKILL.md — це спосіб, яким Claude набуває нових здібностей. Команда з слешем викликає навичку явно, або Claude може самостійно її використати, коли вирішить, що завдання до неї підходить.
Архітектурний аспект полягає у часу. «Тіло» навички — це не постійна пам’ять проекту. Воно потрапляє в контекст лише тоді, коли це необхідно, тож можна використовувати повторно процедури, чек-листи та посібники без зайвого навантаження на кожну сесію.
Багато інженерів розглядають налаштування як один довгий запит: вони поміщають усе в постійний контекст та сподіваються, що модель зрозуміє, що є важливим. Навички — це більш структурований варіант. Anthropic рекомендує створювати їх, коли одні й ті самі інструкції вставляються багаторазово або коли частина CLAUDE.md перетворюється з факту на процедуру. CLAUDE.md має містити стабільні правила проекту; навички — повторно використовувані оперативні знання. Це дозволяє тримати постійно завантажений контекст легким та перетворювати складні робочі процеси на модулі, які Claude може використовувати за потреби.
Навички — це не просто перейменовані користувацькі команди. Старіші файли .claude/commands/.md та новіші визначення у форматі .claude/skills//SKILL.md поводяться схоже під час виклику, але навички надають додатковий контроль. Вони дозволяють створювати каталог із супутніми файлами, визначати, хто може їх активувати — користувач, Claude чи обидва, підтримувати динамічне вставлення контексту та навіть виконуватися всередині підагента. Саме тому підходить термін „шар знань“: навичка — це одиниця, через яку експертиза, процедури та контекст завдань стають комбінованими під час роботи програми.
Уявіть собі навичку як запечатаний пакет знань для виконання певної роботи. Її опис вказує на мету, а перевірка під час виконання вирішує, чи підходить вона до поточного запиту; інструкції всередині завантажуються лише тоді, коли вони можуть допомогти. У документації зазначено, що навички у вигляді пакетів, такі як /debug, /loop та /simplify, ґрунтуються на запитах користувача, а не на фіксованій логіці, що є важливим показником їхньої конструкції. Таким чином поведінка стає модульною, оскільки не все кодується безпосередньо в основний продукт, що є набагато більш масштабованим підходом, ніж сподівання на те, що один величезний базовий запит покриє всі процеси роботи.
Уявіть команду, яка використовує стандартний метод для виправлення нестабільних тестів, перегляду міграцій SQL чи підготовки записів про випуск. Постійна пам’ять занадто узка для таких завдань, а одноразові запити є занадто повторюваними. Команда один раз пакує процедуру, зберігає довідкові матеріали поруч з нею, а Claude завантажує їх лише тоді, коли це необхідно для виконання завдання. Довгий довідковий контент усередині навички коштує майже нічого до моменту його використання, тож такий підхід є більш чистим та дешевшим у експлуатації.
Тому навички стимулюють звичку помічати повторення. Кожного разу, коли те саме пояснення вводиться втретє або абзац у CLAUDE.md починає нагадувати нумеровану процедуру, це, ймовірно, ознака навички, яку можна виділити. Цей крок займає кілька хвилин, але окуповується щоразу, коли завдання повторюється.
У сукупності CLAUDE.md забезпечує агенту стабільні основні правила, а функції Skills надають йому цілеспрямовані, повторно використовувані навички без збільшення розміру основного вікна контексту. Наступний рівень робить цю поведінку ще безпечнішою.
Третій рівень: Гаки як захисні механізми
Гаки перетворюють поведінку агента на щось, що можна контролювати. Офіційна документація описує їх як автоматизацію, засновану на подіях: команда виконується до або після певної дії в Claude Code під дією самої події. Гаки допомагають класифікувати типові сценарії використання: автоматичне форматування коду після змін, відмова у змінах до захищених файлів, відновлення контексту після стиснення розмови, аудит змін конфігурації, оновлення стану середовища при зміні файлів та попередня затвердження певних запитів на надання дозволів.
Це інша робота, ніж створення запитів. Запит може пропонувати певну поведінку; хук може перехоплювати її або детерміновано її трансформувати. Саме тому хуки краще розглядати як шар захисту, а не просто засіб для автоматизації.
Конкретний приклад наведено у посібнику з витрат: хук PreToolUse перехоплює команди Bash, розпізнає тестові виконання та переписує їх, так що результат, який отримує Claude, містить лише інформацію про помилки, а не весь потік даних. Механічно хук отримує JSON-дані, які описують запит, аналізує команду та відповідає JSON-даними, які змінюють вхідні дані інструменту. У цьому процесі ШІ не приймає рішень щодо покращення результату; це інфраструктура, яка контролює те, що модель може бачити чи робити на певному етапі робочого процесу.
Слід звернути увагу на контраст між правилами на рівні запиту та іншими правилами. „М’які“ захисні механізми часто є занадто слабкими для реальних умов використання. Уявіть собі, що генерований код завжди має переформатуватися, конфіденційні файли ніколи не повинні змінюватися, а виклики руйнівних інструментів потребують більш суворої перевірки. Покладання лише на письмові інструкції є крихким, тоді як хуки переміщують контроль за межі дискреції моделі та забезпечують дотримання правил робочого процесу на рівні подій.
Хуки також знаходяться поруч із механізмами керування контекстом, а не всередині них. Документація з усунення проблем вказує „хуки, які не функціонують“, як окрему проблему конфігурації та рекомендує використовувати /doctor для діагностики проблем із хуками, серверами MCP та використанням контексту. Обидві деталі свідчать про те, що хуки належать до середовища виконання: це поведінка, яка керується конфігурацією та має бути правильно інтегрована в час виконання сесії, а не просто текст, який читає Claude.
Є ще й аспект витрат. Керівництво з витрат від Anthropic рекомендує переміщувати обробку даних у хуками та навичками, оскільки хуки можуть попередньо обробити великі об’єми даних ще до того, як модель їх побачить. Як приклад наводиться фільтрація величезного журналу тестів, щоб залишилися лише помилки, що дозволяє скоротити обсяг даних, який може становити десятки тисяч токенів, до значно меншого об’єму. Таким чином хуки сприяють як ефективності, так і безпеці: вони зменшують марнування токенів, підтримують чистоту контексту та звільняють модель від завдань з фільтрації, які детерміністична логіка оболонки виконує дешевше та надійніше.
Допомагає уявити собі ситуацію «до» та «після». До використання хуків команда пише у інструкціях «завжди запускайте форматувальник» та сподівається на краще. Після використання хуків форматувальник запускається після кожної зміни, незалежно від того, пам’ятає про це модель чи ні, а захищений файл просто не можна змінити. Агент все ще вільно обмірковує, що створювати; хук визначає, що дозволено робити під час цих обмірковувань.
Більшість команд спочатку недооцінюють цей рівень. Пам’ять допомагає агенту запам’ятовувати, а навички — спеціалізуватися, але хуків перетворюють повторювані операційні вимоги на правила. Вони знаходяться саме там, де зустрічається міркування, кероване моделлю, та поведінка, нав’язана системою, і саме там насправді виникає багато проблем у продакшені. Без них якість занадто сильно залежить від запиту.
Четвертий рівень: підагенти для делегування
Якщо гаки відповідають за керування, то субагенти відповідають за делегування. У документації їх описують як спеціалізованих допоміжних систем ШІ, які виконують певні типи завдань у власному вікні контексту та повертають лише результат.
Логіка проста. Одним із найшвидших способів погіршити якість сеансу є дозволити побічним завданням забруднювати основну розмову логами, результатами пошуку чи експериментальними міркуваннями, які ніколи не будуть використані знову. Замість того, щоб змушувати одного універсального агента виконувати все в одному потоці, основний агент передає побічне завдання спеціалізованому працівнику, який працює незалежно та надсилає узагальнення. Серед переваг:
- Експлорація та реалізація не впливають на основну розмову, що дозволяє зберегти контекст.
- Обмежений доступ до інструментів запроваджує обмеження.
- Конфігурації можна використовувати у різних проектах.
- Цілеспрямовані запити спеціалізують поведінку.
Називати підагента іменованим запитом — це недооцінка його функцій. Насправді це самостійна одиниця роботи, яка містить опис, системний запит, обрану модель, набір дозволених інструментів, налаштування пам’яті та межі часу виконання.
Вбудовані приклади ілюструють їхнє призначення. Explore оптимізований для читання та аналізу кодової бази, Plan використовується для планування робочих процесів, а універсальний агент виконує складні багатоетапні завдання, які поєднують логічне мислення та дії. У документації зазначено, що вбудовані підагенти успадковують права батьківської розмови, а також додаткові обмеження щодо інструментів, тож делегування завдань є обмеженим за своєю суттю.
Ще одне обмеження: підагенти не рекурсують. Anthropic стверджує, що підагент не може створювати інших підагентів, саме тому Claude уникає нескінченного вкладання, при цьому все одно збираючи необхідний контекст. Без чіткого обмеження делегування може призвести до неконтрольованих структур агентів, які є дорогими у обробці, важкими для моніторингу та складними для аналізу. Модель залишається простою: основний агент передає завдання вниз, підагент виконує його ізольовано, а результат повертається назад.
З практичної точки зору, підагенти можна налаштовувати в різних масштабах. Їх можна створювати інтерактивно за допомогою команди /agents, зберігати для кожного користувача у директорії ~/.claude/agents/, зберігати для кожного проекту у директорії .claude/agents/, передавати через командну лінію для однієї сесії або включати у плагіни. Кожен з них — це файл формату Markdown із YAML-передмовою, проте поведінка, яку він визначає, є різноманітною: вибір моделі, доступ до інструментів, поведінка пам’яті, хуки та навички — усе це можна налаштувати для конкретного підагента. Це профілі виконання, а не мітки ролей.
Саме тому субагенти належать до найважливіших елементів архітектури. CLAUDE.md закріплює основного агента за правилами проекту, модульні навички забезпечують необхідну експертизу, а механізми кріплення дотримуються політик під час виконання, проте субагенти запобігають тому, щоб усе не перетворилося на одну надмірно обтяжену розмову з занадто багатьма обов’язками. Ізоляція — це тихий, але важливий перевага. Субагент може читати десятки файлів, виконувати пошук та досліджувати безвихідні ситуації, при цьому жодна з цих дій не потрапляє до основного потоку, який отримує лише результат. Вони створюють чіткі межі навколо побічних завдань, дозволяють командам спеціалізуватися у своїх робочих процесах та підтримують чистоту та довговічність основного контексту. Коли делегування вже на місці, залишається лише організаційна проблема: як упакувати все це для команди.
Вибір місця для кожного правила
З наявністю п’яти рівнів розміщення стає елементом дизайнерського рішення. Корисним тестом є запитання про те, як має поводитися правило. Якщо його потрібно завжди знати, помістіть його у CLAUDE.md. Якщо це процедура, яка потрібна лише іноді, перетворіть її на навичку. Якщо її необхідно застосовувати незалежно від рішення моделі, це є хуком. Якщо робота є шумною, самостійною або підходить для дешевшої моделі, передайте її підагенту. Якщо весь комплекс потрібно передати іншому місцю, запакуйте його як плагін. Правила, розміщені на неправильному рівні, схильні до помилок у звичний спосіб: політика, залишена у прозовому вигляді, ігнорується, довга процедура, що зберігається в пам’яті, займає всю доступну місцевість, а розумна налаштування, залишені на одному ноутбуці, ніколи не потрапляють до команди.
П’ятий рівень: плагіни для розповсюдження
Припустимо, що у команди вже є файл пам’яті, навички, хуки та підагенти. Проблема більше не полягає у локальній поведінці — це проблема розповсюдження. Як така конфігурація може переміщуватися між репозиторіями, комп’ютерами та колегами без необхідності її щоразу вручну перебудовувати?
Anthropic пропонує кілька механізмів для пакетування та повторного використання поведінки в різних контекстах: підагенти на рівні користувача та проекту, спільні навички, налаштування плагінів, розгортання CLAUDE.md у всій організації, а також плагіни, які забезпечують інтелект коду чи інші функції. Claude Code призначений не лише для індивідуального використання; він все більше спрямований на те, щоб команди стандартизували та поширювали спосіб поведінки агента.
Найяснішим офіційним сигналом є модель плагінів та налаштувань. Документація до налаштувань описує спеціальні розділи для конфігурації плагінів, списки дозволених елементів та права доступу, такі як codeIntelligence.*, а також локальні налаштування проекту та успадковані налаштування користувача. У ній також зазначено, що аргументи командного рядка, такі як параметри append-system-prompt та allowed-tools, не передаються у плагіни, що підтверджує, що плагіни є окремими одиницями розповсюдження з власною поведінкою, а не пасивними розширеннями основної сесії. Отже, плагіни слугують радше для упакування поведінки агента, щоб її можна було встановлювати, повторно використовувати та керувати нею у масштабі.
Така сама структура спостерігається й в інших місцях. Підагенти підтримують встановлення на рівні користувача, проекту, лише для поточної сесії та за визначенням плагінів. Навички мають модульну структуру, яка дозволяє повторно використовувані знання існувати поза шаром пам’яті, який завжди завантажений. Архітектура не обмежується лише можливістю агента щось робити; вона все більше зосереджується на тому, як цю здатність можна запакувати та поділитися, що є ознакою платформи, а не допоміжного інструменту для одного користувача.
Управління також є частиною цього процесу. Один спільний пакет може містити перевірених підагентів, суворо обмежені права доступу до інструментів, стандартні механізми взаємодії чи робочі процеси, характерні для певної організації, тож команди розповсюджують правила, а не лише зручність. Шляхи управління файлами CLAUDE.md в корпоративних середовищах свідчать про те, що стандартизація була запланована з самого початку. Той самий багаторівневий дизайн, який прискорює роботу одного інженера, може стати моделлю функціонування всієї команди, у якій пам’ять, досвід, контроль та делегування обмінюються замість того, щоб їх створювати заново.
Що йде не так, коли бракує рівня
Якщо дивитися на всю структуру цілком, вона є практичним чек-листом для діагностики ненадійної налаштованої системи агентів. Симптоми зазвичай вказують на відсутній рівень.
- Агент постійно ставить одні й ті самі запитання або ігнорує стиль будинку. Пам’ять відсутня. Стабільні правила мають знаходитися у CLAUDE.md, розділені за каталогами та розбиті на імпорти, щоб файли не ставали занадто великими.
- Кожна сесія починається з довгого вставленого процедуру. Знання застрягають у запитах. Перемістіть повторювані частини до навичок, щоб вони завантажувалися лише тоді, коли це необхідно для виконання завдання.
- Ризиковані дії залежать від того, чи пам’ятатиме модель бути обережною. Механізми контролю є лише рекомендаціями. Хуки забезпечують форматування, захист файлів та переписування команд незалежно від рішення моделі.
- Основна розмова заповнюється журналами подій та глухими кутами. Відсутня делегування обов’язків. Підагенти з обмеженими інструментами виконують непотрібну роботу та повертають лише узагальнення.
Спільним між усіма цими рішеннями є те, що жодне з них не полягає у створенні кращого речення в запиті. Це структурні зміни, саме тому вони ефективно працюють під справжньою навантаженням. Розглядати Claude Code як інструмент для розробки агентів, який випадково постачається разом із терміналом, дозволяє краще бачити ці зміни, легше обговорювати їх із командою та поступово, шар за шаром, впроваджувати їх навмисно.