Стандарт кодирования для AI-агентов на PHP-проектах

Главная цель стандарта кодирования — поддержание высокой скорости разработки и удобной поддержки кода в долгосрочной перспективе. Скорость достигается за счёт единообразия: разработчик и AI-агент сразу знают, где лежит DTO, как устроен хендлер, какие зависимости допустимы между слоями. Поддержка — за счёт архитектурных подходов, зафиксированных в конвенциях: изоляция слоёв, чистые доменные модели, строгие границы модулей.

AI-агенты склонны отклоняться от конвенций. Поэтому соблюдение конвенций проверяется автоматически: сниффы PHP CodeSniffer и правила Deptrac ловят нарушения до кодревью.

---

Конвенции

Документация описывает принципы, паттерны, слои, модули, тестирование и структуру Symfony-приложения. Служит справочником для команды и AI-агентов.

Полное содержание: docs/conventions/index.md.

---

Автоматические проверки

Соблюдение конвенций проверяется через PHP CodeSniffer и Deptrac — без ручного кодревью структуры.

Markdown-валидация

Проверка документации ведётся двумя инструментами:

• composer validate-docs — проверяет конвенции внутри каталога docs/conventions/: структуру front matter, именование файлов (kebab-case), обязательные секции и ссылки между документами каталога.
• composer validate-md-links — проверяет ссылки между Markdown-файлами всего проекта (пути и якоря). Область проверки настраивается через файл конфигурации .md-links.php. Подробнее.
• composer validate-language — ищет английские фразы в русскоязычном тексте Markdown/text-файлов (англицизмы вида «persisted rows»). Техническая терминология и code blocks исключаются. Настраивается через секцию language в .coding-standard.php. Подробнее.

PHP CodeSniffer-сниффы

Снифф	Что проверяет
DtoStructureSniff	DTO — final readonly, только promoted-параметры в конструкторе, без методов и свойств
EnumStructureSniff	Enum — чистый (без методов, констант, трейтов), case'ы в camelCase
ValueObjectStructureSniff	Value Object — final readonly, неизменяемый, приватный конструктор, статические фабрики
CommandQueryStructureSniff	Command/Query — конструктор только с promoted-параметрами, без свойств и методов
CommandHandlerStructureSniff	CommandHandler — только __invoke, без публичных свойств
QueryHandlerReturnTypeSniff	QueryHandler — должен возвращать Result или ResultDto
CommandHandlerReturnTypeSniff	CommandHandler — должен возвращать void или Result
UseCaseNamingSniff	UseCase — обязательный суффикс; имя файла и неймспейс совпадают с путём
GlobalFunctionCallStyleSniff	Глобальные функции вызываются без обратного слеша и без use function

Deptrac-правила

Правило	Что проверяет
ServiceContractDependencyRule	Infrastructure зависит только от Domain-интерфейсов, не от конкретных классов
CrossModuleDomainRule	Домен одного модуля не зависит от домена другого — только через Application DTO

Готовый depfile.yaml с правилами для DDD-слоёв и модульных границ: config/deptrac/. Копируется в проект через coding-standard-init или вручную.

PHPStan-правила

Пользовательское PHPStan-расширение (Collector + Rule) для межфайловых проверок:

Правило	Что проверяет
DtoReuseRule	Находит DTO в общей папке модуля (Module\{ModuleName}\Application\Dto), которые по факту использует только один use case, и предлагает переложить их рядом с владельцем.

Подключение: потребитель добавляет phpstan/phpstan в require-dev (сосуществует с Psalm) и расширение подхватывается автоматически через phpstan/extension-installer, либо вручную через includes: в phpstan.neon:

includes:
    - vendor/prikotov/coding-standard/phpstan-rules.neon

Конвенция размещения DTO: docs/conventions/core-patterns/dto.md.

Примеры конфигураций: docs/conventions/examples/

Файл	Назначение
phpcs.xml.dist	PHP CodeSniffer
phpunit.xml.dist	PHPUnit
phpmd.xml	PHPMD
phpstan.neon.dist	PHPStan
psalm.xml	Psalm
Makefile	Команды проверки (make check)

---

Установка

composer require --dev prikotov/coding-standard

В состав пакета входят:

• Сниффы — PHP CodeSniffer-правила, работают сразу из vendor/
• Deptrac-правила — пользовательские правила для deptrac
• PHPStan-правила — пользовательские правила для phpstan
• Конфигурации — depfile.yaml для Deptrac, phpcs.xml.dist для PHPCS, phpstan.neon.dist для PHPStan
• Шаблоны исключений — типовые классы и интерфейсы, копируются с подстановкой namespace проекта
• Конвенции — документация, копируется командой coding-standard-init

Подключение PHPCS

<config name="installed_paths" value="vendor/prikotov/coding-standard"/>
<rule ref="PrikotovCodingStandard"/>

Копирование конвенций в проект

php vendor/bin/coding-standard-init

По умолчанию существующие файлы не перезаписываются. Флаг --force включает перезапись.

php vendor/bin/coding-standard-init /path/to/project --docs-path=docs/ddd --deptrac-path=config/depfile.yaml --force

Копирование типовых исключений

Шаблоны исключений хранятся в config/exceptions/ и копируются в проект с подстановкой имени namespace.

php vendor/bin/coding-standard-init --project-name=Task

Это создаст файлы в src/Common/Exception/ с namespace Task\Common\Exception.

Опция	Описание
--project-name=Task	Имя проекта для namespace (обязательно для исключений)
--exceptions-path=src/Common/Exception	Путь копирования (по умолчанию)
--no-exceptions	Пропустить копирование исключений

Без --project-name исключения пропускаются, остальные файлы копируются как обычно.

---

License

MIT