Перейти к основному содержимому

ИИ-агент — Свод законов

Версия: 1.0
Дата: 19.04.2026
Статус: Утверждён

Этот документ — жёсткий свод правил поведения ИИ-агента в системе документооборота. Хук ссылается на него при каждом срабатывании. Агент обязан следовать этим правилам безоговорочно.

Полное руководство по настройке: cms-system/reference/ИИ-агент — Настройка и интеграция.md

I. КОД ПЕРВИЧЕН​

  1. Код, живые файлы, реальная структура папок — единственный источник истины.
  2. Документация — ориентир и опора. Если документ противоречит коду — верить коду.
  3. Обновление документации обязательно, но только после того как код написан и проверен.
  4. Никогда не строить логику на основании документации не сверившись с реальными файлами.

II. ОРИЕНТАЦИЯ ПЕРЕД ЛЮБЫМ ДЕЙСТВИЕМ​

  1. Перед любой правкой — прочитать структуру проекта: docs_index → docs_search → docs_get_section.
  2. Прочитать реальные файлы (Read/Grep) — не доверять документации на слово.
  3. Убедиться что работаешь в правильном проекте — см. раздел V "Сверка проекта".
  4. Если после ориентации картина неясна — спросить пользователя, не угадывать.

III. АЛГОРИТМ РАБОТЫ (порядок строгий)​

1. Получить задачу
2. Ориентация: DocMap index → search → get_section
3. Сверка реальных файлов: Read/Grep — код первичен
4. Сверка проекта: slug папки = slug в задаче
5. Выполнить задачу (код/документы)
6. Обновить документацию в рамках той же задачи
7. git add <конкретные файлы> (не -A)
8. git commit с осмысленным сообщением

Отклонение от порядка — только с явного согласия пользователя.

IV. ПРАВИЛА ЗАПИСИ ФАЙЛОВ​

  1. Картинки и медиа — только в docs/<slug>/assets/. Никогда не в static/ напрямую.
  2. index.md проекта — не редактировать вручную. Только через tools/build_project_index.sh <slug>.
  3. Новый документ — создавать строго в одном из четырёх разделов проекта: overview/, reference/, operations/, development/. Не в корне проекта, не в корне docs/.
  4. Новый проект — требует _project_.json, четыре папки разделов, _category_.json в каждой. Без этого папка невидима для системы.
  5. cms-config.json — не редактировать напрямую, только через tools/add_user.sh.
  6. docusaurus.config.ts — не редактировать url и title вручную, только через cms-config.json.
  7. static/admin/index.html — не редактировать CREDENTIALS_HASH вручную, только через tools/add_user.sh --admin. UI-изменения (стили, кнопки, логика не связанная с хэшем) — редактировать напрямую.
  8. При создании нового файла — после записи запустить tools/build_project_index.sh <slug>.

V. СВЕРКА ПРОЕКТА​

  1. Перед любой правкой убедиться: slug из задачи/памяти совпадает с именем папки в docs/.
  2. Проверить: docs/<slug>/_project_.json существует.
  3. Проверить: label в _project_.json соответствует задаче.
  4. Если slug не найден или не совпадает — стоп, консультация с пользователем.
  5. Если задача касается нескольких проектов — явно уточнить у пользователя для каждого.

VI. ЧУЖИЕ ПРОЕКТЫ​

  1. Агент работает в одном проекте за раз — том, который указан в задаче или памяти.
  2. Читать документацию других проектов — можно.
  3. Редактировать файлы другого проекта — запрещено без явного подтверждения пользователя.
  4. "Явное подтверждение" — пользователь назвал slug другого проекта в этой задаче. Не додумывать.

VII. ОБНОВЛЕНИЕ ДОКУМЕНТАЦИИ​

  1. Документация обновляется в рамках той же задачи что и код — не откладывать на потом.
  2. Последовательность: код готов и проверен → затем docs_patch_section / docs_create_section.
  3. Если создан новый файл — обновить index.md через скрипт, обновить DocMap.
  4. Если изменилась структура проекта — запустить tools/build_project_index.sh <slug>.
  5. Если добавлен публичный проект — запустить tools/build_index.sh.
  6. DocMap обновляется через MCP-инструменты: docs_patch_section, docs_create_section, docs_create_file. Не через прямое редактирование MD-файлов когда есть MCP.

VIII. ОФОРМЛЕНИЕ ДОКУМЕНТОВ​

  1. Каждый содержательный документ (не index.md) обязан иметь шапку сразу после H1:
**Версия:** 1.0  
**Дата:** ДД.ММ.ГГГГ  
**Статус:** Черновик / Готов к обсуждению / Утверждён
  1. index.md проекта — шапка не нужна, он генерируется скриптом.
  2. Навигационные index.md разделов — шапка не нужна, только список документов.
  3. При создании нового документа — шапка обязательна сразу, не добавлять потом.
  4. При обновлении документа — обновить **Версия:** и **Дата:**.
  5. Статус "Утверждён" — только когда пользователь явно подтвердил готовность документа.

IX. GIT-КОММИТ​

  1. Коммитить только после завершения задачи включая обновление документации.
  2. git add — только конкретные файлы. Никогда git add -A или git add ..
  3. Сообщение коммита — что изменилось и зачем, не перечисление файлов.
  4. Не коммитить: .deploy-tmp/, exports/, docs/_uploads/.
  5. Не коммитить cms-config.json если репозиторий публичный.
  6. Один коммит на одну логическую задачу. Не дробить без причины, не объединять несвязанное.

X. ЕСЛИ НЕЯСНО — СПРОСИТЬ​

  1. Неясен раздел для нового документа → спросить.
  2. Неясен slug проекта → спросить.
  3. Задача затрагивает чужой проект → спросить.
  4. Документация противоречит коду → сообщить пользователю, не выбирать самостоятельно.
  5. Любое сомнение в деструктивном действии (удаление, переименование, рефакторинг структуры) → спросить.

Правило: лучше один лишний вопрос чем неверное действие в автономном режиме.

XI. ЗАПРЕЩЕНО БЕЗУСЛОВНО​

  • Писать картинки в static/ напрямую
  • Редактировать index.md проекта вручную
  • Редактировать файлы чужого проекта без подтверждения
  • git add -A или git add .
  • Строить логику только на документации без сверки с кодом
  • Коммитить незавершённую задачу (код без обновления документации)
  • Менять CREDENTIALS_HASH, url, title вручную минуя скрипты
  • Создавать документы в корне docs/ или корне проекта (только в разделах)