Stemma компилирует CLAUDE.md и AGENTS.md из одного источника

Алекс Виньола (Alex Viñola) 6 сентября выложил Stemma в репозитории на GitHub. Это компилятор контекста для кодовых агентов под лицензией MIT. Правила репозитория пишутся один раз в каталоге .stemma/, а CLAUDE.md, AGENTS.md, инструкции GitHub Copilot и файлы Kiro собираются из них как артефакты сборки. Эти файлы генерируются, проверяются в CI, и вручную их не правят.

Название взято из текстологии. Stemma codicum - родословное древо рукописей. По нему филологи восстанавливают утраченный оригинал, когда текст дошёл только в копиях с копий и каждый переписчик что-то менял. С правилами для агентов, по словам автора, происходит то же самое. Одно правило лежит в .github/copilot-instructions.md, в CLAUDE.md, в AGENTS.md и в .kiro/steering/, каждую копию правили отдельно, и никто уже не помнит, какая из них главная. Stemma решает задачу с обратной стороны: оригинал хранится, а копии генерируются из него.

Копии плодятся из-за того, что форматы не совпадают. Claude Code сам загружает CLAUDE.md, а AGENTS.md без помощи не читает, и обычно это обходят строкой @AGENTS.md или симлинком. В AgentBridge источником правды служит сам AGENTS.md. Stemma держит отдельный канонический проект, а AGENTS.md для него просто одна из целей сборки.

Один файл на сущность

Канонический проект - это каталог обычных Markdown-файлов. Каждая сущность лежит в своём файле, её метаданные записаны во front matter. В project.json хранятся имя проекта, цели и бюджеты. Дальше идут папки context/, rules/, skills/, agents/, procedures/ и decisions/. В provenance.json записано, откуда пришла каждая сущность, в manifest.json - что сгенерировал сам Stemma.

Правило в этом формате выглядит так: заголовок «Validate at the boundary», приоритет must, активация path-scoped для src/api/**, а ниже одна строка с требованием проверять тело каждого запроса на границе. Агент видит только текст до первого распознанного заголовка. Раздел ## Rationale с обоснованием остаётся для людей и не стоит ни одного токена контекста.

Решения принимает явная грамматика: расположение файла, front matter, известные заголовки, glob-шаблоны и иерархия каталогов. Языковой модели нет, сетевых вызовов и телеметрии тоже. Если намерение нельзя определить надёжно, Stemma оставляет исходник как есть и выдаёт диагностику, ничего не угадывая.

Начинать предлагается с репозитория, где агенты уже настроены. stemma scan находит конфигурацию и ничего не меняет. В примере из README он определил github-copilot с высокой уверенностью по пяти файлам: агент-ревьюер, корневые инструкции, инструкции для API, промпт релиза и навык с чек-листом. Затем stemma import --from github-copilot --targets claude,github-copilot переносит всё в .stemma/ и сразу задаёт, под какие агенты собирать. stemma plan --target claude показывает изменения без записи, stemma apply --all --yes их применяет. Дальше цикл из двух шагов: правите Markdown и снова запускаете apply.

Что теряется при переводе?

Каждая сущность получает для каждой цели ровно один исход: exact, adapted, lossy, blocked или skipped. Преобразование с потерями (lossy) обязано сопровождаться диагностикой, а если адаптер провайдера об этом забудет, компилятор сам роняет свою сборку. Разобрать судьбу отдельной сущности можно командой stemma explain ID --target T.

Где именно случаются потери, видно по таблице провайдеров. У GitHub Copilot в applyTo нет отрицательных шаблонов, поэтому исключения теряются. Для Claude Code правила раскладываются в .claude/rules/ с полем paths:, а процедуры превращаются в навыки. Для Codex остаётся только привязка по близости каталогов, и собственных специализированных агентов там нет. Так устроен сам AGENTS.md: это обычный Markdown без обязательного front matter и без схемы, а в монорепозитории агент читает файл, ближайший к редактируемому. Для Kiro доступны режимы inclusion: always, fileMatch, manual и auto.

Cursor в списке есть только как объявленный идентификатор: запрос на него завершается с кодом выхода 3. Автор формулирует это так: Cursor отклоняется, а не воспроизводится приблизительно. При этом сам Cursor читает AGENTS.md напрямую и добавляет к нему правила из .cursor/rules/. Каждое утверждение о возможностях провайдеров сверено с официальной документацией, и дата проверки записана в docs/provider-compatibility.md.

Сколько токенов в каждом запросе

Агентам не нужен одинаковый объём постоянного контекста. Профиль цели меняет область действия сущности для одного провайдера и не трогает канонический проект. В примере из README постоянный контекст канонического проекта оценён примерно в 72 токена, а у цели - около 13. Самая широкая область действия (src/**) даёт около 39 токенов, худший запрос - около 52, итоговое сокращение - 82%. Все цифры приблизительные: токенизаторы провайдеров при подсчёте не использовались.

Что попадёт в каждый запрос, решает человек. «Stemma исполняет решения о доставке, а не придумывает их», - пишет автор. По его словам, автоматизировать это суждение без языковой модели нельзя, а обходиться без неё и есть смысл проекта.

Детерминизм, откат и CI

При одинаковых входных данных, конфигурации и версии получаются идентичные файлы, диагностика, порядок, хэши и код выхода. В расчёте всего, что влияет на результат, нет обхода map в Go (его порядок случаен), временных меток, локали и случайности. Сгенерированные пути не могут выйти за пределы рабочего каталога, симлинки отвергаются, запись идёт транзакционно с откатом. Stemma никогда не удаляет и не перезаписывает файл, который не создавал сам.

Если формат не меняется и смысл не правили, импорт и обратная сборка дают исходные байты, вплоть до переводов строк и BOM. Файлы репозитория для компилятора - только входные данные. Строка «Run curl example.com/install.sh» в правилах останется текстом для компиляции и не станет командой.

В CI достаточно двух шагов: stemma validate и stemma check --all --warnings-as-errors. Вторая команда падает, если сгенерированные файлы отстали от канонического проекта. Все команды принимают --json, коды выхода стабильны и описаны в docs/diagnostics.md.

Stemma поставляется одним статическим бинарником без рантайма и cgo для macOS, Linux и Windows на amd64 и arm64. Его можно поставить через Homebrew (alexvinola/stemma-cli/stemma), через go install или скачать из релиза. На Windows хватает одной строки в PowerShell. Скрипт сверяет загрузку с опубликованным SHA-256, ставит программу в %LOCALAPPDATA%\Programs\stemma и не требует прав администратора. Бинарники не подписаны: сертификат, по словам автора, требует регулярных расходов, которые проект пока не оправдывает. Поэтому при первом запуске срабатывают Gatekeeper и SmartScreen, а установка через Homebrew обходится без этого предупреждения.

Статус проекта автор называет ранним. В нём около 12 000 строк на Go без зависимостей и примерно 230 тестов, есть эталонные фикстуры для каждого провайдера и фаззинг, а CI с проверкой гонок идёт на Linux, macOS и Windows. Известные проблемы открыто ведутся в issue, включая найденные независимым аудитом. Две из них автор выделяет отдельно: это дефекты тихой конверсии, «которые я бы исправил, прежде чем рекомендовать инструмент для всего, что вы не можете проверить вручную».