Я тричі купив паприку, бо тримав її в трьох місцях.
Поличка для спецій над плитою дісталася мені разом із квартирою. Коли місця на ній забракло, я облаштував шухляду. Потім додав полицю в коморі. Кожне рішення було цілком логічним, коли я його ухвалював. А разом через них знайти паприку стало напрочуд важко.
Проблема випливла, коли в мене готував друг. Цілий вечір я простояв у нього за спиною: добра сковорідка під мийкою, ця сіль крупна, духовка гріє сильніше, ніж показує. Він готує краще за мене. Йому просто треба було підказувати, що де лежить на моїй кухні.
У серпні я зрозумів, що зробив те саме з нашими репозиторіями.
Дубльовані правила
Крім вихідного коду, проєкти OwlMeans містять інструкції агентові для програмування: що де лежить, які команди запускати й що має вціліти після правки.
Ми підтримували Claude Code і GitHub Copilot. Правило для одного ставало навичкою в .claude/skills/, а другий отримував його копію в .github/instructions/. Мапи проєкту, shell-скрипти й памʼять обросли власними двійниками.
Один коміт зачепив дванадцять файлів навичок і одинадцять їхніх дзеркальних версій. До кожного виправлення додавалося маленьке питання: а другу копію я виправив?
В OwlMeans Common під час прибирання ми видалили 213 дубльованих файлів з інструкціями. Ця цифра описує зміну в нашому репозиторії. Про те, наскільки швидшим став агент, вона нічого не каже.
На заміну прийшли одна канонічна тека .agents/ і кореневий AGENTS.md. У навичок, правил, скриптів і спільної памʼяті зʼявилося своє місце. Файли для окремих агентів стали містками до цього джерела.
Спільний формат
AGENTS.md дає агентові інструкції проєкту у звичайному файлі Markdown. Специфікація Agent Skills визначає структуру теки навички та її SKILL.md.
Вони розвʼязують різні задачі. Кореневий файл пояснює агентові, як працювати в цьому репозиторії. Навичка містить процедуру, яку агент може підвантажити під конкретне завдання.
Специфікація навичок не приписує, яким має бути батьківський каталог. Вибір .agents/skills/ — наша власна домовленість під інструменти, якими ми користувалися. Мені не слід подавати цей каталог так, ніби кожен агент пообіцяв його знаходити.
Ця різниця стає важливою, коли додаєш ще один інструмент. Спільний текст допомагає, лише якщо інструмент справді його завантажує.
Місток для Claude
У серпні ми лишили невеликий CLAUDE.md, перша інструкція в якому — @AGENTS.md. Скрипт створював у .claude/skills/ по одному симлінку на кожну навичку.
Так Claude Code отримував ті точки входу, на які розраховував, а нам не доводилося підтримувати ще один набір інструкцій. Посилання оновлював хук сесії.
До окремих посилань на кожну навичку ми дійшли, тестуючи налаштування. Посилання на весь каталог навичок у нашій конфігурації не спрацювало. Це спостереження про те конкретне налаштування, а не незмінне правило для кожного майбутнього релізу Claude Code.
15 жовтня 2026 року я знову перевірив запит на нативну підтримку AGENTS.md. Він усе ще був відкритий. Якщо встановлюєш Claude Code сьогодні, звірся з актуальною документацією про його памʼять і перевір, що саме він читає. Наш місток, як і раніше, прямо вказує, яке джерело імпортує.
Інструкції, які варто зберігати
Коли ми перенесли файли, дублювання зникло. Але корисним їхній вміст від цього не став.
Загальна навичка про те, як писати добрий код, мало що скаже агентові про наші точки входу чи слоти проєктів. Корисні інструкції пояснюють саме цю кодову базу: який пакет відповідає за ресурс, яку межу зміна мусить поважати і яка перевірка ловить помилку.
Пакети OwlMeans Common містять настанови поряд зі своїм кодом. Згенерований проєкт може встановити ці настанови через @owlmeans/agent-skills. Інструкції надходять із метаданих пакетів, а локальний контекст — із самого репозиторію.
Підтримувати і те, і те все одно комусь доведеться.
У нас правило: після великої запланованої роботи переглядати відповідні навички. Якщо змінилися команда, шлях чи поведінка, треба переписати інструкцію, яка це описує. Навичка викладає чинне правило. Датована примітка про те, що старе правило перестало працювати, лишає наступному агентові вирішувати, який абзац переважить.
Це має свою ціну. Деякі завдання завершуються роботою над документацією, коли код уже проходить перевірки. Я волію заплатити цю ціну, поки ще памʼятаю, чому змінилася реалізація.
Памʼять за підсистемами
У памʼяті дублювання було іншого роду. Ми вели в ній хроніку завдань.
Файл із назвою якогось розслідування розповідав, що сталося того тижня. Щоб дізнатися, що зараз актуально щодо маршрутизації, мені доводилося перечитувати кілька розслідувань і зʼясовувати, яке з них замінило решту.
Ми перегрупували сховище довкола самого проєкту: маршрутизація, переклади, розгортання, зовнішні сервіси. Індекс зіставляє ці вузли зі шляхами, які вони охоплюють. Агент спершу читає цю мапу, а потім відкриває потрібні вузли.
Кожен запис оновлює відповідний факт на місці й не додає ще однієї датованої розповіді під застарілою. Робота, яка ще триває, може мати дату, але усталені настанови не повинні вимагати, щоб хтось відтворював сесію.
У репозиторії платформи двадцять хронологічних файлів перетворилися на одинадцять структурних вузлів. Це наші підрахунки під час реорганізації. Користь була в тому, що я знав, де шукати.
Сховище памʼяті однаково доводиться виправляти. Його форма не завадить записати хибне припущення, а короткий індекс не гарантує, що агент завантажить потрібну сторінку. Зате в нас є місце, де це припущення можна виправити, коли ми його знайдемо.
Два тижні
Реорганізація забрала два тижні. Частину цього часу я витратив на домовленості щодо каталогів, а частину — на дрібні проблеми сумісності, які спливають лише тоді, коли запускаєш іншого агента.
Згенеровані проєкти OwlMeans містять настанови для агентів. У межах наших послуг ми також підганяємо навички й метадані під проєкт, який передаємо. А щоб ці настанови й далі були корисними, над ними мусить працювати той, хто супроводжує репозиторій.
Другові й досі треба знати, що духовка гріє сильніше, ніж показує. Принаймні тепер у мене є одне місце, де це записати.
Уперше опубліковано 13 серпня 2026 року. Переглянуто 15 жовтня 2026 року, щоб відмежувати спільні формати від нашої домовленості щодо каталогів і датувати спостереження про сумісність інструментів.