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

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

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

---

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

Проект может содержать разный код. Определи область задачи:

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

> **Про префиксы инструментов.** MCP-клиенты именуют инструменты по-разному: Claude Code — `mcp__1c-rsv__write_module_source`, Cursor — `mcp_1c-rsv_write_module_source` и т. д. В этом файле используются **короткие имена** (`write_module_source`). Реальное имя в своём клиенте определяй сам.

---

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

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

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

---

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

Плагин имеет три профиля. Проверь, какие инструменты доступны, и работай в их рамках.

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

Список доступных инструментов всегда виден в протоколе MCP — ориентируйся на него, а не на это перечисление.

---

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

В корне 1С-проекта ведётся две текстовых записки:

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

**В начале каждой сессии**:

1. Убедись что папка `.ai/` существует (создай, если нет).
2. Прочитай `project-knowledge.md`, если есть.
3. Прочитай `current-task.md` — если есть, продолжи с его шагов.
4. По ходу работы обновляй оба файла.

---

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

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

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

1. `list_workspace_projects` — состав workspace.
2. `get_config_properties` — тип конфигурации, версия, подсистемы.
3. `list_metadata_objects` — обзор объектов (с фильтрацией).
4. `get_object_help` — встроенная справка объекта (аналог кнопки «?» в 1С).

Находки — в `.ai/project-knowledge.md`.

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

Перед работой с объектом вызывай `ai_context` (режимы: `minimal`, `standard`, `full`) — он заменяет 5-7 отдельных запросов. Используй **вместо** серии мелких вызовов `get_object_details` + `list_modules` + `get_module_structure`.

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

- `get_module_structure` — карта методов модуля. Смотри первым.
- `read_method_source` — чтение **нужного метода**, не всего модуля.
- `read_module_source` целиком — только если метод завязан на глобальные переменные / область `#Область` требует полного контекста.
- `search_in_code` — полнотекстовый поиск по BSL, поддерживает regex. Используй вместо `Grep`.
- `find_object_references` — все ссылки на объект (`deep` для производных типов).
- `get_method_call_hierarchy` — кто вызывает метод (`incoming`) или кого вызывает он (`outgoing`). Используй перед модификацией, чтобы оценить влияние.

### 6.4. Синтаксис-помощник платформы — `get_platform_docs`

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

---

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

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

### 7.1. Выбор режима

| Задача | Режим | Параметры |
| --- | --- | --- |
| Изменить один метод | `replaceMethod` | `methodName` |
| Изменить диапазон строк | `replaceLines` | `lineFrom`+`lineTo` |
| Добавить метод в конец | `append` | — |
| Вставить код перед/после строки | `insertBefore` / `insertAfter` | `line` |
| Полностью переписать модуль | `replace` | + `confirmFullReplace: true` |

### 7.2. Запрещено использовать `replace` для изменения одного метода

`replace` заменяет **весь модуль**. Если передать только один метод — остальной код (сотни/тысячи строк) будет удалён. Для одного метода — `replaceMethod`. Для диапазона — `replaceLines`.

### 7.3. Алгоритм изменения метода

1. `read_method_source` — прочитай метод, запомни `startLine` и `endLine`.
2. Подготовь исправленный код (от `Процедура`/`Функция` до `КонецПроцедуры`/`КонецФункции`, включая директивы `&НаКлиенте`, `&НаСервере`, `&После(...)`).
3. `write_module_source` с `mode: "replaceMethod"` и `dryRun: true`.
4. Проверь dry-run: `removedLines` ≈ размер старого метода, `addedLines` ≈ размер нового.
5. Повтори с `dryRun: false` — запись.

### 7.4. Контроль dry-run

После `dryRun: true` обязательно смотри `removedLines`:

| Условие | Действие |
| --- | --- |
| `removedLines = 0` | ✅ Безопасно — код только добавляется |
| `removedLines` ≈ заменяемому фрагменту | ✅ Ожидаемо для `replaceLines` / `replaceMethod` |
| `removedLines > 30%` от модуля | ❌ СТОП — неправильный режим, пересмотри |
| `removedLines > 50%` от модуля | ❌ Только после явного разрешения пользователя |

Когда `replace` допустим: модуль пустой / создаётся впервые / меньше 50 строк и ты передаёшь его целиком / полная переработка после согласования с пользователем.

### 7.5. Валидация — встроена в ответ записи

После успешной записи (не dry-run) `write_module_source` **сам** дожидается валидации EDT и возвращает её результат в поле `validation`:

```json
"validation": {
  "errors": [ { "line": 8, "message": "..." } ],
  "errorCount": 3,
  "hint": "3 ошибок в записанном файле. Исправь их перед продолжением"
}
```

Отдельно звать `get_validation_errors` **не нужно** — валидация уже в ответе. Если `errorCount > 0` — исправь и запиши ещё раз. Если `errorCount = 0` — код корректен.

Поведение можно отключить параметром `validateAfterWrite: false` (для серии быстрых правок — потом один раз позови валидацию вручную).

### 7.6. Проверка изменений — `diff_module`

После серии правок можно глянуть итоговый diff: `mode: "summary"` (какие методы добавлены / изменены / удалены), `"unified"` (git-style), `"methods"` (диф по методам).

### 7.7. Большие модули

Для модулей 6000+ строк используй `nameFilter` в `get_module_structure` и читай только нужные методы через `read_method_source` с пагинацией.

---

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

Нужна, если ты **не** использовал `write_module_source` (правили файл вручную в EDT), или хочешь проверить состояние целиком.

Дефолт `scope=session` возвращает ошибки только по файлам, изменённым в текущей сессии плагина. `scope=object` — по одному объекту (с `objectName`). `scope=project` при >200 ошибок сработает предохранитель `tooManyErrors` и вернёт краткую сводку вместо списка тысяч ошибок из базовой конфигурации.

Параметр `fileFilter` — точечный фильтр по подстроке пути файла, работает поверх любого scope.

`validate_query` — синтаксис 1С-запросов перед вставкой в код.

---

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

Единый инструмент-конструктор (доступен в профиле Архитектор). Десятки операций: создание объектов метаданных любого типа, реквизиты и табличные части, формы (создание, поля, группы, кнопки, таблицы, декорации, обработчики команд), картинки (стандартные и `CommonPicture.*`), расширения и заимствование объектов, отчёты СКД (схемы, наборы данных, группировки, отборы, оформление) — в т. ч. на любых объектах, не только `Report`, макеты печатных форм и именованные области.

### 9.1. Используй встроенную справку

Перед работой вызови `edit_metadata operation=help` — получишь список всех операций. Для деталей конкретной операции — `help topic=<имя>`. Для типичных сценариев — `help topic=workflow`, `help topic=dcsWorkflow`, `help topic=composerWorkflow`, `help topic=matrixWorkflow`.

### 9.2. Проверяй результат через `dryRun`

К любой операции `edit_metadata` можно добавить `dryRun: true` — операция выполнится в транзакции и **откатится**, в ответе виден полный результат. Используй перед изменением, чтобы перепроверить параметры. Исключения (`adoptObject`, `adoptObjects`, `adoptChild`, удаление реквизитов/табличных частей) возвращают `dryRunNotSupported` с пояснением.

### 9.3. Перед модификацией формы

`get_form_image` с `format: "structure"` — JSON-дерево элементов формы. `format: "image"` — PNG-превью. Без этого не меняй форму «вслепую».

### 9.4. Расширения

`adoptObject` — заимствование одного объекта. `adoptObjects` — **батч-заимствование** списка объектов одним вызовом (без автоматической тяги связанных — это именно то, что хочет человек, когда говорит «заимствуй вот эти 5 объектов»). Если указать ссылочный тип реквизита на незаимствованный объект — он подтянется автоматически.

---

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

Полноценный отладчик 1С (breakpoints, step, переменные, evaluate произвольных BSL-выражений). Доступен в профилях Разработчик и Архитектор.

Типичный сценарий:

1. `list_applications` — получить `applicationId` информационной базы.
2. `launch_debugger action=addBreakpoint` — поставить точку останова.
3. Пользователь выполняет действие в 1С:Предприятии.
4. `launch_debugger action=getState` → `getVariables` → `evaluate` → `stepOver` / `resume`.

---

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

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

---

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

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

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

**Алгоритм адаптации**:

1. Через `search_in_code` найди 3–5 примеров аналогичного кода.
2. Через `read_method_source` и `get_method_call_hierarchy` изучи паттерн.
3. При сомнениях уточни через `get_platform_docs` / `get_object_help`.
4. Пиши код **в стиле проекта**, не навязывай свой.

---

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

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