AGENTS.md и правила Cursor для проекта 1С: как настроить память ИИ-ассистентов

Открываете выгрузку конфигурации в Cursor или запускаете Claude Code в терминале, и модель начинает с угадывания: какие в проекте директивы компиляции, как называть процедуры, можно ли трогать рабочую базу. Каждый раз объяснять это в чате долго, а длинный промпт занимает контекстное окно. Постоянные правила лежат в файлах репозитория, и каждый инструмент читает свой набор файлов.

С этими файлами легко ошибиться. Я проверила документацию Cursor и Claude Code и нашла место, где типичная схема «AGENTS.md для всех плюс CLAUDE.md для Claude» тихо перестаёт работать: когда в репозитории есть оба файла, Claude Code читает только CLAUDE.md. В статье разобрано, как устроены приоритеты файлов, какие шаблоны я положила в архив, и как скрипт ловит поломку до коммита.

🔬 Что я прогнала на стенде

Стенд:

Прогнано три вещи. Скрипт check_rules.py запускался из распакованного архива на шаблонах и на испорченной копии. Команда синтаксического контроля из CLAUDE.md запускалась платформой на двух файловых базах, с ошибкой в модуле и без. Поведение Cursor и Claude Code с файлами правил я сверяла с официальной документацией: живую сессию с моделью на этом стенде я не гоняла. Claude Code 2.1.276 вдобавок младше версии 2.1.277, с которой он читает AGENTS.md сам, поэтому проверять эту часть запуском здесь было бы нечестно.

📋 Какой файл читает какой инструмент

По документации Cursor, правила проекта лежат в .cursor/rules/ в файлах .mdc с тремя полями frontmatter: description, globs и alwaysApply. Если alwaysApply: true, правило подключается всегда, а globs и description игнорируются. Если alwaysApply: false и заданы globs, правило автоматически подключается, когда в контексте есть подходящий файл. AGENTS.md в корне Cursor принимает как простую альтернативу .cursor/rules, вложенные AGENTS.md в подкаталогах поддерживаются, более конкретный файл приоритетнее.

У Claude Code картина другая. Документация описывает три случая:

Прямое чтение AGENTS.md появилось в версии 2.1.277. В более ранних версиях Claude Code читает только CLAUDE.md. Если в проекте есть CLAUDE.md, а общий AGENTS.md нужен Claude, в CLAUDE.md первой строкой ставят импорт @AGENTS.md. Фраза «следуй правилам из AGENTS.md» словами не работает: по документации Claude увидит файл, только если сам решит его открыть. Есть и настройка claude-md-and-agents-md, которая заставляет читать оба файла, но она живёт в личных настройках разработчика, а импорт лежит в репозитории и действует на всю команду.

Отсюда схема из трёх файлов:

1. AGENTS.md хранит общие правила: безопасность, стандарты BSL, методы платформы, коммиты. Его читают Cursor и другие инструменты из списка на agents.md (там, среди прочих, GitHub Copilot, Codex, Gemini CLI и Windsurf).
2. CLAUDE.md начинается со строки @AGENTS.md, дальше идут команды и порядок работы Claude Code.
3. .cursor/rules/1c-bsl.mdc содержит то, что нужно Cursor только при работе с .bsl.

🧱 Общие правила в AGENTS.md

В AGENTS.md четыре раздела. Вот их полный текст из архива:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# Стандарты разработки и правила ИИ-агентов в 1С-проекте

Этот файл читают все ИИ-ассистенты репозитория: Cursor, Claude Code и другие инструменты, поддерживающие AGENTS.md. Он описывает исходные тексты конфигураций и внешних обработок 1С:Предприятия 8.3.

## Безопасность

1. Токены, пароли, адреса рабочих контуров и закрытые ключи API не вставлять в модули BSL, XML-выгрузки и скрипты.
2. Настройки интеграций брать из переменных среды или из безопасного хранилища платформы.
3. Рабочую информационную базу скриптами не менять: тесты идут в отдельной файловой или клиент-серверной базе.
4. В примерах запросов к внешним сервисам использовать адрес `https://example.local/api` и фиктивные токены.
5. Файлы `.env`, выгрузки пользователей и журналы регистрации не читать и не вставлять в ответ.

## Стандарты BSL

1. Имена процедур, функций и переменных - по-русски, полными словами, без транслитерации.
2. У каждой процедуры и функции управляемой формы указана директива компиляции: `&НаКлиенте`, `&НаСервере` или `&НаСервереБезКонтекста`.
3. Экспортные процедуры и функции снабжены описанием назначения, параметров и возвращаемого значения.
4. Транзакция: `НачатьТранзакцию()`, затем `Попытка`; в `Исключении` вызвать `ОтменитьТранзакцию()` и `ВызватьИсключение`.

## Методы платформы

1. Методы и свойства объектов платформы не выдумывать. Если метод неочевиден, сверить его с синтакс-помощником платформы 8.3 или прямо написать в ответе, что имя метода не подтверждено.
2. Режим совместимости конфигурации взять из `Configuration.xml`, прежде чем применять новые возможности языка.
3. Тип значения, который вернул метод, не предполагать: проверять `ТипЗнч()` или документацию.

## Фиксация изменений

1. Сообщение коммита: `[Подсистема] Краткое описание изменения`.
2. Перед коммитом модули проходят синтаксический контроль платформы (команда записана в `CLAUDE.md`).
3. Файлы исходных текстов без явного подтверждения разработчика не удалять.

Раздел «Безопасность» стоит первым, чтобы запреты читались раньше остального.

🔧 Правило Cursor для файлов BSL

Правила, которые нужны только при работе с модулями, удобно вынести в .cursor/rules/1c-bsl.mdc с маской файлов:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

---
description: Правила для модулей 1С:Предприятия на встроенном языке BSL
globs: **/*.bsl
alwaysApply: false
---

# Правила для файлов .bsl

Правило подключается, когда в контексте есть файл с расширением `.bsl`. Общие правила проекта - в `AGENTS.md`.

1. Перед процедурами и функциями управляемых форм ставить директиву компиляции (`&НаКлиенте`, `&НаСервере`, `&НаСервереБезКонтекста`).
2. Не изобретать методы платформы: неочевидное сверять с синтакс-помощником 8.3.
3. Транзакция: `НачатьТранзакцию()`, `Попытка`, `ЗафиксироватьТранзакцию()`; в `Исключении` - `ОтменитьТранзакцию()` и `ВызватьИсключение`.
4. Пароли, токены и адреса рабочих контуров в модуль не вставлять.

Маска важна. В документации Cursor есть пара примеров: *.ts совпадает с файлами .ts в корне, **/*.ts - с файлами в любом каталоге. В выгрузке конфигурации модули лежат глубоко, например Documents/Реализация/Forms/ФормаДокумента/Ext/Form/Module.bsl, поэтому маска *.bsl не сработает ни на один из них.

📜 Как CLAUDE.md подключает общие правила

Файл для Claude Code начинается с импорта, дальше идёт команда синтаксического контроля платформой:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

@AGENTS.md

# Claude Code: команды и порядок работы

Общие правила проекта лежат в `AGENTS.md`, строка выше подключает их в контекст.

## Синтаксический контроль платформой

Конфигуратор запускать через `Start-Process -Wait`: прямой вызов `1cv8.exe` из PowerShell возвращает управление сразу, код завершения не виден. Результат записывается в файл `/Out`.

```powershell
$p = Start-Process "C:\Program Files (x86)\1cv8\8.3.27.2130\bin\1cv8.exe" `
  -ArgumentList 'DESIGNER','/F','C:\bases\test_db','/DisableStartupDialogs','/CheckModules','-Server','-ThinClient','/Out','C:\temp\check.txt' `
  -Wait -PassThru -WindowStyle Hidden
$p.ExitCode          # 0 - ошибок нет, 101 - есть ошибки в модулях
Get-Content C:\temp\check.txt -Encoding UTF8
```

Номер версии и путь к платформе заменить на свои. Базу `C:\bases\test_db` брать тестовую.

## Порядок работы

1. Ответы - по-русски, коротко.
2. После правки `.bsl` запустить проверку выше и показать вывод из файла.
3. При конфликте или спорном месте логики спросить разработчика, не решать самой.

Эту команду я прогнала на платформе 8.3.27.2130 на двух файловых базах из моей лаборатории. На базе без ошибок:

ExitCode=0
Синтаксических ошибок не обнаружено!

На базе, где в общем модуле стоит Возврат 1 +;:

ExitCode=101
{ОбщийМодуль.ЛабМодуль.Модуль(2,13)}: Ошибка в выражении
	Возврат 1 +<<?>>; (Проверка: Сервер)

Прямой вызов & 1cv8.exe DESIGNER ... из PowerShell у меня вернул управление сразу, без кода завершения. Поэтому в шаблоне стоит Start-Process -Wait. Платформа у меня 32-разрядная и лежит в Program Files (x86); на 64-разрядной установке путь другой. Анализатор BSL Language Server в CLAUDE.md я не включала: его команду из документации (--analyze --srcDir ... --reporter ...) я на стенде не запускала.

🧰 Проверка файлов правил скриптом

Файл правил ломается тихо. Если в начале .mdc стоит BOM-сигнатура, первая строка файла перестаёт быть ---. Маска *.bsl не захватывает подкаталоги. Из CLAUDE.md пропадает строка @AGENTS.md, и общие правила перестают попадать в контекст. Git такие поломки не замечает. Скрипт check_rules.py из архива проверяет все три случая и ещё разделы AGENTS.md и поля frontmatter. Ключевая часть:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

def check_claude(path: Path) -> list:
    errors = []
    text = read_text(path, errors)
    if text is None:
        return errors
    if not any(line.strip() == "@AGENTS.md" for line in text.split("\n")):
        errors.append(f"{path.name}: нет строки @AGENTS.md - Claude Code прочитает только CLAUDE.md, общие правила не попадут в контекст")
    return errors


def check_mdc(path: Path) -> list:
    errors = []
    text = read_text(path, errors)
    if text is None:
        return errors
    fields = frontmatter(text)
    if fields is None:
        errors.append(f"{path.name}: нет блока frontmatter (первая строка '---', закрывающая '---')")
        return errors
    for key in ("description", "globs", "alwaysApply"):
        if key not in fields:
            errors.append(f"{path.name}: во frontmatter нет поля {key}")
    globs = fields.get("globs", "")
    for g in [x.strip() for x in globs.split(",") if x.strip()]:
        if g.startswith("*.") and "/" not in g:
            errors.append(f"{path.name}: маска {g} захватит только корень проекта, для подкаталогов нужна **/{g}")
    return errors

Полный текст со вспомогательными функциями - в архиве. Запуск из распакованного архива на шаблонах:

Проверка файлов правил ИИ-ассистентов: C:\распаковано
============================================================
[OK]   AGENTS.md
[OK]   CLAUDE.md
[OK]   1c-bsl.mdc
============================================================
Итог: проверено 3, с ошибками 0

На копии, где я убрала из CLAUDE.md первую строку, добавила BOM в .mdc и заменила маску на *.bsl:

Проверка файлов правил ИИ-ассистентов: C:\распаковано\bom
============================================================
[OK]   AGENTS.md
[FAIL] CLAUDE.md
  - CLAUDE.md: нет строки @AGENTS.md - Claude Code прочитает только CLAUDE.md, общие правила не попадут в контекст
[FAIL] 1c-bsl.mdc
  - 1c-bsl.mdc: в начале файла маркер BOM (U+FEFF), нужен UTF-8 без BOM
  - 1c-bsl.mdc: маска *.bsl захватит только корень проекта, для подкаталогов нужна **/*.bsl
============================================================
Итог: проверено 3, с ошибками 2

Код возврата второго прогона равен 1, поэтому скрипт можно поставить в pre-commit или в CI. Как именно Cursor реагирует на BOM в .mdc, я не проверяла: скрипт запрещает BOM заранее, на случай такой реакции.

🛠 Если правила не действуют

Claude Code не знает правил из AGENTS.md. Причина: в репозитории есть CLAUDE.md без импорта, либо версия Claude Code ниже 2.1.277. Что сделать: первой строкой CLAUDE.md поставить @AGENTS.md. Проверка: check_rules.py.

Правило .mdc не подключается на файлах из подкаталогов. Причина: маска *.bsl без **/. Что сделать: заменить на **/*.bsl.

Правило подключается в каждом диалоге. Причина: в frontmatter alwaysApply: true; по документации тогда globs и description игнорируются. Что сделать: поставить alwaysApply: false.

Правило не срабатывает вообще. Причина: нет блока frontmatter, он испорчен или перед ним стоит BOM. Что сделать: сохранить файл в UTF-8 без BOM и запустить check_rules.py.

💬 Что у вас в правилах

Какие требования к BSL вы вынесли в постоянные правила ассистента, а какие оставили проверять BSL Language Server или SonarQube? Если у вас в одном репозитории работают несколько инструментов, поделитесь в комментариях, какой файл у вас главный и как вы синхронизируете остальные.

🧭 Ограничения

Поведение Cursor и Claude Code с файлами правил описано по официальной документации на 06.10.2026: на стенде я проверила скрипт и команду платформы, а живые сессии ассистентов с моделью не запускала. Установленный у меня Claude Code 2.1.276 читает только CLAUDE.md, поэтому на этом стенде схема работает через импорт @AGENTS.md. Cursor 3.22.12 установлен, но правила я в нём на модели не гоняла. Версии платформы, кроме 8.3.27.2130, и клиент-серверные базы не проверялись. Формат файлов памяти в обоих инструментах меняется быстро, сверяйте с документацией на дату чтения.

📚 Источники

• Правила проекта в Cursor - формат .cursor/rules/*.mdc, поля description, globs, alwaysApply, поддержка AGENTS.md, примеры масок.
• Память проекта в Claude Code - порядок чтения CLAUDE.md и AGENTS.md, импорт @AGENTS.md, версия 2.1.277.
• Открытый формат AGENTS.md - описание формата, список поддерживающих инструментов, приоритет ближайшего файла.
• Документация BSL Language Server - режим анализа командной строки.

Предшественники на Infostart:

• Cursor + MCP: собираем идеальное рабочее место 1С-разработчика за 15 минут (Ninel_S) - подключение MCP-серверов к Cursor. Здесь речь о файлах правил и памяти проекта.
• Расширение УТ 11 за 19 минут: бесплатные скиллы и память проекта (Часть 2) (Ibrogim, 25.09.2026) - замер времени работы агента со скиллами и памятью проекта. Здесь разобраны сами файлы памяти для двух инструментов и их приоритеты.
• 1C Skills для ИИ-агентов: инструменты для разработки, проверки и тестирования 1С (Aleksandr) - каталог навыков для агентов. Здесь - постоянные правила репозитория.

Идея держать правила в репозитории общая для этих инструментов. Своё в статье - сверка приоритетов по документации, импорт @AGENTS.md в CLAUDE.md, шаблоны для BSL и скрипт проверки, прогнанный из распакованного архива.

📎 Файл к статье

В архиве к статье - 13.9-companion.zip: шаблоны AGENTS.md, CLAUDE.md и 1c-bsl.mdc, скрипт check_rules.py и README.md. Архив прикреплён в блоке «Файлы» под текстом публикации.

Распакуйте архив в отдельную папку, запустите python check_rules.py, затем скопируйте шаблоны в корень своего репозитория 1С.

 

Нинель Адольевна Щербакова (Ninel_S)

Архитектор • SRE & DevOps инженер • HighLoad 1С

Автор 48 технических публикаций на Infostart. Разработчик NOPik, SRE-Suite-for-1C и мультиагентных ассистентов для экосистемы 1С:Предприятие.

Каталог статей и открытых репозиториев Ninel_S