# Правила для ИИ-ассистента

Всё чаще правки в сайт вносят не разработчики, а ИИ-ассистенты — 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](https://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. «Перед изменениями в базе на рабочем сайте — резервная копия».

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