Я тройчы купіў папрыку, бо трымаў яе ў трох месцах.
Кватэра дасталася мне з паліцай для спецый над плітой. Калі на ёй скончылася месца, я прыстасаваў для іх шуфляду. Потым дадаў паліцу ў каморы. Кожнае рашэнне было слушным, пакуль я яго прымаў. А разам яны ператварылі пошукі папрыкі ў нечакана складаную справу.
Праблему выявіў сябар, які гатаваў у мяне. Увесь вечар я стаяў у яго за спінай і падказваў: добрая патэльня пад ракавінай, гэтая соль буйная, духоўка перагравае. Гатуе ён лепш за мяне. Яму проста патрэбны быў праваднік па маёй кухні.
У жніўні я зразумеў, што зрабіў тое самае з нашымі рэпазіторыямі.
Дубляваныя правілы
Праекты 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.
Я зноў праверыў запыт на ўбудаваную падтрымку AGENTS.md 15 кастрычніка 2026 г. Ён усё яшчэ быў адкрыты. Калі ўсталёўваеш сёння, глядзі цяперашнюю дакументацыю Claude Code пра памяць і правер, што насамрэч чытае Claude Code. Наш мост па-ранейшаму яўна паказвае, якую крыніцу імпартуе.
Інструкцыі, якія варта пакінуць
Пераезд файлаў пазбавіў нас дублявання. Карысным іх змесціва ён не зрабіў.
Агульны навык пра тое, як пісаць добры код, мала што кажа агенту пра нашы кропкі ўваходу ці праектныя слоты. Карысныя інструкцыі тлумачаць менавіта гэтую базу кода: які пакет валодае рэсурсам, якую мяжу павінна паважаць змена і якая праверка вылавіць памылку.
У пакетах OwlMeans Common інструкцыі ляжаць побач з кодам. Згенераваны праект можа ўсталяваць іх праз @owlmeans/agent-skills. Метаданыя пакета даюць інструкцыі, а рэпазіторый — лакальны кантэкст.
І тое, і другое ўсё роўна нехта мусіць падтрымліваць.
Наша правіла: пасля вялікай запланаванай працы пераглядаць адпаведныя навыкі. Калі змяніліся каманда, шлях ці паводзіны, перапішы інструкцыю, якая іх апісвае. Навык фармулюе цяперашняе правіла. А нататка з датай пра тое, што старое правіла перастала працаваць, пакідае наступнаму агенту вырашаць, які абзац мае перавагу.
Гэта мае сваю цану. Некаторыя задачы заканчваюцца працай над дакументацыяй, калі код ужо праходзіць праверкі. Я лепш заплачу яе, пакуль яшчэ памятаю, чаму змянілася рэалізацыя.
Памяць па падсістэмах
З памяццю дубляванне было іншага кшталту. Мы вялі хроніку задач.
Файл, названы паводле расследавання, расказваў, што адбылося на тым тыдні. Каб даведацца, што на той момант было праўдай пра маршрутызацыю, мне трэба было прачытаць некалькі расследаванняў і зразумець, якое з іх замяніла астатнія.
Мы перагрупавалі сховішча вакол самога праекта: маршрутызацыя, пераклады, разгортванне, знешнія сэрвісы. Індэкс звязвае гэтыя вузлы са шляхамі, якія яны ахопліваюць. Агент спачатку чытае гэтую карту, а потым адкрывае патрэбныя вузлы.
Запіс абнаўляе адпаведны факт на месцы, а не дапісвае яшчэ адну нататку з датай пад састарэлай. Праца, якая яшчэ ідзе, можа мець дату, але ўсталяваныя інструкцыі не павінны прымушаць аднаўляць ход сеанса.
У рэпазіторыі платформы дваццаць храналагічных файлаў ператварыліся ў адзінаццаць структурных вузлоў. Такія лічбы мы налічылі падчас рэарганізацыі. Карысць была ў тым, што я ведаў, дзе шукаць.
Сховішча памяці ўсё роўна трэба выпраўляць. Яго форма не перашкодзіць запісаць памылковае меркаванне, а кароткі індэкс не гарантуе, што агент загрузіць патрэбную старонку. Затое мы маем месца, дзе выправіць такое меркаванне, калі яго знойдзем.
Два тыдні
Рэарганізацыя заняла два тыдні. Частку гэтага часу я патраціў на пагадненні пра тэчкі, а частку — на дробныя праблемы сумяшчальнасці, якія выплываюць толькі тады, калі запускаеш іншага агента.
Згенераваныя праекты OwlMeans маюць інструкцыі для агентаў. У нашы паслугі ўваходзіць і адаптацыя навыкаў і метаданых да праекта, які мы перадаём. Але трымаць гэтыя інструкцыі карыснымі — па-ранейшаму справа таго, хто падтрымлівае рэпазіторый.
Сябру ўсё яшчэ трэба ведаць, што духоўка перагравае. Прынамсі, цяпер я маю адно месца, дзе гэта запісаць.
Упершыню апублікавана 13 жніўня 2026 г. Перагледжана 15 кастрычніка 2026 г.: агульныя фарматы аддзеленыя ад нашага пагаднення пра тэчкі, а назіранні пра сумяшчальнасць інструментаў атрымалі даты.