# CLAUDE.md

Инструкции для агента, работающего **над самим плагином** (не для тех, кто его использует).

## Что это

Плагин Claude Code для контроля качества 1С-разработки. Оркестратор `quality-gate` определяет
профиль изменения и запускает четыре контура: код, архитектура, XML метаданных, гигиена файлов.
Блокирующие хуки не дают завершить сессию, пока проверка не прогнана.

## Язык

Отвечать и писать файлы по-русски. Технические термины, код, имена файлов и идентификаторы — в
оригинале.

## Раскладка

```
.claude-plugin/plugin.json   манифест (только метаданные; version обязателен)
.claude-plugin/marketplace.json
.mcp.json                    MCP-серверы плоским объектом, без обёртки mcpServers
skills/<имя>/SKILL.md        навыки; имя в frontmatter = имя каталога
agents/<имя>.md              субагенты
commands/<имя>.md            слэш-команды
hooks/hooks.json             хуки; пути через ${CLAUDE_PLUGIN_ROOT}
tools/                       исполняемые проверки
shared/                      знание, общее для нескольких навыков
```

Компоненты **не перечисляются** в манифесте — подхватываются по соглашению об именах каталогов.

## Правила, нарушение которых ломает плагин

**Пути только через переменные.** `${CLAUDE_PLUGIN_ROOT}` внутри плагина,
`${CLAUDE_PROJECT_DIR}` для проекта пользователя. Абсолютный путь работает у автора и больше
ни у кого.

**Никаких проектных данных.** Плагин публичный: имена систем, модулей, полей внешних
контрактов, пути машин автора в артефакт не попадают. Проверяется автоматически —
`node tools/validate-package.mjs`.

**Тексты стандартов не воспроизводятся.** Публикуются только ссылки и номера; тексты
запрашиваются через MCP `v8std` во время работы. Это лицензионное ограничение, а не стиль.

**Frontmatter — только поддерживаемые поля.** `inclusion`, `fileMatchPattern` и подобные из
других сред молча не работают: навык просто не активируется, и это неотличимо от «правило не
сработало». Триггеры по типам файлов живут в хуках.

**Состояние гейта именуется по сессии.** Общий на проект маркер запирает сессию, которая
правила совсем другие файлы. Идентификатор берётся из payload хука.

**Навык живёт в бюджете, а не до предела.** Навык грузится целиком при каждом вызове, и
предел пакета (32 768 байт) — порог отказа, а не план: доросший до него файл обнаруживается
в момент, когда правку уже некуда положить. Бюджеты на каждый навык заданы в
`tests/run-tests.mjs`. Граница разреза при выносе: **исполняемое и решающее остаётся в
навыке, обосновывающее уходит в `references/`** — с однофразовой причиной в навыке и
указателем на разбор. Правило без причины не применяется, поэтому голых команд не
оставляем. Справочник, которого не называет ни навык, ни соседний справочник, не читается
никогда — это тоже проверяется тестом.

## Перед коммитом

```bash
node tests/run-tests.mjs             # тесты программных проверок (596 кейсов)
node tools/validate-package.mjs      # целостность пакета, ссылки, утечки
node tools/gen-signs-map-md.mjs      # если менялся signs-map.json
```

Контуры `code` и `arch` — инструкции для модели, автоматически их прогнать нельзя.
Для них тесты проверяют только полноту правил: что строка про конкретный антипаттерн не
исчезла. Это ловит регрессию удаления, но не качество применения — такие проверки
остаются за живой сессией.

То же гоняет CI на каждый push.

## Принципы, на которых плагин построен

Их стоит держать в голове при любой правке — они объясняют, почему код выглядит именно так.

**Пропуск проверки обязан оставлять след.** Невыполненная проверка неотличима от выполненной,
если после неё ничего не остаётся. Отсюда формат evidence и правило: недоступный инструмент
даёт запись `skipped` с причиной, а не тишину.

**Вердикт «чисто» обязан признавать непроверяемое.** Компилируемость тел модулей не проверяется
ничем, кроме платформы. Полностью зелёный отчёт без записи `not_verified` валидатор отклоняет.

**Градация вместо «всё или ничего».** Полный прогон на правке комментария — налог, из-за
которого гейт начинают обходить. Глубина считается по трём осям: объём, архетипы кода,
сложность.

**Контр-сигнал обязателен.** Ложноположительная находка дороже пропущенной: она провоцирует
переделку работающего кода и подрывает доверие ко всему инструменту. У каждого признака есть
законная форма, в которой он не дефект.

**Приближение лучше пропуска, но должно быть заявлено.** Где разбор неточен (например,
определение строковых литералов в гигиене), находка не блокирует и это сказано прямо.