Удобство для Claude Code и API-документация

Статус: проектирование. CMS разрабатывается и сопровождается через Claude Code — значит она должна быть читаемой для AI-агента: предсказуемая структура, богатые контракты, и обширная автоматизированная API-документация. Это не «приятный бонус», а требование: чем понятнее CMS для Claude Code, тем быстрее и безопаснее разработка.

Почему DX для AI — отдельное требование

Студия — один разработчик + Claude Code. Скорость и качество зависят от того, насколько легко агент ориентируется в кодовой базе, находит нужное и не ломает соседние модули. CMS, спроектированная под AI-DX, экономит лимиты (меньше чтения кода на понимание) и снижает риск регрессий.

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

Принцип	Как реализуем
Предсказуемая структура	Единый скелет модуля: src/, config/, routes/, resources/, манифест. Агент знает, где что лежит, не читая весь модуль
Явные контракты	Интерфейсы (BlockContract, PaymentGateway, ModuleContract) — агент читает контракт, а не реализацию
Манифест как карта	module.json (requires/provides/permissions/routes) — агент видит границы модуля из одного файла
Строгая типизация	declare(strict_types=1), типы параметров/возврата — агент точно знает сигнатуры
Реестры вместо магии	BlockRegistry/WidgetRegistry/хуки в явном реестре (cms:hooks) — агент видит все точки расширения списком, а не грепом по кодовой базе
Laravel Boost	Каждый сайт с laravel/boost — агент получает схему БД, логи, роуты структурированно (1% лимита вместо docker-exec)

Самодокументируемость через CLAUDE.md

CMS поставляет иерархию CLAUDE.md, чтобы агент сразу знал правила:

• ядро привозит корневой CLAUDE.md с архитектурой и правилами CMS;
• каждый модуль — свой CLAUDE.md (что делает, контракты, точки расширения, зависимости) и docs/module.md — человекочитаемое описание работы модуля и его взаимосвязей (схема данных, события, настройки, обратные зависимости, поведение при выключении). Из этих файлов docs-site собирает по странице на модуль — источник живёт в пакете рядом с кодом и обновляется тем же PR, что и код;
• skeleton клиента — проектный CLAUDE.md (специфика сайта, что не трогать).

Плюс машинно-читаемый реестр: команда php artisan cms:map выдаёт агенту карту — установленные модули, их версии, зависимости, точки расширения, роуты. Одна команда вместо десятка grep-ов.

Автоматизированная API-документация

Ядро headless-ready — API есть у всех сущностей. Документация к нему генерируется автоматически из кода, не пишется руками:

Что	Инструмент/подход	Результат
REST OpenAPI-спека	Атрибуты/аннотации на контроллерах + генератор (Scramble / L5-Swagger)	openapi.json из кода, всегда актуален
Интерактивная песочница	Swagger UI / Scalar	Живой пробник эндпоинтов в браузере
GraphQL-схема	SDL из типов (Lighthouse)	Интроспекция + GraphiQL
SDK-клиенты	Автоген из OpenAPI	Готовые клиенты для мобильных/интеграций
Постман-коллекция	Экспорт из OpenAPI	Для ручного тестирования
Схема БД	laravel/boost database-schema	Структурированно для Claude Code
Карта роутов	php artisan route:list + cms:map	Все эндпоинты списком

Принцип «docs-as-code»: документация живёт в коде (атрибуты, типы, PHPDoc) и генерируется в CI при каждом релизе. Расхождение кода и доков невозможно — они один источник. Это критично для парка: у каждой версии ядра/модуля — своя актуальная спека.

Автогенерация из контрактов

Поскольку сущности и поля описаны декларативно (движок полей, BlockRegistry со схемами), из них генерируется не только API-спека, но и:

• справочник блоков — все типы блоков, их поля, demo-props (из BlockRegistry);
• справочник событий/хуков — все точки расширения (из реестра cms:hooks);
• справочник permissions — все права (из деклараций модулей + Shield);
• справочник настроек — все ключи setting() с типами и дефолтами.

Эти справочники — и для человека (админ-панель «Разработчику»), и для Claude Code (машинно-читаемый JSON).

Цикл разработки: Claude Code пишет 100% кода

CMS проектируется под то, что весь код планирует и пишет Claude Code — среда разработки обязана быть для него самодостаточной:

Среда монорепо

• orchestra/testbench — каждый пакет (ядро, модуль) тестируется в изоляции, без полного приложения: composer test внутри пакета поднимает testbench-окружение, гоняет Pest + контрактные тесты cms-testing. Один вызов — весь вердикт;
• dev-playground — skeleton-сайт в монорепо (playground/) с path-репозиториями на все пакеты: живой сайт для ручной и браузерной проверки, с демо-контентом профиля;
• в playground предустановлены laravel/boost и .mcp.json (по процедуре студии MCP-SETUP.md) — агент получает схему БД, логи, роуты, tinker через MCP с первой сессии;
• генераторы: cms:make:module, cms:make:block, cms:make:widget, cms:make:field-type — скаффолд по контракту (структура, манифест, тесты, CLAUDE.md и docs/module.md заготовкой). Агент не копирует структуру руками — генерирует.

Петля работы агента над модулем

1. читает ТЗ модуля (/cms-v2/modules/) + донорский код по пути из реестра
   (обязательная ссылка на образец — [реестр](/cms-v2/modules-registry#пути-к-донорскому-коду-проверено-по-фаиловои-системе));
   код пишется по спекам студии specs/laravel_13 (модели/контроллеры/миграции/тесты)
2. cms:make:module → скаффолд по контракту
3. TDD: контрактные тесты уже красные из коробки → пишет код до зелёного
   (composer test = Pest + cms-testing + larastan, один вызов)
4. проверка в playground: boost (логи/схема/routes) + browser-проверка
5. cms:doctor + контрактный прогон → публикация в Satis

Правила MCP-экономии (наследуются из практики студии)

• логи/схема/доки Laravel → laravel-boost (дёшево); SQL → postgres MCP; artisan/composer → docker exec — в этом порядке (LIMITS-OPTIMIZATION);
• вся диагностика CMS — структурированные команды (cms:map, cms:hooks, cms:doctor, cms:cache:inspect, cms:theme:resolve) с --json-флагом: агент читает машинный вывод, а не парсит человекочитаемые таблицы;
• ошибки ядра — доменные исключения с текстом «что делать» — агент чинит по сообщению, не по stack trace.

Что закладываем в контракт модуля

Чтобы автодокументация и AI-DX работали, модуль обязан декларировать:

• манифест module.json с requires/provides/permissions/routes/events;
• OpenAPI-атрибуты на публичных API-эндпоинтах;
• CLAUDE.md модуля (назначение, контракты, точки расширения);
• типизированные события (не строковые) — чтобы агент видел, на что подписываться;
• схемы блоков/полей в реестре (не хардкод) — чтобы попадали в автосправочник.

Это часть контракта модуля — без этих деклараций модуль не проходит валидацию.

Итог

CMS «читаема для Claude Code» = предсказуемая структура + явные контракты + машинные карты (cms:map, Boost) + автогенерируемая API-документация из кода. Каждое требование к модулю (манифест, типизированные события, OpenAPI-атрибуты, CLAUDE.md) служит двум целям сразу: корректной работе CMS и понятности для AI-агента. См. иерархию зависимостей и расширяемость.