1c-rules — набор правил и инструментов разработки на 1С для ИИ-агентов

Если ты ИИ-агент и тебе нужно установить или обновить правила в проекте, перейди к AGENT-INSTALL.md и следуй инструкциям оттуда. Текущий файл — обзор для разработчика.

1c-rules — это переносимый набор правил, ролей субагентов, on-demand инструкций и интеграций для разработки в 1С:Предприятие 8 (BSL) с помощью ИИ-агентов. Содержимое раскладывается в проект единым установщиком и адаптируется под формат каждого инструмента.

Под какие ИИ-агенты адаптированы правила

Правила и команды собираются под конкретный инструмент адаптерами из adapters/*.yaml. Поддерживаются:

• Cursor (.cursor/rules/, .cursor/commands/)
• Claude Code (.claude/rules/, .claude/agents/, .claude/commands/)
• OpenAI Codex (.codex/rules/, .codex/agents/, .codex/skills/, .codex/config.toml; slash-команды ставятся в пользовательский ~/.codex/prompts/)
• OpenCode (.opencode/command/)
• Kilo Code (.kilo/rules/, .kilo/commands/, .kilo/agents/, .kilo/skills/)
• Прочее (other, универсальный fallback) (.ai-agent/rules/, .ai-agent/agents/, .ai-agent/commands/, .ai-agent/skills/, .ai-agent/mcp.json) — для любого ИИ-клиента, которого нет в списке выше (Aider, Cline, Continue, Cody и т.п.). Ничего не автодетектится — выбирается вручную при установке. На диск пишутся максимально портабельные правила: AGENTS.md в корне (де-факто стандарт для современных агентов), а on-demand-правила и описания субагентов — по нейтральным путям под .ai-agent/ с минимальной frontmatter (description + alwaysApply).

Один и тот же исходный набор правил из content/ раскладывается во все активные инструменты одновременно, поэтому AGENTS.md, on-demand правила и описания субагентов остаются согласованными независимо от того, в каком клиенте вы работаете.

Как попросить агента поставить правила

Установка спроектирована как протокол, который выполняет сам ИИ-агент. Откройте проект в любимом ИИ-агенте (Cursor / Claude Code / Codex / OpenCode / Kilo Code) и отправьте сообщение:

Установи правила из https://github.com/comol/ai_rules_1c по AGENT-INSTALL.md.

Всё. Остальное — клонирование репозитория, определение активных инструментов, миграция существующих AGENTS.md / CLAUDE.md, запросы перед разрушительными действиями — описано в AGENT-INSTALL.md, который агент прочитает сам.

Fallback: PowerShell-установщик

Если агент не справляется (ограниченная среда, нет FS-доступа, нужен детерминированный CI-запуск) — тот же протокол реализован как PowerShell-скрипт install.ps1:

git clone https://github.com/comol/ai_rules_1c.git $env:TEMP\1c-rules
& $env:TEMP\1c-rules\install.ps1 init -Source $env:TEMP\1c-rules

Имя локальной папки произвольное: в примерах используется 1c-rules, но установленный или рабочий каталог может называться иначе.

Параметр -Source также принимает URL напрямую — в этом случае установщик сам делает shallow-clone в кэш под $env:TEMP (ключ кэша — хэш URL) и переиспользует его при повторных запусках; требует git в PATH:

.\install.ps1 init -Source https://github.com/comol/ai_rules_1c

Команды: init / update / add <tool> / remove [<tool>] / doctor / eject.

Что внутри

• Корневой свод правил — AGENTS.md: исходный always-on контекст для ИИ-агента: персона, процедура разработки, принципы, перечень MCP-инструментов и их использование, стандарты кода, дисциплина вызовов инструментов. В этом репозитории он хранится в корне для удобного просмотра и поддерживается как читаемый документ без обязательных плейсхолдеров путей.
• Пользовательские правила — USER-RULES.md: пустой по умолчанию файл для команды/проекта. Установщик его не перезаписывает.
• Память проекта — memory.md: строгий долговременный слой для глобальных критичных правил проекта. Маршрутизация между memory.md и векторной памятью remember / recall описана в AGENTS.md → Project memory; это не общий блокнот.
• Параметры проекта — .dev.env: единый источник правды для всех правил, on-demand-инструкций, слэш-команд и субагентов. Содержит и параметры генерации кода (PREFIX, COMPANY, DEVELOPER, PLATFORM_VERSION, шаблоны комментариев, NEW_OBJECTS_IN), и параметры подключения к ИБ для команд и тестов (PLATFORM_PATH, INFOBASE_KIND/INFOBASE_PATH, IB_USER/IB_PASSWORD, EXTENSION_NAME, EXPORT_PATH, LOG_PATH, INFOBASE_PUBLISH_URL для веб-тестов). Установщик создаёт .dev.env автоматически на init, заполняет автодетектом PLATFORM_VERSION (из Configuration.xml), PLATFORM_PATH (поиск в C:\Program Files\1cv8\) и PREFIX (из NamePrefix расширения), запрашивает остальное в интерактивном режиме. В -NonInteractive оставляет пустые поля с явным WARNING. Шаблон — .dev.env.example.
• Установщик — install.ps1: PowerShell-инсталлятор (команды init / update / add / remove / doctor / eject).
• Спецификация установщика — AGENT-INSTALL.md: что пишется/обновляется на диске, как происходит миграция и что принадлежит установщику.

Структура репозитория

.
├── AGENTS.md                # шаблон основного свода правил (always-on контекст после установки)
├── AGENT-INSTALL.md         # инструкция установки для ИИ-агентов
├── USER-RULES.md            # пользовательские правила (не трогается установщиком)
├── memory.md                # память проекта
├── install.ps1              # PowerShell-установщик
├── .dev.env.example         # шаблон параметров проекта
├── adapters/                # адаптеры под инструменты (cursor, claude-code, codex, opencode, kilocode)
├── content/
│   ├── rules/               # on-demand правила, подключаемые по задаче
│   ├── agents/              # описания 13 специализированных субагентов
│   ├── commands/            # слэш-команды (doctor, deploy-and-test, getconfigfiles, loadfrom1cbase, update1cbase, checkmcp, installmcp, updatemcp, update)
│   ├── skills/              # SKILL-пакеты (1c-metadata-manage, mermaid-diagrams и др.)
│   ├── openspec-bundle/     # снапшот вывода `openspec init` для каждого инструмента
│   └── mcp-servers.json     # каталог MCP-серверов экосистемы 1С
├── openspec/                # OpenSpec-воркспейс (specs/, changes/, project.md)
└── tools/                   # вспомогательные скрипты (refresh-openspec-bundle.ps1)

Что появится в проекте после установки

Независимо от канала установки (агент или install.ps1) на диске будет:

• AGENTS.md, USER-RULES.md, memory.md — в корне проекта. Это требование инструментов: Cursor, Claude Code, Codex, OpenCode, Kilo Code читают AGENTS.md именно из корня; перенос в .cursor//.claude/ отключит загрузку.
• директории активных инструментов (.cursor/, .claude/, .codex/, .opencode/, .kilo/ — для Kilo Code MCP пишется в .kilo/kilo.json под ключом mcp; legacy .kilocode/mcp.json больше не используется и автоматически удаляется при update) — для каждого детектированного. On-demand правила лежат в <tool>/rules/ соответствующего инструмента, не дублируются в отдельный «общий» каталог.
• openspec/ — OpenSpec-воркспейс (если ещё не было).
• .ai-rules.json — манифест с перечнем размещённых файлов, активных инструментов, выбранным каноническим каталогом on-demand правил и версией.

AGENTS.md ссылается на on-demand правила по пути одного канонического каталога (приоритет cursor → claude-code → kilocode → opencode → codex → other; other становится каноном только когда выбран без «реального» инструмента). При установке только под один инструмент в проекте появится ровно одна тулзовая директория плюс AGENTS.md/USER-RULES.md/memory.md в корне — без дополнительных общих папок.

Если активен ровно один инструмент, агент-установщик не задаёт уточняющих вопросов. PowerShell-fallback дополнительно поддерживает флаги -Tools cursor,claude-code, -NonInteractive, -AssumeYes. Полный протокол и описание манифеста — в AGENT-INSTALL.md.

Свод on-demand правил (content/rules/)

Подгружаются ИИ-агентом по задаче, когда сценарий совпадает с описанием правила. Полный и авторитетный список входных точек находится в AGENTS.md → Additional rules; список ниже — обзор по группам.

• coding-standards.md — краткий индекс стандартов кода и ссылок на детальные правила.
• dev-standards-core.md — параметры проекта, стиль кода, шаблоны комментариев модификаций, нейминг, заголовки документации.
• dev-standards-architecture.md — архитектурные паттерны, расширения, стандарты платформы, code smells.
• dev-standards-forms.md — правила доработки управляемых форм (программная модификация типовых форм, размещение элементов, проверка заполнения, команды формы).
• module-structure.md — канонические шаблоны регионов для общих модулей, модулей объектов и менеджеров, модулей форм; директивы препроцессора; обязательные регионы.
• forms.md — единая точка входа для задач по управляемым формам; выбирает нужные companion-правила для Form.xml, Form.Module.bsl, событий, async, reserved names и XML-валидации.
• forms-add.md / forms-events-add.md / form-module.md — генерация форм, событий и работа с модулем формы.
• form-reserved-names.md — зарезервированные имена свойств в модулях форм (запрет на локальные переменные ПараметрыВыбора, СвязиПараметровВыбора, СписокВыбора, ПараметрыОтбора, ОтборСтрок).
• async-methods.md — практическое руководство по Асинх / Ждать / Обещание (платформа 8.3.18+) с типичными паттернами и ловушками (тихая потеря исключений без Ждать, Асинх в обработчиках событий формы, HTTP-async).
• extension-patterns.md — паттерны расширений (CFE): типы перехватчиков, правила ПродолжитьВызов, маркеры #Вставка / #Удаление, ограничения заимствованных объектов, антипаттерны.
• dcs-design.md — правила проектирования отчётов на СКД: выбор типа наборов данных, вычисляемые поля vs ресурсы, параметры и пользовательские настройки, варианты, программный override компоновки, взаимодействие с RLS, чек-лист производительности.
• registers-design.md — проектирование регистров (сведений, накопления, бухгалтерии, расчёта): измерения и ресурсы, периодичность, индексирование, подчинение регистратору, остатки vs обороты, проведение и перепроведение.
• metadata-xml-workarounds.md — типовые ошибки при ручной генерации метаданных XML (отсутствие LineNumber в табличных частях, опечатка PagesGroupExtInfo, обязательный Page.enabled, уникальность UUID).
• tooling-playbooks.md — пошаговые MCP-плейбуки под типовые задачи (написание кода, ревью, архитектура, исправление ошибок, оптимизация, рефакторинг, метаданные XML, формы, интеграции, документация, сравнение версий платформы).
• subagents.md / subagent-pipeline.md — каталог субагентов и формализованный pipeline для full-cycle задач.
• getconfigfiles.md — выгрузка объектов метаданных из информационной базы в репозиторий.
• integrations-add.md — правила для интеграций (HTTP-сервисы, REST, очереди).
• refactor-add.md — чек-лист безопасного рефакторинга.
• sdd-integrations.md — правила работы с OpenSpec.
• logging-strategy.md — позитивная стратегия логирования: когда писать в ЖурналРегистрации, уровни, нейминг событий, структура Данные, запрет на секреты / PII, ротация.
• locks-and-transactions.md — управляемые блокировки, границы транзакций, фиксированный порядок блокировок, предотвращение взаимных блокировок, режимы блокировок, диагностика через техжурнал.
• anti-patterns.md — каталог 1С анти-паттернов и рубрика код-ревью.
• systematic-debugging.md / verification-checklist.md — методика отладки и итоговый gate готовности.
• platform-solutions.md — типичные ловушки платформы и проверенные шаблоны решений (включая фоновые задания из внешней обработки через БСП).

Специализированные субагенты (content/agents/)

Тринадцать ролей под конкретные задачи: 1c-explorer, 1c-analytic, 1c-planner, 1c-architect, 1c-arch-reviewer, 1c-developer, 1c-metadata-manager, 1c-refactoring, 1c-performance-optimizer, 1c-error-fixer, 1c-tester, 1c-code-reviewer, 1c-doc-writer. Когда какой использовать — описано в content/rules/subagents.md (точка входа из AGENTS.md → Skills and Subagents).

SKILL-пакеты (content/skills/)

Скиллы — это самодостаточные подключаемые модули с собственной документацией и (опционально) скриптами/инструментами. Активный инструмент подхватывает их из своего skills/-каталога. В поставке:

1c-metadata-manage — управление структурой метаданных 1С

Главный скилл для работы с метаданными конфигурации: создание, редактирование, валидация, удаление объектов, форм, отчётов, макетов, ролей, расширений, баз. Скилл — диспетчер: по ключевым словам задачи он направляет агента в нужный домен и при сложных мутирующих сценариях делегирует работу субагенту 1c-metadata-manager. Все XML-операции выполняются через скрипты в tools/, которые корректно обрабатывают BOM, кодировки, UUID, порядок ChildObjects и кросс-ссылки — то, что легко сломать ручной правкой.

Покрываемые домены:

• Объекты метаданных (meta-manage.md) — справочники, документы, регистры (сведений, накопления, бухгалтерии, расчёта), перечисления, константы, общие модули, реквизиты, табличные части.
• Управляемые формы (form-manage.md) — создание, редактирование, анализ, валидация Form.xml, элементов, команд, событий.
• Схемы компоновки данных, СКД (skd-manage.md) — отчёты, наборы данных, запросы СКД.
• Табличные документы, MXL (mxl-manage.md) — макеты, печатные формы, декомпиляция MXL.
• Роли и права (role-manage.md) — права, RLS, разграничение доступа.
• Внешние обработки и отчёты (epf-manage.md) — каркас, сборка, дамп EPF/ERF.
• Конфигурации и расширения (cf-manage.md, cfe-manage.md) — создание, диффы, патчи, регистрация в БСП (bsp-manage.md).
• Базы данных (db-manage.md) — реестр, создание, запуск, загрузка/выгрузка ИБ.
• Подсистемы и командный интерфейс (subsystem-manage.md, interface-manage.md).
• Макеты и шаблоны, справка (template-manage.md, help-manage.md), паттерны БСП (ssl-patterns.md).
• Запросы — написание новых (query-writing.md) и оптимизация (query-optimization.md).
• Веб-публикация (web-manage.md) — публикация/снятие, статус, smoke-тесты для Apache/IIS.
• Распаковка бинарников без платформы 1С (v8unpack-cf.md) — извлечение и сборка CF/CFE/EPF через Python-утилиту v8unpack (для CI без 1С на хосте, оффлайн-инспекции стороннего расширения, partial-rebuild пайплайнов).

Сопутствующие скиллы

• mcp-1c-tools — диспетчер MCP-серверов экосистемы 1С: каталог серверов, маршрутизация задач, fallback-цепочка (graph → code-metadata → grep=true retry → Grep), параметрические подсказки. Подгружается до выбора любого 1С MCP-инструмента; per-server описания — в docs/<server>.md.
• caveman — стиль общения для разработческих задач: краткие рабочие ответы на русском, без лишнего объяснения. Включён для реализации, отладки и деплоя; выключен для ревью, анализа, аудита и пользовательской документации.
• img-grid-analysis — наложение пронумерованной сетки на изображение для определения пропорций колонок. Используется при генерации MXL-макетов из скриншотов или сканов печатных форм; даёт коэффициенты ширины колонок для JSON-DSL компилятора.
• mermaid-diagrams — практическое руководство по диаграммам Mermaid, совместимым с большинством рендереров (плюс ASCII-сайдкары для просмотра в чистом Markdown).
• powershell-windows — правила скриптинга в Windows PowerShell (разделители команд, кавычки путей, замены curl/timeout/&&, Docker, HTTP, JSON). Подгружается, когда правила выполняют shell-команды на Windows.
• md-to-docx — конвертация Markdown в Word-документ (.docx) c сохранением заголовков, таблиц, списков, кода, ссылок и инлайн-изображений. Требует Node.js и пакет docx.
• prompt-enhancer — превращение короткой неструктурированной заметки или ТЗ в подробную императивную постановку с пронумерованными шагами анализа, явными граничными случаями и фиксированным форматом вывода. Сохраняет термины и не добавляет новых требований.
• transcribe — транскрибация аудио и видео через Gemini 2.5 Flash API: дословная расшифровка с таймкодами, опциональное саммари, режим --analyze-ui для разбора экранного интерфейса со скриншотами. Требует Python, ffmpeg и GEMINI_API_KEY.
• handoff — сжимает текущий разговор в самодостаточный handoff-документ для следующей сессии (новый чат, другая машина, другой ИИ-клиент). Не дублирует durable-артефакты (openspec/, memory.md, коммиты, заметки в 1c-templates-mcp), а ссылается на них. Дефолтный путь — handoffs/handoff-<timestamp>.md в корне проекта. Адаптировано из mattpocock/skills.

MCP-серверы экосистемы 1С

Правила рассчитаны на работу совместно с пакетом MCP-серверов от vibecoding1c.ru/mcp_server (Docker-контейнеры, поднимаются локально по HTTP). Все серверы опциональны: правила содержат graceful fallback, если конкретный MCP не поднят. Каталог адресов и идентификаторов — в content/mcp-servers.json. Единый источник правды по MCP-маршрутизации, fallback-порядку и таблицам инструментов — скилл mcp-1c-tools (content/skills/mcp-1c-tools/SKILL.md, разделы docs/<server>.md); плейбуки под типовые задачи — в content/rules/tooling-playbooks.md.

1c-graph-metadata-mcp — граф метаданных (Neo4j/Cypher)

Основной инструмент для глубокого анализа конфигурации. Метаданные индексируются как граф связей, что даёт многоуровневый impact-анализ и понимание архитектуры в терминах бизнес-сущностей.

• get_object_dossier — полное «досье» объекта одним вызовом: реквизиты, табличные части, измерения/ресурсы, формы, подписки, роли, зависимости (USED_IN, движения регистров), модули с сигнатурами процедур, бизнес-описание.
• trace_impact — рекурсивный impact-анализ глубиной 1–10 по USED_IN / DO_MOVEMENTS_IN / CALLS. «Если изменю X — что ещё затронет?» Используется перед рефакторингом.
• trace_call_chain — рекурсивный обход графа вызовов BSL (callees / callers, глубина 1–10), с дизамбигуацией одноимённых процедур по объекту-владельцу.
• search_code — поиск по коду конфигурации: fulltext (Lucene), semantic (по смыслу), hybrid. Уровни детализации L0–L3 (от полного кода процедуры до минимальных карточек) для управления токенами.
• search_metadata — JSON-шаблоны Cypher-запросов (детерминированные) или NL → Cypher: списки атрибутов, объектов категории, форм, значений перечислений, измерений и т.д.
• search_metadata_by_description — Lucene-fulltext + опционально вектор по Синоним / Комментарий / Описание / Справка.
• business_search / answer_metadata_question — семантический поиск по бизнес-описаниям и Q&A на естественном языке.
• find_objects_using_object / find_usages_of_object / find_register_movement_docs / resolve_qualified_name / find_by_guid / compare_base_and_extension — точечные обходы графа.

1c-code-metadata-mcp — поиск кода/метаданных, формы, XSD

Базовый «индекс» конфигурации (используется как fallback к графовому MCP).

• Метаданные: metadatasearch (FTS/семантика, режим names_only для компактных списков), get_metadata_details (полная структура объекта по имени).
• Код: codesearch (гибридный поиск), search_function (структурный FTS-индекс по процедурам/функциям с экзакт+fuzzy), get_module_structure (содержимое модуля), get_method_call_hierarchy (плоский call-граф), graph_dependencies (плоские зависимости forward/reverse), bsl_scope_members (доступные методы/свойства/события для BSL-контекста).
• Формы: search_forms (поиск форм по элементам, реквизитам, командам), inspect_form_layout (полное дерево формы — иерархия элементов, привязки, обработчики).
• XSD и валидация: get_xsd_schema (XSD под Справочник, Документ, РегистрСведений и пр., в т.ч. подобъекты Форма / СКД / Макет) и verify_xml (валидация XML-строки против XSD).
• Справка: helpsearch (поиск по HTML-справке).
• Администрирование: reindex, stats.

1c-syntax-checker-mcp — синтаксис BSL

syntaxcheck — проверка кода через BSL Language Server. Лимит — до 3 вызовов этого валидатора на цикл (одна логическая правка одного модуля). После лимита фиксируются содержательные ошибки, остальное — игнорируется.

1c-templates-mcp — шаблоны и долговременная память проекта

• templatesearch — гибридный поиск (вектор + fulltext) по библиотеке из 2000+ шаблонов и архитектурных паттернов 1С. Вызывается до написания кода.
• remember — сохранение проектного факта/корректировки/нетривиального решения в векторную память (одна самодостаточная заметка на запись, на английском, с сохранением оригинальных имён объектов/модулей 1С).
• recall — векторный поиск по сохранённым заметкам. Используется в начале нетривиальной задачи с ключевыми терминами (имя объекта, подсистема, текст ошибки).

Маршрутизация между этой памятью и memory.md описана в разделе AGENTS.md → Project memory (всегда подгружается вместе с правилами).

1c-ssl-mcp — Библиотека Стандартных Подсистем (БСП)

ssl_search — поиск стандартных функций БСП (любой версии) по точному имени и по семантике. Перед написанием новой служебной процедуры агент проверяет, нет ли готовой в БСП, чтобы «не изобретать велосипед».

1C-docs-mcp — справка платформы 1С

Поиск по официальной справке конкретной версии платформы — критично, потому что сигнатуры и поведение меняются между версиями.

• docinfo — точечный поиск по известному имени объекта/метода (ТаблицаЗначений, Массив.Найти, Запрос).
• docsearch — гибридный (вектор + BM25) поиск по описанию, когда точное имя неизвестно.

1c-code-check-mcp — 1С:Напарник и ИТС

Доступ к коммерческому сервису 1С:Напарник в роли субагента + поиск по ИТС.

• Анализ кода: check_1c_code (синтаксис, логика, производительность), review_1c_code (стиль, стандарты ИТС, нейминг, структура), rewrite_1c_code / modify_1c_code (переписывание/целевые правки), ask_1c_ai (свободный диалог с сохранением контекста).
• Документация и база знаний: search_1c_documentation (документация под конкретную версию платформы), onec_help (актуальная справка), its_help → fetch_its (поиск по ИТС-стандартам с обязательным дочитыванием полной статьи), diff_1c_documentation_versions (диффы между версиями платформы), config_help (документация по конкретным конфигурациям — ERP, БП, ЗУП, УТ).

Лимит на check_1c_code / review_1c_code — до 3 вызовов каждого валидатора на цикл, как и у syntaxcheck. Output AI-инструментов всегда перепроверяется через syntaxcheck + check_1c_code + review_1c_code перед сдачей кода.

OpenSpec

Установщик безусловно разворачивает OpenSpec-воркспейс (openspec/) с режимом «не перезаписывать существующее». Слэш-команды /opsx:propose, /opsx:apply, /opsx:archive, /opsx:explore разворачиваются автоматически для каждого активного инструмента из набора cursor, claude-code, codex, opencode, kilocode (бандлы — в content/openspec-bundle/<tool>/). Для адаптера other (универсальный fallback) тулз-нейтрального бандла нет — слэш-команды OpenSpec автоматически не разворачиваются; пользователь подключает их вручную, работая напрямую с openspec/specs/ и openspec/changes/. Подробности — в openspec/README.md.

Ссылки

• vibecoding1c.ru — портал по вайбкодингу для 1С: курсы, бенчмарк моделей, статьи, продукты для разработки 1С с ИИ.
• vibecoding1c.ru/mcp_server — пакет MCP-серверов для 1С, под который заточены правила и плейбуки этого репозитория.
• Telegram-канал «IT Does Matter» — обсуждение вайбкодинга для 1С, MCP, ИИ-агентов, практик и обновлений.

Лицензия

Никакой лицензии, берите и используйте как хотите