内容
# v8std-standards-harness
**Обвязка, которая не даёт ИИ-агенту молча пропустить сверку со стандартами разработки
1С:Предприятие.**
Навык + карта ситуаций + машинная проверка отметок. Работает по правилу «запрет по
умолчанию»: не подтверждено — не пропускаем.
<p align="center">
<sub>Работа агента идёт слева направо через четыре ступени. <b>TRIGGER MAP</b> — карта в двух проекциях
(по объекту метаданных и по действию в коде) выдаёт номера стандартов. <b>SEARCH</b> и <b>SENTINEL</b> обращаются
к внешнему сервису <b>v8std MCP</b>: первый ищет то, чего нет в карте, второй проверяет, что сервис жив;
если сервис молчит — <b>RETRY x3</b> и <b>OFFLINE CACHE</b>, а исход честно попадает в отметку <b>SKIPPED</b>.
<b>VALIDATOR</b> работает в двух режимах (<b>LINT</b> / <b>GATE</b>) по настройкам <b>CONFIG</b> и пропускает в коммит
только при наличии отметок <b>EVIDENCE</b> — четырёх видов, где <b>SKIPPED</b> обязателен вместе с причиной.
Найденное вне карты возвращается в неё стрелкой <b>PROMOTE</b>: карта пополняется, а не стареет.</sub>
</p>
---
## Проблема
Вы допустили ИИ-агента к боевому BSL и написали в инструкции: «сверяйся со стандартами
разработки».
Агент отвечает «сверился». Иногда действительно сверяется. **Отличить одно от другого
невозможно** — невыполнение инструкции выглядит ровно так же, как выполнение. Узнаёте вы
об этом на проверке кода, а чаще — уже в работающей базе.
Дело не в недобросовестности модели. Стандартов около трёхсот; без карты «в этой ситуации
смотри вот эти» проверка превращается в «вспомни всё, что знаешь про 1С». Модель вспоминает
приблизительно — и уверенно.
## Решение: четыре слоя
Ни один слой не самодостаточен. Каждый закрывает дыру, оставленную остальными.
| Слой | Что ловит | Что протекает без него |
|---|---|---|
| **1. Карта ситуаций** | Известные случаи: «пишешь запрос → std729/437/438» | Агент сверяется по настроению и по памяти |
| **2. Обязательный поиск** | Стандарты вне карты — минимум один `v8std_search` за этап | Карта замерзает в моменте создания |
| **3. Сторожевая проверка** | Устаревший или недоступный указатель стандартов | «Ничего не нашлось» неотличимо от «сервис лежит» |
| **4. Проверка отметок** | Саму молчаливую деградацию — отсутствие следа проверки | Слои 1–3 остаются рекомендацией |
Ключевая идея четвёртого слоя: **пропуск разрешён, молчаливый пропуск — нет.** Каждая
проверка оставляет одну машинно-читаемую строку, и `skipped` с причиной из закрытого списка
— полноправный, ожидаемый исход. Невозможен только третий вариант: не проверить и не
сказать об этом.
```
[v8std applied: phase=implement, scope=document-posting, ids_checked=[std450,std603], conclusion=clean]
[v8std skipped: phase=implement, scope=query-virtual-table, planned_ids=[std657], reason=timeout, retries=3]
[v8std discovered: phase=implement, scope=document-posting, query="проведение движения", top_ids=[std450,std792], new_ids=[std792], decision=applied]
[v8std sentinel: id=std792, status=found, phase=implement]
```
## Что внутри
| Файл | Назначение |
|---|---|
| [`SKILL.md`](SKILL.md) | Навык: когда срабатывает, что делать, формат записей |
| [`references/standards-map.md`](references/standards-map.md) | Карта по **объекту метаданных**: «создаёшь регистр → …», «настраиваешь RLS → …» |
| [`references/situations.md`](references/situations.md) | Карта по **действию в коде**: «пишешь `ОбработкаПроведения` → …», «составной тип в запросе → …» |
| [`references/INSTALL.md`](references/INSTALL.md) | Пошаговая установка — рассчитана на выполнение агентом |
| [`references/field-notes.md`](references/field-notes.md) | Почему слоёв именно четыре: случаи из практики, из которых каждый вырос |
| [`tools/`](tools/) | Программа проверки, её тесты, пример настроек |
## Быстрый старт
```bash
# 1. Подключить MCP стандартов (Claude Code — .mcp.json, Codex — ~/.codex/config.toml)
# { "mcpServers": { "v8std": { "type": "http", "url": "https://ai.v8std.ru/mcp" } } }
# 2. Проверить, что сервис отвечает
# v8std_get_page("std792") → found=true
# 3. Проверить программа проверки
node tools/v8std-evidence-validator.smoke.mjs # ожидается 0 failed
# 4. Прогнать проверку в строгом режиме
node tools/v8std-evidence-validator.mjs validate-pack . --gate
```
Подробно, включая подключение к сборке и создание локального кэша, — [`references/INSTALL.md`](references/INSTALL.md).
## Два режима проверки
| Профиль | Поведение | Для чего |
|---|---|---|
| `lint` | Проверяет только оформление найденного. Ноль записей = чисто | Ручной прогон |
| `gate` | Запрет по умолчанию: нужна минимум одна запись, сторожевая с совпадающим `id`, поиск или обоснованный пропуск. **Ноль записей = ошибка** | Сборка, проверка перед коммитом |
Разделение появилось после того, как выяснилось: программа проверки на каталоге без единой записи
возвращал «чисто». То есть проект, где стандарты не применялись вообще — ровно целевой
отказ — проходил проверку зелёным. **У проверки «ничего не найдено» и «всё в порядке»
обязаны быть разными исходами.**
## Требования
- 1С:Предприятие (BSL) — карты предметно привязаны к платформе
- ИИ-агент, пишущий или проверяющий код
- Node.js 18+ для программы проверки (внешних зависимостей нет)
- Доступ к `https://ai.v8std.ru/mcp` — либо локальный кэш, собранный по инструкции
## Не на 1С?
Содержимое карт вам не подойдёт, но переносимо главное — приём проверяемого пропуска:
типы записей, обязательные поля, различие `lint`/`gate` и правило «ноль записей ≠ чисто».
Раздел «Перенос идеи на другую платформу» в [`references/INSTALL.md`](references/INSTALL.md).
## Границы честности
Пакет не притворяется тем, чем не является:
- **Не анализирует код.** `v8std` — справочник стандартов и диагностик, он не заменяет
синтаксическую проверку, статический анализатор и тесты.
- **Не гарантирует правильность применения.** Валидатор проверяет наличие и формат следа,
а не качество решения. Это защита от пропуска, а не от ошибки.
- **Не проверяет существование стандартов.** Валидатор работает офлайн: `std99999` формально
валиден и пройдёт. Ловится это слоями 1–3 — реальным обращением к сервису, а не разбором
отметок. Проверка отметок защищает от пропуска сверки, а не от намеренной подделки следа.
- **Сторожевая проверка не доказывает актуальность карты.** Она ловит недоступность сервиса
и откат указателя назад, но не то, что он ушёл вперёд, а карта осталась в прошлом.
- **Признаки ситуаций (`smell_patterns`) сегодня никем не исполняются** — это
структурированная подсказка для агента, а не автоматический определитель.
- **Карта — снимок на дату** (`last_reviewed_at`). Ревизия — ваша ответственность.
## Атрибуция
Тексты стандартов разработки 1С принадлежат правообладателям: первоисточник — ИТС фирмы
«1С» (`its.1c.ru/db/v8std`), удобный доступ — [v8std.ru](https://v8std.ru/) и его MCP-сервис.
**Этот репозиторий текстов стандартов не содержит.** В картах — только идентификаторы,
официальные заголовки как средство идентификации и собственные формулировки авторов о том,
в какой рабочей ситуации к стандарту следует обратиться. Содержание требований читается по
ссылке у правообладателя. См. [`LICENSE`](LICENSE).
Отдельная благодарность авторам [v8std.ru](https://v8std.ru/) — без их MCP-сервиса
машинная работа со стандартами была бы куда менее удобной.
## Лицензия
MIT — на код, тесты, документацию и карты соответствия этого репозитория.
Подробнее об области действия — [`LICENSE`](LICENSE).
连接信息
猜你喜欢
暂无推荐服务器