Процесс
Большую часть кода в этих пакетах пишет агент. Он работает внутри свода правил, которым владею я, за гейтами, которые он не может понизить, и не мержит, не ставит теги и не публикует. Свод правил и инструменты открыты снимком: php-package-toolkit. Тот же цикл построил cska.in. Полная версия с инцидентами подробно: Как я заставил AI-агента поддерживать 90 PHP-пакетов и не сойти с ума.
Исходная мысль: агент не учится на опыте, но перечитывает правила в начале каждой сессии. Поэтому всё, что не должно повториться, записано в форме, которую он исполняет буквально.
Три слоя правил
| Слой | Что в нём |
|---|---|
Корневой AGENTS.md | Конституция, больше тысячи строк. Обязательный набор файлов, стиль кода, структура тестов, именование, CI, процесс релиза. Конкретные идентификаторы, а не ценности: 'Invalid operator "foo"', а не «пиши чистый код». |
AGENTS.md пакета | Локальные инварианты. Правило 3 из четырёх золотых заменяется одним правилом безопасности, специфичным для пакета, до первого коммита. |
docs/evolved-rules.md | Судебная практика. Около пятидесяти записей: источник, самодостаточное правило и статус. Агент читает одну запись по ссылке, поэтому каждая должна стоять сама по себе. |
Свод правил агент правит только по моей просьбе. Правило 1 конституции: никогда не говорить «готово» без свежего зелёного composer build с вставленным выводом.
Записи, которые пришли из реальных инцидентов:
$в PCRE совпадает перед завершающим переводом строки. Cookie из 32 hex-символов плюс\nпроходила валидацию и попадала в логи и аналитику. Якорь\z.DEFAULTна TEXT-колонке. MySQL отвергает его, SQLite принимает. На MySQL миграции не создавали таблиц, а CI на SQLite оставался зелёным.- Миграции, которые молча ничего не делали. Совпадение по префиксу PSR-4 уводило поиск namespace в пакет-ядро в девяти
*-dbпакетах. Исправлено вyiisoft/db-migration2.1.
Гейты
Каждый пакет проходит один и тот же гейт: Psalm level 1 без подавлений и baseline, тесты на Testo (на PHPUnit у PHPUnit-адаптера), проверка обратной совместимости перед мажором и мутационный порог. Property-тесты покрывают алгебраические законы и инварианты там, где они есть.
Мутационная метрика врала
Testo засчитывает тесту только код, названный в его #[Covers], а Infection по умолчанию мутирует только покрытый код. Код вне любого #[Covers] не давал мутантов, и в отчёте было Not Covered: 0.
Замер с --with-uncovered | |
|---|---|
json-ld | раньше 1 169 мутантов и 97%; теперь 2 726 мутантов и 41% |
| Всё монорепо | 42 348 мутантов, 19% из них раньше были невидимы |
Пакетов, где честный MSI дотягивал до собственного minMsi | 4 из 75 |
У исправления свои правила:
- Флаг включён у новых пакетов. Опубликованные получают его, когда PR их касается, и доводятся до прежнего
minMsi, не ниже. - Порог не снижают, чтобы узаконить текущее состояние. Снизить может только владелец, не ниже 85, с причиной в
infection.json5. Агент этого не делает никогда: он напишет убедительное оправдание чему угодно. - Мутанты, которых нельзя убить (видимость на строке сигнатуры без опкода, значения по умолчанию в сигнатуре конструктора), исключены в общем конфиге, а в PR указывается MSI до и после игнора. Число
Ignoredне прячется. - Локальный прогон должен совпадать с CI. В CI
zend.assertionsвыключен, поэтому мутантыassert()там не покрыты. Локально тот же прогон сначала отключает assertions.
Property-тесты помнят
Случайный вход, ломающий свойство, воспроизводится случайно. Движок пишет каждое опровергнутое свойство в корпус на диске, а CI восстанавливает этот корпус из кеша перед прогоном и сохраняет после, даже когда прогон упал. Комбинированный cache-action не сохраняет кеш на красном job, а именно такой прогон и записал контрпример. Это нашёл ревью-бот; теперь restore и save разделены.
Релизы
Packagist навсегда блокирует пере-тегированную версию, поэтому тег ставится один раз, на проверенный коммит, и не двигается.
- Тег ставится на post-merge коммит
master, после слияния PR. Релизный workflow проверяет, что тегированный коммит является предкомmasterи что check-runsPHP *на нём прошли. CHANGELOG.mdчасть гейта. Ломающий PR законен только когда верхний заголовок объявляет мажор выше последнего тега или минор, пока пакет на 0.x.- Тег не ставится, если
src/не менялся, потому что Composer-dist был бы байт-в-байт тем же. - CI укреплён: каждый
uses:закреплён 40-символьным SHA коммита,permissions: contents: read,persist-credentials: false, аудит черезzizmor. - Новое правило доходит до опубликованных пакетов лениво, довеском к следующему PR, который их касается, а не волной из девяноста механических PR.
Инструменты
| Инструмент | Что делает |
|---|---|
bin/package-audit | Детерминированный аудит соглашений: обязательные файлы, @api на каждом типе, #[Covers] на каждом тест-классе, без подавлений, один ## Unreleased. |
bin/dev | Пакетные операции над многими пакетами: сборка, git, записи в changelog, репликация шаблонов. |
bin/config-merge-harness | Сливает DI и params ядра и бэкендов так, как это делает настоящий config-плагин, чтобы поймать два vendor-пакета на одном ключе. |
bin/verify-clean-clone | Клонирует пакет во временный каталог и гоняет установку и сборку в Docker. |
bin/record-openapi-corpus | Записывает сгенерированный OpenAPI-трафик вместе с намерением, валиден он или нет, как корпус тестов валидатора. |
bin/build-digest | Пишет полный лог сборки в файл и возвращает одну строку PASS или FAIL, что экономит контекст агента. |
| Хуки Claude Code | Shell-страж опасных команд и аудит перед коммитом, срабатывающий перед каждым git commit. |
Что остаётся человеку
API и границы слоёв проектирую я, решаю, как должен выглядеть context с дедлайнами или детерминированный A/B-движок, ревьюю каждое изменение и отвечаю за релиз. Агент не мержит, не ставит теги и не публикует без моей явной команды.
Где это ломается
- Правила не покрывают незнание. Запись про
DEFAULTна TEXT появилась только после проверки пакетов на настоящем MySQL. - Контекст конечен. Свод правил приходится время от времени сжимать: зрелые правила переезжают в конституцию, дубли сливаются, устаревшие помечаются obsolete.
- Доверие односторонне. Всё работает потому, что агент исполняет правила, а не переписывает их. Это свойство моей среды, а не закон.