Я трижды купил паприку, потому что держал её в трёх местах.
В квартире над плитой с самого начала была полка для специй. Когда она заполнилась, я приспособил под специи ящик. Потом добавил полку в кладовке. Каждое решение казалось разумным, пока я его принимал. А вместе они превратили поиск паприки в неожиданно трудное дело.
Проблема всплыла, когда у меня готовил друг. Весь вечер я простоял у него за спиной: хорошая сковородка под раковиной, эта соль крупная, духовка жарит сильнее, чем показывает. Он готовит лучше меня. Ему просто нужны были подсказки, как ориентироваться на моей кухне.
В августе я понял, что сделал то же самое с нашими репозиториями.
Дубли правил
Кроме исходного кода, в проектах 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 приходят с инструкциями для агентов. А в Услугах OwlMeans мы ещё и подгоняем навыки и метаданные под проект, который сдаём. Держать эти инструкции полезными — по-прежнему работа того, кто поддерживает репозиторий.
Другу всё ещё нужно знать, что духовка жарит сильнее, чем показывает. Зато теперь у меня есть одно место, где это записать.
Впервые опубликовано 13 августа 2026 года. Отредактировано 15 октября 2026 года: общие форматы отделены от нашего соглашения о папках, а наблюдения о совместимости инструментов датированы.