# Правила для AI-ассистента при работе с 1С-проектами

## 1. Язык общения

Общайся с пользователем **на русском**. Все вопросы, объяснения, комментарии к коду и сообщения об ошибках — на русском. Если пользователь переключился на другой язык — следуй за ним.

---

## 2. Когда использовать MCP-сервер `1c-rsv`

- **1С** (BSL, метаданные, формы, запросы, схемы компоновки, макеты) — **только** через инструменты `1c-rsv`.
- **Не-1С** (JSON, JS, Python, docker, shell) — обычными инструментами (`Read`, `Edit`, `Write`, `Grep`, `Bash`). На файлы 1С их **не применяй**.
- **Смешанное** — комбинируй: 1С-часть через `1c-rsv`, остальное обычными инструментами.

> Имя инструмента у разных клиентов разное (`mcp__1c-rsv__write_module_source` в Claude Code, `mcp_1c-rsv_write_module_source` в Cursor). Здесь — короткие имена; реальное определяй в своём клиенте.

---

## 3. Работа с 1С — только через MCP

Файлы 1С в EDT (`.bsl`, `.mdo`, `.form`, `.dcs`, XML) имеют сложную структуру. Прямая правка через `Read`/`Edit`/`Write`/`Grep` **ломает проект** — теряются внутренние связи модели и ссылки на объекты. Инструменты `1c-rsv` работают через штатный API 1С:EDT (понимают контекст, типы, ссылки).

**Протокол при отказе инструмента (ВАЖНО).** Если операция вернула ошибку или результат не совпал с ожиданием:

1. **СТОП.** Не правь файлы 1С напрямую (`Edit`/`Write`/скрипты/переименование папок) — модель EDT и файлы рассинхронизируются, у пользователя зависнут синхронизация ИБ и выгрузка. Это хуже, чем невыполненная задача.
2. Перечитай текст ошибки — обычно там написано, что делать (`helpHint`, поле `important`).
3. Если решения нет — **доложи пользователю**: какая операция, какие параметры, какой ответ. Пусть он решает: выполнить вручную в EDT или изменить задачу. Обход запрета допустим только после его явного разрешения.

---

## 4. Профили доступа

Три профиля — работай в рамках доступных инструментов:

- **Аналитик** — чтение, поиск, анализ, справка (без записи кода и метаданных).
- **Разработчик** — + запись BSL, валидация, сборка, отладка, экспорт `.epf`/`.erf`.
- **Архитектор** — + `edit_metadata` (метаданные, формы, отчёты СКД, макеты, расширения).

Доступный набор виден в протоколе MCP — ориентируйся на него. Если профиль не позволяет правку — сообщи и предложи переключить.

---

## 5. Управление знаниями — папка `.ai/`

- **`.ai/project-knowledge.md`** — что за конфигурация (ERP/УТ/БП/ЗУП/самописная), версия БСП, ключевые общие модули, паттерны проекта, расширения. Держи **кратким** — только то, что экономит токены в следующей сессии.
- **`.ai/current-task.md`** — для многошаговых задач: описание, план, хронология. Обновляй по ходу, удаляй после завершения.

**В начале сессии:** убедись что `.ai/` есть; прочитай `project-knowledge.md` и `current-task.md` (если есть — продолжи с его шагов); по ходу обновляй оба.

---

## 6. Работа с кодом

### 6.1. Знакомство с проектом

`list_workspace_projects` (состав workspace) → `get_config_properties` (тип/версия/подсистемы) → `list_metadata_objects` (обзор объектов) → `get_object_help` (встроенная справка объекта, аналог кнопки «?»). Находки — в `.ai/project-knowledge.md`.

### 6.2. Сбор контекста по объекту — `ai_context`

Перед работой с объектом вызывай `ai_context` (`minimal`/`standard`/`full`) — он заменяет 5-7 отдельных запросов. На крупных отчётах схема компоновки выводится компактно, детали дозапрашиваются.

### 6.3. Чтение и поиск кода

- `code_structure` — структура и код BSL на штатной модели EDT (точные сигнатуры, типы параметров, области — не текстовый разбор). Паттерн: карта модуля → тело нужного метода → при необходимости модуль целиком. Не читай весь модуль ради одного метода.
- `code_search` — поиск по коду вместо `Grep`: текст, ссылки на объект/метод, переход к определению (F12), иерархия вызовов (оцени влияние перед правкой метода).

### 6.4. Платформенный справочник — `get_platform_docs`

API платформы и язык запросов/СКД. Вызывай **при сомнениях** в сигнатуре, не каждый раз — если паттерн уже найден в коде проекта, проверка не нужна.

---

## 7. Запись кода — `write_module_source`

Самая опасная зона: неверный режим может **безвозвратно удалить весь модуль**.

- Один метод — `replaceMethod`, диапазон строк — `replaceLines`, добавить — `append`, вставить — `insertBefore`/`insertAfter`.
- **Никогда не используй `replace` для одного метода** — он заменяет весь модуль, остальной код (сотни/тысячи строк) будет удалён. `replace` (с `confirmFullReplace`) — только для пустого/нового/маленького модуля целиком или полной переработки по согласованию.

**Алгоритм:** `code_structure operation=readMethod` (прочитай метод и его границы) → подготовь полный код метода (с директивами `&НаКлиенте`/`&НаСервере`/`&После(...)`) → запись с `dryRun: true`, проверь `removedLines` → повтори с `dryRun: false`.

**Контроль dry-run**: для `replaceMethod`/`replaceLines` сверяй `replacedLines` (что именно заменится); `removedLines` — это лишь «на сколько строк модуль уменьшился» (разница размеров). `removedLines` больше ~30% модуля — СТОП, скорее всего не тот режим; больше ~50% — только с явного разрешения пользователя.

**Валидация уже в ответе:** после записи `write_module_source` сам дожидается проверки EDT — поле `validation` (`errorCount` + список ошибок). Отдельно `get_validation_errors` звать не нужно; есть ошибки — исправь и перепиши.

`diff_module` — итоговый diff после серии правок. Большие модули (6000+ строк) — `nameFilter` в `code_structure`, читай только нужные методы.

---

## 8. Валидация — `get_validation_errors`

Нужна, если правил **не** через `write_module_source` (вручную в EDT) или хочешь проверить состояние целиком (по сессии / объекту / проекту). `validate_query` — синтаксис 1С-запроса перед вставкой в код.

---

## 9. Создание и изменение метаданных — `edit_metadata`

Единый конструктор (профиль Архитектор): объекты метаданных, реквизиты и табличные части, формы, отчёты СКД, макеты, расширения и заимствование — более 100 операций. **Список операций и их параметры — `edit_metadata operation=help`** (`topic=<имя>` — детали операции; `topic=workflow`/`dcsWorkflow`/`composerWorkflow`/`matrixWorkflow` — типовые сценарии).

- **`dryRun: true`** к любой операции — выполнится в транзакции и откатится, в ответе полный результат. Удобно перепроверить параметры до изменения.
- **Перед правкой формы посмотри её:** `get_form_image` (`format: structure` — дерево элементов, `image` — PNG). Не меняй форму вслепую.
- **Расширения:** `adoptObject` — заимствовать один объект, `adoptObjects` — батч-заимствование списка (когда просят «заимствуй вот эти 5»); ссылочные типы реквизитов подтягиваются автоматически.

---

## 10. Отладка — `launch_debugger`

Полноценный отладчик 1С (точки останова, шаги, переменные, `evaluate` произвольных BSL-выражений). Профили Разработчик/Архитектор. Сценарий: `list_applications` → поставить точку останова → пользователь выполняет действие в 1С:Предприятии → `getState` / `getVariables` / `evaluate` / `stepOver` / `resume`.

---

## 11. Экспорт внешних обработок и отчётов — `export_object`

Проект внешней обработки (`.epf`) / отчёта (`.erf`) собирается в бинарный файл одним вызовом `export_object` (EDT сам подберёт совместимую версию платформы). Путь не указан — **спроси** пользователя, куда сохранить; во временный каталог без подтверждения не пиши.

---

## 12. Следуй паттернам проекта

**Код должен быть органичен конфигурации** — не тащи платформенные примитивы, если в проекте есть обёртки.

- Вместо `Сообщить()` — метод общего модуля (`ОбщегоНазначения.СообщитьПользователю`, `ВызовСервера.СообщитьПользователю` и т. п.).
- Перед формированием движений — проверь специальные процедуры; перед прямыми запросами к регистрам — API-методы.

**Как адаптироваться:** `code_search` (найди 3-5 примеров аналогичного кода) → `code_structure` + `code_search` callHierarchy (изучи паттерн) → при сомнениях `get_platform_docs` / `get_object_help` → пиши **в стиле проекта**, не навязывай свой.

---

## 13. Экономия токенов

- Ответ уже в `.ai/project-knowledge.md` — повторный вызов не нужен.
- `ai_context` вместо серии мелких запросов; пагинация (`offset`/`limit`) — не запрашивай всё целиком; читай нужный метод, а не весь модуль.
- Перед `edit_metadata` — `operation=help` вместо угадывания параметров.
- Находки записывай в `.ai/project-knowledge.md` для следующих сессий.
