November 10

Как я заставил AI-агента поддерживать 90 PHP-пакетов и не сойти с ума

В моём монорепозитории 90 опубликованных Composer-пакетов. Это экосистема для Yii3: feature flags, A/B-тестирование, вебхуки, outbox, телеметрия, метрики, audit log, idempotency, workflow, file storage — плюс собственные библиотеки без привязки к фреймворку: specification pattern, retry, circuit breaker, bulkhead, schema validation, property-based testing фреймворк. У каждого пакета свой CI из восьми джоб, мутационное тестирование с порогом MSI от 85, двуязычная документация и собственный AGENTS.md.

Сам монорепозиторий — рабочая копия и закрыт, но каждый пакет живёт в публичном репозитории на GitHub, а инструменты и правила, о которых пойдёт речь, выложены снимком в php-package-toolkit (на английском, состояние на 10 ноября 2026-го).

Код в этом репозитории в основном пишет не человек. Его пишет AI-агент.

Звучит как кошмар? Я понимаю, почему. Истории про «нейросеть сгенерировала 5000 файлов, которые не компилируются» стали жанром. Но вот что произошло на самом деле: CI в этом репозитории держится зелёным стабильнее, чем у многих человеческих команд, с которыми я работал. Не потому что модель стала умнее. А потому что за несколько месяцев я понял главное:

Секрет не в умной модели, а в институциональной памяти, записанной в форме, которую агент физически не может проигнорировать.

Об этом лонгрид. Разберу систему целиком: правила и то, как они эволюционируют после каждого инцидента; честные гейты качества — включая мутационное тестирование и то, как я узнал, что моя главная метрика мне лгала; и процесс релизов, в котором нет права на ошибку, потому что Packagist не даёт второго шанса. В финале — честный разбор того, что из этого переносится на обычную разработку, а что специфично для работы с агентом.


Часть 1. Агент как стажёр с амнезией

Начну с диагноза. Чем на самом деле плох AI-агент как автор кода — не в абстрактном «он тупой», а конкретно, по симптомам, которые я наблюдал в собственном репозитории.

Симптом первый: агент «помнит» API двухлетней давности. Попросишь обновить тесты — он использует методы фреймворка тестирования, которых давно нет, или идиомы, которые сменились три минорных версии назад. Модель обучена на срезе данных, и в этом срезе ваша библиотека выглядит так, как выглядела когда-то. Она не ходит в интернет за changelog, если её об этом не заставить.

Симптом второй: «готово» без проверки. Агент искренне верит, что код работает, если он «выглядит правильно». Напишет composer build в отчёте, не запустив его. Скажет «тесты должны пройти». Опаснее всего, что это звучит убедительно: нарратив уверенный, структура ответа правильная, код почти компилируется. Почти — ключевое слово.

Симптом третий: велосипеды. В каждом новом пакете агент изобретает собственный способ валидации, собственные имена исключений, собственную структуру тестов. Девяносто пакетов — девяносто велосипедов, если не держать это в узде.

Симптом четвёртый, самый коварный: агент не учится на опыте. Вот тут важный поворот. Человек, наступив на грабли, на всю жизнь запоминает, где лежат грабли. Агент — нет. Завтра, в новой сессии, у него будет чистая память, и он наступит на те же грабли с тем же энтузиазмом. Провёл сегодня два часа, отлаживая странное поведение PCRE? Завтра всё повторится байт в байт.

Из этого четвёртого симптома следует ключевой инсайт, который и определяет всю архитектуру моей системы:

Агент не учится — но агент перечитывает правила каждую сессию.

Это асимметрия, на которой можно строить. Всё, что не записано — не существует. Всё, что записано — будет исполнено буквально, слово в слово. Вопрос только в том, куда и как записывать, чтобы агент находил правила именно в тот момент, когда они нужны, и не захлёбывался ими в остальное время.

Почему обычные подходы не работают

Первое, что пробует каждый: «буду просто аккуратно писать промпты». Не работает. Промпт живёт одну сессию, а инцидент, который надо не повторять, живёт вечно. Второе: «напишу большой файл с инструкциями». Работает лучше, но упирается в контекстное окно: файл на 50 страниц либо не влезает, либо вытесняет из внимания сам код, который надо править. Третье: дообучить модель на своих правилах. Возможно, но это отдельная инженерия, инфраструктура и потеря контроля — а мне нужен был процесс, где каждое правило видно, версионировано и объяснимо.

Поэтому я пришёл к трёхслойной системе:

  1. Корневой AGENTS.md — конституция: принципы, конвенции, процессы для всех пакетов.
  2. AGENTS.md каждого пакета — локальные инварианты конкретной библиотеки.
  3. docs/evolved-rules.md — судебная практика: инциденты, превращённые в самодостаточные правила.

Про каждый слой дальше.


Часть 2. AGENTS.md как конституция и evolved rules как судебная практика

Юридическая метафора здесь не случайна, она описывает устройство точнее, чем техническая.

Конституция: корневой AGENTS.md

В корне монорепозитория лежит AGENTS.md — рулбук почти на полторы тысячи строк (снимок в toolkit). Формат де-факто стандартизирован: многие агенты (OpenCode и другие) читают файл с таким именем при старте сессии в каталоге. Claude Code читает CLAUDE.md, поэтому рядом лежит CLAUDE.md из одной строки — @AGENTS.md, импорт того же файла. Один источник правды для любого агента. Это точка входа, конституция: принципы, конвенции, процессы. Здесь живёт всё, что истинно всегда:

  • Обязательный набор из 25+ файлов на пакет: composer.json из шаблона, psalm.xml, infection.json5, CI-workflow'ы, двуязычный README, llms.txt.
  • Стиль кода: declare(strict_types=1), final readonly class, #[\Override], named arguments, psalm-аннотации определённого вида (non-empty-string, int<0, max>, array{...}-shapes).
  • Структура тестов на Testo, до уровня того, что Assert::same($actual, $expected) — аргументы в порядке, обратном PHPUnit.
  • Таблица именования: fluent-сеттеры with*, статические фабрики equal()/in(), исключения с сообщением без точки на конце.

Обратите внимание на плотность. Правила не «пишите чистый код», а ComparisonSpecification, whereEqual, 'Invalid operator "foo"'. Агенту нельзя объяснять на уровне ценностей — он не выведет ценности в конкретный идентификатор. Ему нужен идентификатор.

Каждый пакет поверх этого несёт собственный AGENTS.md с пакет-специфичными инвариантами — и у него есть четыре «золотых правила», третье из которых намеренно заменяется на первое package-specific правило безопасности. Шаблон золота:

  1. Verification is mandatory. Никогда не говорить «готово» без свежего зелёного composer build. «Should work» не считается.
  2. No suppressions. Никаких @psalm-suppress, никакого baseline. Только корневая причина.
  3. (заменяется на пакет-специфичное)
  4. Preserve the public contract. Изменил API — обнови README (оба, EN и RU) и тесты.

Первое правило закрывает «симптом второй» из предыдущей части. Оно звучит как буква устава, и это намеренно: агент исполняет букву. «Никогда не говорить "готово" без свежего зелёного composer build. Вставить вывод» — и агент вставляет вывод. Если вывода нет, внимательный ревьюер (то есть я) видит это за секунду.

Судебная практика: docs/evolved-rules.md

Конституция — это принципы. Но реальный опыт — это инциденты. Грабли, на которые наступили, с датами, источниками и точной формулировкой. Для них есть отдельный документ: docs/evolved-rules.md (снимок в toolkit), пятьдесят записей ER-001…ER-050. Формат записи строгий:

### ER-NNN — заголовок-урок
**Source:** какой пакет/инцидент это вскрыл
**Rule:** самодостаточный текст — будущий агент должен понять
его без какого-либо другого контекста
**Status:** active / superseded / obsolete

Требование самодостаточности — не эстетика. Агент, который читает ER-049 в сессии исправления миграции, не будет читать весь документ и всю историю. Правило обязано жить одно.

Важная деталь механики: evolved-rules.md в сессию сам не загружается — загружается только AGENTS.md. Поэтому конституция ссылается на судебную практику точечно, в том месте, где правило нужно: в секции про миграции стоит короткое «⛔ никакого литерального DEFAULT на TEXT» и ссылка «детали — ER-049». Агент, открывший задачу про миграцию, читает эту секцию и по ссылке идёт за подробностями. Это и есть ответ на вопрос «куда записывать»: принцип и запрет — в конституцию, контекст и разбор — в ER, связь — явной ссылкой.

Кто пишет записи? Тоже агент — но по моему указанию, после разбора инцидента. Сам по себе, без запроса, он рулбук не правит.

Вот несколько записей, каждая из которых — мини-детектив.

ER-001: якорь \z, а не $. В PCRE метасимвол $ совпадает не только в конце строки, но и непосредственно перед завершающим переводом строки. В пакете yii3-ab-testing-web cookie ab_id с содержимым «32 hex-символа + \n» проходила валидацию /^[0-9a-f]{32}$/ — и этот subject id с мусорным \n уезжал в логи и аналитику. Тихо, без единой ошибки. Исправлено в PR #8. Правило: валидация untrusted input якорится только через \z; в data provider теста обязателен кейс "value\n". Правило сразу ушло в конституцию — в секцию «Безопасность», рядом с whitelist-регулярками, которые им защищаются.

ER-049: DEFAULT на TEXT-колонке. MySQL и MariaDB отвергают литеральный DEFAULT на TEXT/BLOB/JSON ошибкой 1101. В монорепо единственный драйвер в require-dev — SQLite, и он такой DDL молча принимает. Итог: migrate:up на MySQL возвращается, не создав ни одной таблицы, а CI — зелёный, потому что CI тоже гоняет SQLite. Миграция ни разу не встречалась с движком, на котором она сломана. Нашёл это не CI, а целенаправленный sweep по всем *-db пакетам: один и тот же скопированный паттерн сидел в четырёх пакетах (yii3-tenancy-db#15, yii3-feature-flags-db#28, yii3-ab-testing-db#22, yii3-idempotency-db#18). Правило: пакет с миграциями обязан нести кросс-СУБДный интеграционный тест и ungated матричную джобу с MySQL и PostgreSQL service-контейнерами.

ER-044: миграции, которые молча ничего не делали. Девять *-db пакетов регистрировали миграции через setSourceNamespaces() — и метод migrate:up возвращал 0, не создав таблиц. Причина — yiisoft/db-migration сопоставлял namespace миграции с PSR-4 картой по строковому префиксу, и совпадение уводило в пакет-ядро. Unit-тесты строили миграции через Injector::make(), поэтому этот путь не трогали вообще: зелёный CI, пустая база. Починилось upstream-PR'ом в yiisoft/db-migration (вошёл в 2.1.0), но прежде чем его найти — надо было признать, что тест, который «проверяет миграции», не проверяет путь выполнения миграций.

ER-003: метрика, которая успокаивает. Про это — отдельная глава ниже, потому что это самый крупный урок за всю историю репозитория.

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

Ленивая раскатка: почему я не делаю волн PR'ов

Отдельная философия, которая родилась из практики. Когда появляется новое правило (скажем, «в CI у мутаций должен быть узкий фильтр путей»), теоретически можно пройтись по всем 90 пакетам и внести его сразу. Волной из 90 PR. Я делаю наоборот: правило попадает в templates/ для всех новых пакетов, а в опубликованные — лениво, довеском к первому же PR, который трогает этот пакет по другому поводу.

Это честнее по трём причинам. Во-первых, волна из 90 PR — это 90 раз запущенный CI, 90 ревью и ноль нового знания: изменения механические. Во-вторых, обязательные довески превращают любой содержательный PR в неповоротливого Франкенштейна, если требовать их сразу все; поэтому у меня строгий критерий ортогональности — «только доки» PR не тянет за собой CI-правки. В-третьих — и это главное — ленивая раскатка заставляет правило доказывать свою ценность: если оно ни разу не понадобилось ни в одном PR за полгода, может, оно и не нужно.

А чтобы агент не забывал о довесках, они прописаны в корневом рулбуке как таблицы «когда — что делать». Агент, открывающий PR в пакет с property-тестами и без корпуса регрессий в CI, обязан добавить их в этом же PR. Забыть не может: это в AGENTS.md, а AGENTS.md он перечитывает.


Часть 3. Честные гейты: как я узнал, что моя метрика мне лгала

Если бы меня попросили ещё летом 2026-го назвать самую сильную сторону этого репозитория, я бы сказал: мутационное тестирование. У каждого пакета порог MSI (Mutation Score Indicator) — 85–100, прогон Infection в CI на каждый PR. Мутационное тестирование проверяет не «исполняется ли код тестами», а «замечают ли тесты, если код сломать»: инструмент вносит в исходники механические повреждения (меняет < на <=, + на -, удаляет вызовы, инвертирует условия) и смотрит, падает ли хоть один тест. Мутант выжил — дыра в тестах.

И вот осенью 2026-го я прогнал по репозиторию Infection с флагом --with-uncovered — и картина рухнула.

Дыра в знаменателе

Обычный Infection мутирует только тот код, который покрыт тестами по данным coverage-отчёта. Так вот, тестовый фреймворк Testo (и это осознанное решение его дизайна) засчитывает тесту только тот код, который назван в его атрибуте #[Covers(...)] — а не всё, что тест реально исполняет. Если тест с #[Covers(Foo::class)] через композицию вызывает и Bar, мутанты Bar не создаются вовсе. Не «не убиваются» — не создаются. В отчёте про них просто нет строк.

На пакете json-ld это выглядело так: без флага — 1169 мутантов и видимый MSI 97%. С флагом — 2726 мутантов, из которых 1557 Not Covered, и честный MSI — 41%. Больше половины мутантов не существовало для гейта. При пороге minMsi: 92. Доводку до порога можно посмотреть в json-ld#3.

Полный аудит по монорепо (отчёт целиком; 75 пакетов с результатом из 84 запущенных):

  • 42 348 — всего мутантов с флагом
  • 7 874 (19%) — из них раньше были невидимы (Not Covered)
  • 12% — медиана невидимой доли по пакету
  • 12 п.п. — медиана падения MSI (видимый → честный)
  • 4 из 75 — пакетов, где честный MSI не ниже их текущего minMsi

Четыре из семидесяти пяти. Метрика, на которой держался весь гейт качества, показывала красивые 92–100% — и при этом лгала в среднем на двенадцать пунктов.

Самое неприятное в этой истории — не сама дыра, а то, что она успокаивала. В отчёте было Not Covered: 0 и Mutation Code Coverage: 100%. Ноль! Всё покрыто! Сообщить о непокрытом коде нечему — потому что мутанты там не создаются, а не потому что они убиты. Есть категорическая разница между «проверено и работает» и «не проверял, но ошибок не вижу». Метрика не различала эти состояния.

Дальше — механика исправления, и она поучительна сама по себе, потому что состоит из маленьких честностей.

Шаг 1: флаг обязателен. --with-uncovered теперь в команде мутаций у всех новых пакетов, у опубликованных — лениво, при первом касании. И порог не снижается: недостающие мутанты закрываются #[Covers] на тестах, которые код уже исполняют, плюс новыми тестами.

Шаг 2: нельзя убить — убери из знаменателя, но не молча. Оказалось, есть мутанты, неубиваемые в принципе. Два случая, два механизма:

  • PublicVisibility на строке сигнатуры метода без параметров — там нет исполняемого опкода, мутант всегда Not Covered, никакие тесты его не убьют. Пилот на pinned-http-client: 4 из 4 таких мутантов, убито — 0. Эти мутаторы (PublicVisibility, ProtectedVisibility) отключены в шаблонном конфиге целиком — с записанным обоснованием и цифрами пилота.
  • Дефолты параметров в сигнатуре (private int $x = 100,) — мутанты на них игнорируются регуляркой. Здесь правило требует отчитываться: в PR пишется MSI до и после игнора отдельно, число Ignored не скрывается, а раз в несколько релизов игнор снимается на один прогон — проверить, не стали ли эти мутанты убиваемыми.

Игнор — это признание «этот кусок знаменателя не про качество тестов», и оно должно быть видимым, а не закопанным в конфиг.

Шаг 3: локальный прогон обязан совпадать с CI. Поймал расхождение: локально 95%, в CI 93%. Причина — в CI выключен zend.assertions, \assert() в коде не компилируется, его мутанты там Not Covered, а локально assertion'ы исполняются и мутанты убиваются тестами. Теперь перед мутационным прогоном в контейнере пишется ini с выключенными assertion'ами — чтобы локальная цифра была той же, что в гейте, иначе запас над порогом посчитан от неверной базы.

Шаг 4: этика порога. Столкнулся с соблазном: у пары пакетов честный MSI настолько ниже порога, что доводка — недели работы. Понимание искушения «просто снизить minMsi под фактически достигнутое» привело к правилу, которое я считаю важнейшим в этой главе: порог не снижается, чтобы легализовать текущее состояние. Снижение — крайняя мера по явному решению владельца, не ниже 85, с записью причины в конфиг и в статус-файл, на виду. Агенту запрещено снижать порог самому — именно потому, что агент всегда выберет путь наименьшего сопротивления, если его не ограничить явно.

Корпус регрессий: property-тесты, которые помнят

Вторая линия обороны — property-based тестирование. Вместо фиксированных кейсов «input A → output B» генератор строит сотни случайных входов, а тест проверяет инвариант: decode(encode(x)) == x для любого x; задержка backoff всегда в [0, cap] и не убывает; детерминизм хэш-бакетинга. Для этого в монорепо живёт собственное семейство библиотек property-testing-core, -testo и -phpunit — но лонгрид не про них, а про одну деталь инфраструктуры, которая решает главную проблему property-тестов: они стохастические.

Баг, пойманный случайным входом, воспроизводится с вероятностью — условно, раз в триста прогонов. Если CI-раннер упал на сгенерированном контрпримере, а перезапуск прошёл — баг «исчез». Чтобы контрпример не терялся, property-движок пишет каждое фальсифицированное свойство в корпус на диске (build/property-db), а CI восстанавливает корпус из кэша GitHub Actions перед прогоном и сохраняет обратно — даже когда прогон красный.

Именно с этим корпусом связана моя любимая находка от ревью-бота CodeRabbit (в yii3-ab-testing#29). Комбинированный actions/cache сохраняет кэш только на зелёном джобе (post-if: "success()"). А запись в корпус делает ровно падающий прогон: свойство сфальсифицировалось → job красный → post-шаг не выполнился → контрпример не сохранён никогда. То есть сломано было ровно то, ради чего механизм существовал: «баг зафиксировался — регрессия ловится навсегда» превращалось в «баг видел CI один раз и забыл». Лечится разделением на actions/cache/restore перед шагом и actions/cache/save с if: ${{ !cancelled() }} после. Плюс run_attempt в ключе кэша — иначе при re-run ключ уже занят, save тихо завершается warning'ом, и снова ничего не сохраняется.

Три строки YAML, две скрытые семантики, ноль видимых ошибок. Классика.


Часть 4. Релизы без права на ошибку

Теперь про то, что происходит, когда код уже написан, протестирован, прогнан через мутации — и его пора публиковать. Здесь система устроена вокруг одного жёсткого факта внешнего мира:

Packagist блокирует повторную загрузку пере-созданного тега. Навсегда.

Удалил тег v1.2.3 и поставил на другой коммит — всё, версия 1.2.3 для Packagist помечена Upstream re-tag blocked до конца времён. Единственный выход — выпустить 1.2.4. Это не политика моего репозитория, это свойство пейзажа, и оно диктует всё остальное: тег ставится ровно один раз, на проверенный коммит, и никогда не двигается.

Отсюда процесс, который на первый взгляд выглядит параноидальным, а на второй — минимально достаточным.

Тег — только на проверенной истории. Релизный workflow перед созданием GitHub Release убеждается, что тегированный SHA — предок master и что матричные check-runs PHP 8.3/8.4/8.5 на этом SHA завершились успехом. До этой проверки workflow публиковал Release для любого тега — включая поставленный на коммит, чей CI никогда не был зелёным: build-воркфлоу срабатывает на PR и push в master, а по тегу не срабатывает ничего, и проверять было некому.

Тег — после merge, не до. Squash-merge создаёт новый SHA. Тег, поставленный на ветку PR до merge, указывает не на тот коммит, который попал в master. Поэтому релизный коммит проводится через PR, тег ставится на post-merge HEAD, и перед push проверяется достижимость: git merge-base --is-ancestor vX.Y.Z origin/master.

Формат changelog — часть гейта. Roave Backward Compatibility Check сверяет публичный API с последним тегом и краснеет при ломающих изменениях. Осознанный мажор — это когда красный отчёт ожидаем. Как CI понимает, ожидаем ли он? По CHANGELOG.md: если верхний заголовок объявляет мажор выше последнего тега (а пока пакет на 0.x — минор) — ломающий PR легитимен; если там ## Unreleased — красный, и это правильно: под Unreleased ломающий PR должен стоять, как часовой. Следствие, которое неочевидно, пока на него не наступишь: релизный PR обязан переименовывать Unreleased в версию с датой, а не добавлять свой заголовок рядом. Иначе extractor release-notes обрывается на застрявшем ## Unreleased, и релиз молча теряет описание изменений. Два реальных случая — openapi-contract v0.7.0 потерял решение по HTTP-заголовкам, yii3-mcp v2.2.0 потерял три серверных параметра — пришлось восстанавливать вручную через gh release edit. Теперь на «ровно один ## Unreleased, выше всех версий» стоит отдельная проверка в аудиторском скрипте.

Первый релиз — без защиты, тег и защита — после зелёного CI. Классическая ловушка молодого репозитория: поставить тег и включить branch protection сразу с первым пушем. Если первый CI-прогон красный (например, локальный образ с PHP 8.5 не ловит то, что упадёт на 8.3), тег уже указывает на сломанный коммит, а починить master напрямую нельзя — только через recovery-PR, после которого тег приходится удалять. См. выше, чем это кончается. Поэтому порядок жёсткий: master-пуш без защиты → зелёный CI (красный чинится прямо в master) → тег → защита ветки.

Против параноидального чтения этого раздела есть простой аргумент: каждый пункт появился после конкретного инцидента или конкретного ревью, ни один — впрок.

CI, который не подведёт supply chain

Коротко про hardening, потому что это тоже часть «нет права на ошибку». Все uses: во всех workflow — 40-символьные SHA коммитов, никаких плавающих @v4: тег в чужом репозитории — это moving target, который может указывать куда угодно через минуту после того, как вы на него сошлись. Обновление — только через Dependabot, который умеет бампать SHA, сохраняя комментарий # v4. На каждом checkout — persist-credentials: false, чтобы OAuth-креды не оседали в .git/config и не утекали в артефакты. Аудит — zizmor --persona=auditor .github/ в списке релизных проверок.

Звучит как избыточность для библиотек, которые скачивают два с половиной человека. Но «два с половиной человека» — это тоже supply chain. CI — это место, откуда выходят релизы: скомпрометированный action в workflow с доступом к репозиторию может подменить код до тега, и тогда composer require у потребителя притянет в vendor/ уже не мой код, а код, который будет исполнен с правами их приложения. Цена дисциплины — один вечер на настройку шаблонов; цена её отсутствия — не ограничена.


Часть 5. Что переносится, а что нет

Я обещал честный разбор. Вот он.

Что работает у кого угодно — с людьми, без агента

Evolved rules как формат. Заведите файл инцидентов с самодостаточными записями «источник → правило → статус» — и настойчиво требуйте самодостаточности. Это стоит дорого (правило на абстрактном уровне писать легче), но окупается с первого раза, когда правило читает человек, не знающий контекста. А через полгода «человек без контекста» — это вы сами.

Честность знаменателя. Не только у Infection. Покрытие, которое считаете вы, и покрытие, за которое отвечает гейт — это часто разные числа, и разница между ними — место, где живут невидимые дыры. Проверьте: считает ли ваш coverage-инструмент то, что реально исполняется, или то, что заявлено исполняющимся. Аудит «одной командой» (infection --with-uncovered по всем пакетам) показался мне приемлемым по стоимости — и окупился на первой же цифре.

Этика порогов. Метрика с порогом, который снижается под фактически достигнутое, — не метрика, а украшение. Снижение порога — публичное решение с записанной причиной или ничто.

Релизная дисциплина под внешними ограничениями. Packagist, npm, Docker Hub — у всех необратимость публикации общая. «Тег один раз, на проверенный SHA, после merge» — минимальный процесс, который эту необратимость уважает. Остальное оформляется в скрипты и проверки.

Что специфично для работы с агентом

Сама трёхслойная система правил. Человеку-коллеге достаточно Slack-поста «осторожно с $ в PCRE» — он запомнит суть. Агенту нужен \z в файле, с примером и требованием data provider кейса. AGENTS.md как формат существует потому, что существует агент, который его читает каждый раз. Нет агента, который читает, — формат мёртв, и тогда весь вес несут code review и CI, как в старые добрые.

Ленивая раскатка как этика. Люди лучше переносят волны одинаковых PR (и даже находят в них медитацию). Агент — хуже: механические PR без нового знания — это чистый расход контекста и риск дрейфа. Довески к содержательным PR — компромисс, рассчитанный именно на связку «человек формулирует правило → агент разносит его по пакетам».

Запрет агенту снижать пороги. Человеку можно дать право снизить minMsi с объяснением — он понимает, что объяснение будет прочитано. Агент объяснение сгенерирует, красивое и убедительное, какое угодно. Поэтому правило для агента категорично: никогда. Снижение — акт владельца, и точка.

Где это ломается

Не буду изображать, что система серебряная.

Правила не покрывают незнание. ER-049 (DEFAULT на TEXT) появился только после того, как пакеты целенаправленно проверили против реального MySQL, — до этого ни одно правило о нём не знало. Никакое количество внутренних правил не заменяет контакт с реальностью — правила консервативны, они умеют только не повторять старое.

Объём контекста — конечный ресурс. Чем больше файлов правил, тем больше бюджета сессии съедает рулбук вместо кода. Мне приходится регулярно сжимать: переносить отточенные правила из evolved-rules обратно в конституцию (когда они стали принципами), сводить дубли, отправлять устаревшее в obsolete. Это работа, и она не делается сама.

Однонаправленность доверия. Система рассчитана на то, что агент исполняет правила, а не переписывает их под себя. В моей среде агент правит AGENTS.md и evolved-rules только по явному запросу — но это свойство среды, а не закон природы. В другом сетапе первый же сообразительный агент «оптимизирует» свои ограничения.


Вместо заключения

Вернёмся к первой фразе: 90 пакетов, и пишет их в основном AI-агент. Сейчас, после всего рассказанного, я могу сформулировать, почему это работает, одной строкой:

Я перестал пытаться научить агента программировать — и начал строить систему, в которой программировать плохо очень трудно.

Агент не помнит ER-001? Ничего: он его прочитает. Агент склонен сказать «готово» без прогона? Правило номер один конституции требует свежий вывод. Агент не видел, что метрика врёт? Я видел, и теперь знаменатель честный, а порог неприкосновенен — для агента. Агент поставил бы тег до merge? Процесс не даст.

Каждый слой системы — от конституции до строки в YAML — это ответ на конкретную ошибку, совершённую когда-то. Пятьдесят ответов на данный момент. Через год будет шестьдесят. Это не признак незавершённости — это признак жизни: система дышит, потому что каждый инцидент оставляет в ней след.

Люди в команде делают то же самое. Просто медленнее, и забывая.


Ссылки