Dandy Code Skills 3.0: как научить AI-агента писать и проверять PHP-код аккуратнее

AI-агенты уже неплохо пишут код. Но «код работает» и «код удобно поддерживать» — всё ещё разные вещи.

Просишь агента поправить один метод, а он заодно создаёт сервис, DTO, интерфейс, фабрику и три слоя абстракций. Формально задача решена. Фактически в проекте стало больше кода, больше связей и больше мест, где что-нибудь может сломаться.

Чтобы реже получать такие архитектурные сюрпризы, я собрал Dandy Code Skills — набор инструкций для AI-агентов, основанный на книге «Денди-код».

Недавно проект обновился до версии 3.0. Структура стала проще: вместо четырёх публичных skills осталось два понятных сценария — работа с кодом в денди-стиле и проверка изменений перед коммитом.

Что такое Dandy Code Skills

Skill — это инструкция, которую AI-агент подключает к задаче. В ней описано, на что смотреть, в каком порядке работать, какие ограничения соблюдать и как оформлять результат.

Без skill приходится каждый раз писать длинный промпт:

Изучи стиль проекта, не меняй бизнес-логику, не создавай лишние абстракции, проверь имена, вложенность, условия и комментарии, используй возможности Laravel и предложи только безопасные изменения.

После установки Dandy Code Skills можно написать проще:

Проверь этот модуль в денди-стиле.

или:

Проверь diff перед коммитом, как денди.

Агент получает не абстрактное требование «сделай красиво», а конкретный рабочий процесс.

Что изменилось в версии 3.0

В ранней версии проекта было четыре публичные точки входа:

• dandy-style;
• dandy-review;
• dandy-commit;
• dandy-breakdown.

На практике границы между dandy-style, dandy-review и dandy-breakdown были слишком условными. Пользователю приходилось сначала решать, какой именно skill вызвать, хотя это вполне может определить сам агент по контексту.

В версии 3.0 осталось два публичных skill:

Skill	Для чего нужен
dandy-style	Ревью проекта, модуля, файла или отдельного метода, поиск точек улучшения и план безопасного рефакторинга
dandy-commit	Проверка текущего git diff перед коммитом, безопасная очистка изменений и подготовка сообщения коммита

Старые dandy-review и dandy-breakdown удалены. Их задачи теперь выполняет dandy-style: режим работы выбирается по запросу и переданному контексту.

Если раньше вы использовали:

/dandy-review
/dandy-breakdown

теперь достаточно:

/dandy-style

Либо можно вообще не вызывать команду напрямую, а упомянуть Денди-код обычным языком.

Как работает dandy-style

Главный принцип skill сформулирован просто:

Сначала проект, потом проблема, затем подходящий рецепт и только после этого — небольшое безопасное действие.

Агент не должен открывать список правил и пытаться найти в коде нарушение под каждый пункт. Сначала он изучает контекст и реальные слабые места. Только затем выбирает от одного до трёх подходящих рецептов.

У dandy-style есть два основных режима.

Обзор проекта

Если вызвать /dandy-style без указания конкретного файла, агент начинает с поверхностного знакомства с проектом:

• читает README.md, AGENTS.md, composer.json и package.json;
• смотрит настройки тестов, форматтера и статического анализа;
• изучает структуру директорий;
• выбирает несколько характерных файлов;
• определяет принятый в проекте стиль.

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

В результате агент должен объяснить:

1. что он понял о проекте;
2. какие архитектурные и стилевые сигналы заметил;
3. где находятся наиболее вероятные проблемы;
4. почему они важны;
5. что стоит сделать первым;
6. какие рецепты Денди-кода подходят к задаче.

Работа с конкретным кодом

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

Например:

Отрефактори метод расчёта скидки в денди-стиле. Публичное поведение не меняй.

В этом режиме агент не должен уходить в аудит всего проекта. Он остаётся в заданных границах, учитывает локальный стиль и применяет только те правила, которые действительно помогают решить задачу.

Какие проблемы замечает агент

Внутри dandy-style находится карта рецептов, связанных с главами книги. Среди них:

• непонятный или устаревший README;
• монолит без видимых границ модулей;
• смешение разных стилей в одном проекте;
• плотные блоки кода без визуальной группировки;
• переменные вроде $data, $item и $result, которые ничего не объясняют;
• глубокая вложенность if/else;
• сложные логические выражения и двойные отрицания;
• магические статусы, роли, строки и числа;
• пять и более аргументов, boolean-флаги и массивы вместо понятных контрактов;
• пустые catch и проглоченные исключения;
• слишком большие методы и классы;
• лишние обёртки и абстракции «на будущее»;
• мёртвый и закомментированный код;
• скрытые зависимости, из-за которых код трудно тестировать;
• собственные велосипеды вместо стандартных возможностей Laravel;
• технический долг по обновлению PHP, фреймворка и пакетов;
• правдоподобный, но непроверенный AI-код.

При этом рецепты не превращены в религию. В skill прямо указано: стиль текущего проекта важнее личных предпочтений агента, а Laravel-way предпочтительнее самодельной архитектуры только тогда, когда для этой архитектуры нет веской причины.

Проверка перед коммитом с dandy-commit

Второй публичный skill предназначен для проверки уже сделанных изменений.

При прямом вызове /dandy-commit агент смотрит git status и git diff, изучает изменённые файлы и при необходимости ближайший код для понимания контекста. Весь проект он не рефакторит.

Доступны три сценария:

• review-only — только показать найденные проблемы; это режим по умолчанию;
• fix-safe — применить небольшие исправления без изменения поведения;
• fix-and-commit — исправить и создать коммит, но только если пользователь попросил об этом явно.

Во время проверки агент обращает внимание на следующее:

• соответствует ли diff стилю проекта;
• не появились ли лишние абстракции;
• не дублируются ли уже существующие helpers, services или repositories;
• честно ли названы переменные и методы;
• не добавлены ли магические значения;
• не пересказывают ли комментарии очевидный код;
• соблюдаются ли соглашения Laravel;
• есть ли подходящие тесты, статический анализ и форматирование;
• отражает ли сообщение коммита реальное изменение.

У skill есть важные ограничения: он не должен самовольно создавать коммит, смешивать с задачей посторонний рефакторинг или менять публичное поведение ради красоты.

Примеры запросов:

/dandy-commit

Проверь текущий diff по правилам Денди-кода. Только ревью, ничего не меняй.

Проверь изменения перед коммитом, исправь только безопасные замечания и запусти доступные тесты. Не коммить.

Ленивая загрузка рецептов

Одна из полезных особенностей проекта — агенту не требуется загружать все инструкции сразу.

Работа строится поэтапно:

1. загружается выбранный SKILL.md;
2. для широкого ревью подключается карта глав книги;
3. открывается карта проблем и рецептов;
4. загружаются только рецепты, соответствующие найденным проблемам.

Для локальной задачи обычно достаточно одного-трёх рецептов. Например, если проблема только в глубокой вложенности и запутанном условии, нет смысла одновременно загружать инструкции про README, обновление Laravel и структуру монолита.

Так расходуется меньше контекста, а агенту проще удержаться в границах задачи. Маленькая правка реже превращается в большой архитектурный праздник с оркестром DTO.

Установка

Требуется Node.js 18 или новее.

Запустить интерактивный установщик можно одной командой:

npx github:tikhomirov/dandy-code-skills install

Установщик спросит:

• установить skills в конкретный проект или глобально;
• какую директорию использовать для локальной установки;
• для какой среды выполнить установку: .agents, Claude Code, OpenCode или для всех сразу;
• удалить ли прежние Dandy-skills.

Для установки в текущий проект без вопросов:

npx github:tikhomirov/dandy-code-skills install --yes

Глобальная установка:

npx github:tikhomirov/dandy-code-skills install --global --yes

Установка только для Claude Code:

npx github:tikhomirov/dandy-code-skills install --target claude --yes

Установка в указанную директорию:

npx github:tikhomirov/dandy-code-skills install --path /path/to/project --yes

Предварительный просмотр без изменений:

npx github:tikhomirov/dandy-code-skills install --dry-run

По умолчанию установщик удаляет старые элементы, принадлежащие Dandy Code Skills, но не очищает целиком пользовательскую директорию skills. Собственные skills должны остаться на месте.

Если очистка старой версии не нужна, можно добавить --no-clean.

Зачем нужна каноническая папка .agents/skills

В актуальной версии источник skills хранится только в:

.agents/skills/

При установке для Claude Code или OpenCode сначала создаётся каноническая версия в .agents/skills, после чего в директориях конкретных агентов создаются символические ссылки на неё.

Это решает неприятную проблему предыдущего подхода: несколько копий одних и тех же инструкций могли со временем разойтись. Теперь правила редактируются и обновляются в одном месте, а разные агенты используют один источник.

Обновление со старой версии

Для перехода на 3.0 достаточно снова запустить установщик:

npx github:tikhomirov/dandy-code-skills install

При включённой очистке он удалит старые Dandy-owned entries, включая dandy-review и dandy-breakdown, а затем установит актуальные skills. Чужие элементы в директории skills удаляться не должны.

После обновления замените старые команды:

Было	Стало
/dandy-review	/dandy-style
/dandy-breakdown	/dandy-style с указанием метода, класса или файла
/dandy-commit	/dandy-commit

Примеры повседневного использования

Обзор незнакомого проекта:

/dandy-style

Ревью модуля:

Проверь модуль оплаты в денди-стиле. Найди 3–5 наиболее важных проблем и предложи безопасный порядок исправлений.

Разбор метода:

Разбери этот метод по правилам Денди-кода. Сохрани поведение и не выходи за границы класса.

Рефакторинг Laravel-кода:

Отрефактори обработчик заказа в денди-стиле. Сначала проверь, нет ли штатного решения Laravel вместо новых абстракций.

Проверка AI-кода:

Проверь изменения, созданные AI: дублирование, выдуманные API, лишние слои, нарушение локального стиля и отсутствие тестов.

Проверка перед коммитом:

/dandy-commit

Что Dandy Code Skills не делает

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

И это не универсальная архитектурная методология. Основной акцент сделан на PHP/Laravel и практической читаемости кода: понятных именах, видимом основном сценарии, небольших методах, разумных комментариях, тестируемости и использовании возможностей фреймворка.

Итог

Dandy Code Skills 3.0 стал проще снаружи и аккуратнее внутри.

Пользователю больше не нужно выбирать между похожими командами для ревью проекта и разбора метода. Для работы с кодом есть dandy-style, для проверки изменений — dandy-commit. Рецепты загружаются только по необходимости, а каноническая папка .agents/skills не даёт версиям для разных агентов разъехаться.

Если вы используете AI для PHP/Laravel-разработки, попробуйте начать с простой команды:

Проверь проект в денди-стиле.

А перед отправкой изменений в репозиторий попросите агента помыть за собой посуду:

/dandy-commit

Репозиторий: github.com/tikhomirov/dandy-code-skills

Книга «Денди-код»: github.com/tabuna/dandy-code