Правила разработки на 1С:Предприятии для ИИ-агентов и людей, с MCP-сервером.
Отличие от других наборов правил простое: каждое правило называет свой источник и свою проверку. Источник — ошибка, измерение или эксперимент на живом проекте, с датой. Проверка — то, что упадёт, если правило нарушить. Ни одного правила «вообще полезно знать»: такие не проверяются и не соблюдаются.
Правила разложены по направлениям: ядро платформы и отдельно каждая конфигурация — со своими правилами, глоссарием и картой объектов.
| Направление | Что покрывает | Правил | Терминов |
|---|---|---|---|
core |
язык, формы, метаданные, макеты, процесс — не зависит от конфигурации | 133 | 12 |
greenfield |
конфигурация с нуля: именование, языки, стиль, контур проверок, версии | 5 | — |
unf |
1С:УНФ — правила, термины, карта объектов | 2 | 10 |
bp |
1С:Бухгалтерия предприятия | открыто | — |
zup |
1С:Зарплата и управление персоналом | открыто | — |
erp |
1С:ERP Управление предприятием (типовая конфигурация «1С») | открыто | — |
maerp |
maERP — собственная конфигурация на платформе 1С | открыто | — |
Направление erp — это типовая конфигурация фирмы «1С». Проект maERP, на
который ссылаются источники правил, — собственная конфигурация на платформе 1С
и к 1С:ERP отношения не имеет.
«Открыто» значит, что направление заведено, а правил пока нет: своего проекта на этой конфигурации у нас не было, а выдуманное правило хуже отсутствующего.
Сервер работает по stdio: агент запускает его как обычный процесс у себя на машине. Хостинг, порты и сеть не нужны — нужен только Python 3.8+, никаких зависимостей.
claude plugin marketplace add bigsofter/tiny1C
claude plugin install 1c@tinycioКлонировать вручную не нужно: набор приезжает вместе с плагином. Версии у
плагина нет, поэтому версией служит коммит main: каждое слияние правил в
main для Claude Code - новая версия. Обновляется набор так:
- один раз включить автообновление маркетплейса:
/plugin- Marketplaces -tinycio- Enable auto-update (по умолчанию оно выключено у любого стороннего маркетплейса); новая версия подтянется в течение ~10 минут после начала сессии и применится в следующей сессии или после/reload-plugins; - либо вручную:
claude plugin update 1c@tinycio; - администратору - в managed settings:
extraKnownMarketplaces.tinycio.autoUpdate: true.
Какая версия набора запущена, видно в ответе сервера на initialize
(serverInfo.version - короткий хеш manifest.json).
Плагин приносит MCP-сервер (включая where_is), скиллы /1c:1c (когда и как
звать инструменты) и /1c:propose-rule (предложить новое правило или рецепт), а также
мягкий хук-напоминание. Подробности и Windows - в INSTALL.md.
git clone https://github.com/bigsofter/tiny1C{
"mcpServers": {
"tiny1c": {
"command": "python3",
"args": ["${TINY1C_HOME:-../tiny1C}/mcp/server.py"]
}
}
}Для Claude Code это .mcp.json в корне проекта, для остальных агентов — их
собственный файл конфигурации MCP. Переменная TINY1C_HOME позволяет не
писать в общий репозиторий путь конкретной машины. Обновление — git pull.
Codex CLI, DeepSeek Harness, Cursor, VS Code и прочие MCP-клиенты — готовые куски конфигурации в INSTALL.md. Там же способ для систем без MCP: выгрузка правил одним файлом в системную подсказку или в проектные инструкции.
scripts/export.py --направление core,greenfield --выход dist/rules.md| Инструмент | Зачем |
|---|---|
list_tracks |
какие направления есть и что в них лежит |
lookup_rule |
поиск по симптому: тексту ошибки (дословно), ключевому слову, id; учитывает словоформы и е/ё, ищет по заголовкам, ключам, разделу «Симптом» и по тексту правил |
get_rule |
полный текст правила |
lookup_guide |
поиск рецептов «как сделать»: по задаче, ключевому слову, id (how-001); для вопросов «как собрать/загрузить/проверить X», не для текста ошибки |
get_guide |
полный текст рецепта: задача, шаги, проверка результата, где ломается, ссылки на правила |
rules_by_category |
все правила категории (запросы, формы-xml, метаданные, расширения…) |
rules_for_object |
что известно про объект метаданных: правила и термины |
checklist |
что проверить перед правкой файла .bsl, .form, .mdo, .mxlx, .epf, .erf, .cfe; compact=true - только id, заголовок, серьёзность |
glossary_lookup |
термин предметной области → определение и объекты |
Плюс ресурс tiny1c://manifest — сокращённый индекс набора (без глоссариев,
симптомов и текстов правил; для отладки). Сервер отдаёт instructions
(«когда что звать») в ответе initialize; клиенты, которые их поддерживают,
передают их модели.
Кроме правил, сервер умеет разбирать XML-выгрузку конфигурации — локально, без
базы и без платформы. Эти инструменты включаются явно: флагом
--tools offline или переменной окружения TINY1C_TOOLS=offline (удобно,
когда аргументы запуска задаёт плагин). Без них сервер отдаёт прежние девять.
| Инструмент | Зачем |
|---|---|
where_is |
где объект в интерфейсе: раздел → подсистема → команда (в том числе собственная), группа панели, кому скрыт, функциональные опции, права, ссылка e1cib/…; по названию раздела — его состав |
{"mcpServers": {"tiny1c": {"command": "python3",
"args": ["${TINY1C_HOME:-../tiny1C}/mcp/server.py", "--tools", "offline"]}}}Аргумент dump — каталог выгрузки конфигуратора «Выгрузить конфигурацию в
файлы», формат «Иерархический» (в нём лежит Configuration.xml); за его пределы инструмент не читает, подменённый XML (DTD, сущности) отвергает.
Каждый инструмент описан карточкой в tools/<группа>/<имя>.md: откуда идея,
где исполняется, чем опасен, чем проверен и что пока не умеет. Инструмент без
проверки на фикстуре в сервер не попадает.
Группа instructions — для ИИ-помощника, который работает не с кодом, а
внутри базы 1С рядом с бухгалтером (в портале TinyCIO это «Татьяна»). Ему
нужно одним вызовом получить всё, что набор знает про конфигурацию базы, и
положить это в системный промпт. Включается так же, как offline:
--tools instructions (можно вместе: --tools offline,instructions); сетевой
режим включает её сам.
| Инструмент | Зачем |
|---|---|
match_config |
по фактам базы (Метаданные.Имя, версия, поставщик, синоним) — направление набора по паспортам profile.json; отдельно говорит, совпал ли поставщик и не ниже ли версия минимальной |
get_instructions |
пакет направления для системного промпта: профиль, «где это в 1С» и особенности в сжатом виде, чипы (общие из core и свои); если направление расширяет другое (ka/erp поверх ut) — сначала общее, потом добавки; include_core=true добавляет шпаргалки. Поле текст — готовый markdown; потолок 24 КБ проверяет манифест |
get_instructions_file |
один файл пакета целиком, как справочник: objects.md (карта объектов), faq.md (типовые вопросы), where_is.md, notes.md без сжатия — по запросу, когда сжатого пакета мало; строки [проверить] в нём есть, с оговоркой |
get_cheats |
шпаргалки платформы из tracks/core/cheats/*.md (язык запросов, регистры) |
Что лежит в пакете и как его завести — «Пакет инструкций по конфигурации».
Кроме stdio у сервера есть режим streamable HTTP (mcp/httpd.py) — для
сервисов, которые живут в одной внутренней сети с ним и не могут запускать
локальный процесс. Тот же набор инструментов и тот же код обработки, плюс:
- один эндпоинт
POST /mcpпо спецификации MCP (ревизии 2024-11-05…2025-11-25): JSON-RPC запрос или батч, ответ одним JSON (SSE — только если клиент принимает лишьtext/event-stream), уведомления —202, сессий нет,GET/DELETE—405; - доступ только по сервис-токену: заголовок
X-Service-Tokenдолжен совпасть с переменнойTINY1C_SERVICE_TOKEN; без неё сервис не стартует. Наружу его не публикуют: это служба внутренней сети, не веб-API; GET /healthzбез токена: ревизия знаний, время и итог последней синхронизации;- знания подтягиваются из git сами: раз в
TINY1C_SYNC_INTERVALсекунд (300) сервис смотрит веткуmainрепозитория, новую ревизию забирает в каталог данныхTINY1C_DATA, проверяет своимscripts/manifest.pyи подменяет снимок целиком; ревизию с ошибками не подключает и остаётся на прошлой (ошибка видна в/healthz). Код из git не исполняется никогда — он меняется только новым образом с закреплённой ревизией.
TINY1C_SERVICE_TOKEN=... python3 mcp/httpd.py --addr localhost:8111 --data /tmp/tiny1c-data
curl -s http://localhost:8111/healthz
curl -s http://localhost:8111/mcp -H 'X-Service-Token: ...' -H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' -H 'MCP-Protocol-Version: 2025-11-25' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"match_config","arguments":{"name":"БухгалтерияПредприятия"}}}'Контейнер — Dockerfile в корне: образ несёт код и встроенную копию набора на
момент сборки, знания — в томе /data, порт 8111, пользователь nobody.
Без --data сервис работает только на встроенной копии (режим для проверок).
Направление может нести, помимо правил для программиста, пакет инструкций
для помощника в базе: что знает набор про саму конфигурацию. Файлы лежат в
tracks/<направление>/, заготовка — tracks/_PACK_TEMPLATE/:
| файл | что внутри |
|---|---|
profile.json |
паспорт: как узнать конфигурацию и что в ней есть (ниже) |
where_is.md |
«что → раздел → путь → как открыть»: журналы, документы, отчёты, настройки |
objects.md |
карта объектов: документ → роль → чем закрывается; справочники; регистры (она же карта для программиста) |
notes.md |
особенности: чего в конфигурации нет, что считается иначе, что умеет только форма |
faq.md |
типовые вопросы пользователя и короткие ответы-маршруты |
chips.json |
подсказки-чипы: список записей id, заголовок, текст; необязательные тема, подсказка (что ввести), параметры (объект, как есть передаётся серверу), проверить: true (чип не отдаётся, пока не проверен). tracks/core/chips.json — общие чипы для всех конфигураций |
cheats/*.md |
шпаргалки платформы — только у core; первая строка # Заголовок; README.md в каталоге — происхождение, в набор не входит |
sources.md |
источники фактов (номера S-n, URL, даты) — для ревью; в пакет не входит и в промпт не попадает |
Что уходит в промпт, а что нет. Файлы пакета пишутся как справочник, а помощнику уходит сжатая выжимка:
get_instructions кладёт в текст профиль, where_is.md и notes.md, пропуская строки с пометкой [проверить]
(неподтверждённый факт помощнику не даётся вовсе), разделы с заголовком … (подробно), колонки таблиц «статус» и
«источник» и ссылки на источники в скобках — (S-5), (опыт), (из промпта); заголовок файла убирается, остальные
опускаются на уровень. objects.md и faq.md в промпт не идут — их целиком отдаёт get_instructions_file. Правила
сжатия — mcp/packtext.py, потолок сжатого текста на направление — 24 КБ, его считает scripts/manifest.py
(ключ размер_промпта); сырые файлы — до 96 КБ, шпаргалки — 24 КБ. В notes.md удобно держать раздел «Коротко»
(тезисы в промпт) и разделы «… (подробно)».
profile.json — объект с закрытым набором ключей (неизвестный ключ — ошибка
манифеста):
| ключ | обязателен | что |
|---|---|---|
семейство |
да | код семейства латиницей: bp, unf, ut… |
имена |
да | Метаданные.Имя конфигураций, без пробелов: ["БухгалтерияПредприятия", "БухгалтерияПредприятияКОРП"] |
тема |
да | о чём конфигурация: «учёт и налоги», «торговля и склад» |
синоним_re |
нет | регулярное выражение по синониму, если имя неизвестно |
мин_версия |
нет | минимальная версия вида 3.0.150 |
поставщики |
нет | список поставщиков, с которыми пакет совпадает: ["Фирма \"1С\""] |
признаки |
нет | {"бухгалтерия": true, "накопление": true, "расчёт": false} — какие регистры есть |
план_счетов, виды_субконто |
нет | имена для подстановки в шпаргалки |
без_кода |
нет | объекты «настройка без программирования» |
расширяет |
нет | код направления, чей пакет берётся за основу (ka → ut): его части идут первыми, свои — добавками |
Правила: пакет без profile.json — ошибка (конфигурацию не определить;
objects.md и chips.json без профиля допускаются — карта для программиста и
общие чипы core); расширяет — только на направление с пакетом, без циклов,
не длиннее трёх. Чистая комната та же, что у правил: без имён клиентов, людей,
баз и путей; факты из открытых источников — своими словами, URL только в
sources.md. В manifest.json пакет виден ключом инструкции направления
(профиль, файлы с sha и размером, размер_промпта, шпаргалки). Первый
пакет — tracks/bp (Бухгалтерия предприятия 3.0): часть путей и имён помечена
[проверить] и ждёт подтверждения по живой базе или руководству.
tracks/<направление>/
track.md паспорт: конфигурации, платформы, статус
rules/*.md правила, одно правило — один файл
guides/*.md рецепты «как сделать»: задача, шаги, проверка результата, ссылки на правила
glossary.md термины: термин | синонимы | объекты | пояснение
objects.md карта объектов конфигурации (необязательно)
profile.json, where_is.md, notes.md, faq.md, chips.json пакет инструкций (необязательно); sources.md - его источники
cheats/*.md шпаргалки платформы (только core)
tracks/_PACK_TEMPLATE/ заготовка пакета инструкций (направлением не считается)
tools/<группа>/<имя>.md карточки исполняемых инструментов
manifest.json машинный индекс, собирается из всего перечисленного
mcp/server.py MCP-сервер (stdio, без зависимостей); mcp/search.py - поиск правил
mcp/httpd.py сетевой режим (streamable HTTP, токен, /healthz); mcp/knowledge.py - знания из git
mcp/instructions.py группа instructions (match_config, get_instructions, get_instructions_file, get_cheats)
mcp/packtext.py сжатие файлов пакета для промпта ([проверить], «(подробно)», колонки статуса)
mcp/snapshot.py снимок набора: манифест + корень дерева
skills/ скиллы плагина Claude Code (1c, 1c-propose)
hooks/ мягкий хук плагина (напоминание, ничего не блокирует)
mcp/tools/ реализации инструментов (только stdlib)
fixtures/ синтетические выгрузки для проверки инструментов
tests/ проверки инструментов: golden-ответы на фикстурах; tests/fixtures/knowledge - набор для сетевого режима
scripts/ сборка манифеста, проверка гигиены, прогон инструментов
Dockerfile образ сетевого режима
Сборка и проверки:
scripts/manifest.py # пересобрать manifest.json
scripts/manifest.py --проверить # проверить формат и актуальность (для CI)
scripts/manifest.py --корень ДИР # то же для другого дерева набора (так сервис проверяет свежую ревизию)
scripts/hygiene.py # что не должно уехать в публичный репозиторий
scripts/hygiene.py --файл x.md # проверить одно правило или рецепт вне дерева (черновик, конверт)
scripts/tools-check.py # инструменты на фикстурах (golden-ответы), сетевой режим, подгрузка знаний---
id: bsl-006
направление: core
категория: модули
серьёзность: критично
платформы: [8.3, 8.5]
заголовок: "ЕстьNULL — функция языка запросов, во встроенном языке её нет"
ключи: [ЕстьNULL, NULL, компиляция]
источник: "ошибка:maERP 2026-09-02, панель сведений в 19 формах списков"
check: ["checkconfig-ext:разбор модулей форм", "smoke-forms:форма не открывается"]
---check пишется как «вид:описание». Виды: lint, checkconfig,
checkconfig-ext, smoke-forms, smoke-samples, smoke-print, fixtures,
refcheck, xml-audit, manual. Вид manual — честное признание, что правило
ловится только человеком; таких сейчас 39 из 140, и это видно в манифесте.
Рецепт — файл tracks/<направление>/guides/how-NNN.md (шаблон —
tracks/_GUIDE_TEMPLATE.md). Правило отвечает на «что нельзя и почему», рецепт
— на «как сделать, по порядку».
---
id: how-001
направление: core
категория: расширения
платформы: [8.3, 8.5]
заголовок: "Собрать расширение из исходников и применить его в копии базы"
источник: "практика:проект 2026-10-12, цикл загрузки расширения в копию"
задача: "В файловой копии базы: расширение из каталога исходников загружено, применено и активно"
ключи: ["LoadConfigFromFiles", "-Extension", "UpdateDBCfg"]
check: ["manual:расширение в списке расширений копии активно"]
правила: [ext-002, ext-004]
---Тело — три раздела: ## Шаги, ## Проверка результата, ## Где ломается
(последний может быть пустым). Серьёзности у рецепта нет. Рецепт — порядок
шагов; факты и запреты живут в правилах, на которые он ссылается полем
правила, и при расхождении главнее правило. Вид источника практика —
порядок, проверенный в деле.
scripts/new-rule.py core forms-011 "Короткий заголовок" # заготовка из шаблона
# заполнить: категория, источник, check, текст
scripts/manifest.py && scripts/hygiene.py # пересобрать и проверитьРецепт заводится так же: scripts/new-guide.py core how-007 "Короткий заголовок".
Подробнее — в CONTRIBUTING.md. Откуда что взялось и что сознательно не заимствовано — в PROVENANCE.md.
Тексты правил, глоссарии и карты объектов — CC BY 4.0. Код (сервер, скрипты) — MIT. Берите с указанием авторства.