Skip to content

Процесс ​

Большую часть кода в этих пакетах пишет агент. Он работает внутри свода правил, которым владею я, за гейтами, которые он не может понизить, и не мержит, не ставит теги и не публикует. Свод правил и инструменты открыты снимком: 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-migration 2.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 дотягивал до собственного minMsi4 из 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-runs PHP * на нём прошли.
  • 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 CodeShell-страж опасных команд и аудит перед коммитом, срабатывающий перед каждым git commit.

Что остаётся человеку ​

API и границы слоёв проектирую я, решаю, как должен выглядеть context с дедлайнами или детерминированный A/B-движок, ревьюю каждое изменение и отвечаю за релиз. Агент не мержит, не ставит теги и не публикует без моей явной команды.

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

  • Правила не покрывают незнание. Запись про DEFAULT на TEXT появилась только после проверки пакетов на настоящем MySQL.
  • Контекст конечен. Свод правил приходится время от времени сжимать: зрелые правила переезжают в конституцию, дубли сливаются, устаревшие помечаются obsolete.
  • Доверие односторонне. Всё работает потому, что агент исполняет правила, а не переписывает их. Это свойство моей среды, а не закон.