Rules for AI assistants

Всё чаще правки в сайт вносят не разработчики, а ИИ-ассистенты — Claude Code, Cursor, Copilot и подобные. Это нормальный сценарий: Celena CMS к нему готова. Но ассистенту нужно объяснить правила игры — иначе он может «починить» сайт так, что правки исчезнут при первом же обновлении, либо сломает то, что трогать нельзя. Эта страница — инструкция, которую стоит дать ассистенту перед задачей.

Главное правило

Не редактировать core/, modules/ и config/. Эти каталоги — ядро движка, при обновлении CMS они перезаписываются целиком (см. «Обновление CMS»). Любая правка там живёт до ближайшего обновления, а потом молча исчезает. То же относится к штатным плагинам и темам — полная карта каталогов на странице «Зоны движка: что можно править».

Всё своё — в отдельный плагин plugins/<имя>/ или свою тему templates/<имя>/. Движок расширяется через хуки и собственный SDK, модифицировать ядро для типовых задач не нужно.

Файлы-инструкции в корне сайта

• AGENTS.md — лежит в корне дистрибутива. Это готовая инструкция для ИИ-агентов: стек, запреты, скелеты плагина и темы, список сервисов ядра. Первое, что должен сделать ассистент, — прочитать этот файл.
• AGENTS.local.md — ваши собственные дополнения (особенности вашего сайта, названия ваших плагинов и тем, доступы к тестовому стенду). Ядро этот файл не перезаписывает — пишите смело. AGENTS.md при обновлении заменяется новой версией, поэтому свои заметки держите только в AGENTS.local.md.
• docs/ — подробная документация для разработчиков (ARCHITECTURE.md, TEMPLATES.md, PLUGIN_SDK.md, AI_AGENT_GUIDE.md). Каталог перезаписывается при обновлении, читать можно, править — нет.

llms.txt

Машиночитаемый индекс этой документации доступен по адресу <https://celena.io/llms.txt> (формат llmstxt.org). Дайте ссылку ассистенту — он сам найдёт нужные страницы. На вашем сайте с активным плагином handbook индекс отдаётся и по вашему домену: https://ваш-сайт/llms.txt.

Чек-лист: что сказать ассистенту перед задачей

Скопируйте в начало диалога и дополните своими данными:

1. «Это сайт на Celena CMS. Сначала прочитай AGENTS.md и AGENTS.local.md в корне проекта».
2. «Не редактируй core/, modules/, config/, штатные плагины (leads, shop, analytics, handbook) и штатные темы (default, admin, commerce) — они перезаписываются при обновлении».
3. «Свой код — только в plugins/<имя>/ или templates/<имя>/». Назовите ассистенту вашу тему и ваши плагины.
4. «PHP в .tpl-файлах не выполняется — только теги шаблонизатора (см. docs/TEMPLATES.md)».
5. «После правки шаблонов выполняй php bin/celena cache:clear».
6. «Никаких внешних CDN — все скрипты и стили локально» (их блокирует CSP).
7. «SQL — только через QueryBuilder или prepared statements, имена таблиц через префикс». Сообщите, какая у вас СУБД — MySQL или PostgreSQL.
8. «Перед изменениями в базе на рабочем сайте — резервная копия».

Типичные ошибки ассистентов и способы их избежать разобраны на странице «Типичные поломки и как их избежать».