Инструкции для AI-агентов

Назначение репозитория

Репозиторий разрабатывает единый скил skills/bsp/ для применения 1С:БСП 3.1.11. Скил содержит маршрутизатор SKILL.md, 24 тематических reference-файла и скрипт проверки API по выгрузке конфигурации.

Структура

skills/bsp/
  SKILL.md                 # маршрутизация по задачам
  agents/openai.yaml       # UI-метаданные и стартовый prompt для Codex
  references/*.md          # сценарии, сигнатуры, примеры, антипаттерны
  scripts/bsp_api.py       # поиск экспортных методов и регионов
ci/
  validate_key_methods.py  # проверка API-утверждений и покрытия
  run_skill_evals.py       # RED/GREEN поведенческие прогоны через cdx
evals/cases.json           # корпус пользовательских сценариев
tests/
  fixtures/                # синтетические BSL/Markdown-фикстуры
  test_*.py                # unit-тесты парсера и валидатора
.github/workflows/         # CI и выпуск архива с единым скилом bsp
install.sh                 # установка/обновление в Unix-подобных системах
install.ps1                # установка/обновление в PowerShell

vendor/agents-best-practices — внешний submodule для разработки. Не редактировать и не обновлять его commit без отдельной задачи. Локальные изменения внутри submodule принадлежат пользователю.

Локальные источники БСП

Эти каталоги находятся в .gitignore, не входят в поставку и доступны только в рабочем окружении разработчика:

bsp3111_md/  # документация БСП 3.1.11, основной источник
bsp321_md/   # документация БСП 3.2.1, только для явного сравнения версий
src/cf/      # XML-выгрузка конфигурации БСП 3.1.11

Файлы внутри этих каталогов разрешено только читать. Не редактировать, не перемещать и не добавлять их в Git.

При проверке факта сначала использовать документацию bsp3111_md/, затем подтверждать сигнатуру и регион по src/cf/. Если источники противоречат друг другу, явно описать противоречие. Не переносить факты из bsp321_md/ в скил 3.1.11 без проверки.

Навигация по локальной документации:

• начинать с bsp3111_md/index.md;
• не загружать целиком большой файл главы 3 — искать нужный фрагмент;
• считать 004_глава_4_программный_интерфейс.md оглавлением, а не справочником сигнатур;
• искать API в файле *_интерфейс.md нужной подсистемы и в следующих за ним файлах отдельных методов;
• не строить зеркальные ссылки между версиями 3.1.11 и 3.2.1: их структура различается.

Работа со скилом

• Сохранять единый umbrella-скил bsp; не возвращать старые каталоги bsp-core, bsp-data, bsp-ui-forms и bsp-ops.
• Держать SKILL.md коротким маршрутизатором. Подробности размещать на одном уровне в references/.
• Опираться на реальные имена общих модулей, методов и регионов БСП 3.1.11.
• Для публичного прикладного вызова предпочитать регион ПрограммныйИнтерфейс.
• Явно маркировать служебные, устаревшие и неэкспортные методы, а также хуки модулей *Переопределяемый.
• Оформлять проверяемые API-вызовы inline-сигнатурой `Модуль.Метод(...)`. Это формат, который читает CI-валидатор.
• Невозможные вызовы сопровождать явной формулировкой «не существует» или «не экспортируется», чтобы валидатор проверял отрицательное утверждение.
• Не ссылаться из скила на локальные планы, отчёты или номера строк исходной выгрузки как на обязательный контекст пользователя.

Проверки

После изменения скила или валидатора выполнить:

python -m unittest discover -s tests -v
python ci/validate_key_methods.py --coverage-only
python ci/validate_key_methods.py --src src/cf
python ci/run_skill_evals.py --dry-run

Если src/cf/ отсутствует, выполнить первые две команды и явно сообщить, что полная семантическая проверка не запускалась.

Для поведенческой проверки сначала выполнить быстрый RED/GREEN-прогон одного сценария через cdx, затем перед релизом полный прогон с тремя повторами:

python ci/run_skill_evals.py --case message-bound-to-field --runs 1
python ci/run_skill_evals.py --runs 3 --jobs 6

--jobs ограничивает число одновременных запусков cdx; каждый запуск использует отдельные файлы артефактов, а общий GREEN staging остаётся только для чтения.

Runner не должен изменять глобальные скилы. GREEN staging разрешён только в <dir>/.agents/skills/bsp; существующий каталог с таким именем нельзя перезаписывать.

При добавлении или переносе eval-сценария синхронно обновлять evals/reference-matrix.json. Матрица перечисляет все reference-файлы, включая ещё не покрытые (с пустым списком), и отдельно — сценарии без reference.

Порог покрытия обязателен: не снижать --min-claims, --min-files или --min-coverage для обхода ошибки. Сначала исправить извлечение утверждений или содержимое reference-файлов.

Для точечной проверки API использовать:

python skills/bsp/scripts/bsp_api.py method <ИмяМетода> --module <ИмяМодуля> --src src/cf
python skills/bsp/scripts/bsp_api.py module <ИмяМодуля> --src src/cf
python skills/bsp/scripts/bsp_api.py modules --src src/cf

Релиз

Workflow релиза упаковывает skills/bsp вместе с обоими установщиками в ZIP и tar.gz. README, команды установки и примеры должны всегда описывать именно эту структуру. После изменения установщиков выполнять их локальные smoke-тесты с --source / -SourceDirectory, не обращаясь к сети.