unica-development git:20260922.2184cd2A

Immutable. This exact content is served forever at /api/v1/blob/bae41000c32930b2.

---
name: unica-development
description: Разработка самого Unica — исследование, изменение и ревью кода, правил и документации репозитория. Используй для работы над Unica; задачи с конфигурациями 1С через готовый плагин обслуживают его продуктовые скиллы.
---

# Разработка Unica

Определи результат задачи и затронутое поведение. Проверь состояние Git и
работай в границах поручения. Устраняй причину; противоречия между задачей,
кодом, тестом и документацией показывай явно. Уже принятое в этой работе
решение человека учитывай без повторного согласования.

## Нужный контекст

При продолжении долгой работы прочитай связанный issue и нужные PR. Локальные
материалы той же задачи могут помочь восстановить ход работы; сверяй их
с текущим кодом и решениями. Историю ищи через Git по конкретному вопросу.

Когда выбираешь исходники для изменения, используй
[карту кода](references/code-map.md). Читай нужные области карты вместе:
публичный инструмент может одновременно менять XML и состояние кеша.
До выбора решения найди применимые `arch/rules/` по предмету, путям исходников
и тестов; прочитай сами записи и тела тестов из `check`. Отсутствие записи
не разрешает менять существующую гарантию или удалять её проверку.

Дочитывай материалы, когда возникает соответствующая работа:

| Работа | Что открыть |
| --- | --- |
| Выбор, написание, запуск или разбор проверки | [unica-testing](../unica-testing/SKILL.md) |
| Текст для человека, включая правило, комментарий, сайт, commit или PR | [unica-writing](../unica-writing/SKILL.md) |
| Выпуск версии или разбор его состояния | [unica-release](../unica-release/SKILL.md) |
| Подготовка PR, правки по ревью, push или слияние | [Порядок PR](references/pull-requests.md) |
| Настройка окружения, Inspector, LSP или отчёт Allure | Нужный раздел [CONTRIBUTING.md](../../../CONTRIBUTING.md) |
| Подготовка внешнего общения | [CODE_OF_CONDUCT.md](../../../CODE_OF_CONDUCT.md) |

Общие `build-mcp-server`, `build-mcp-app` и `build-mcpb` выбирай по задаче
контракта, UI или упаковки. Обычная правка Unica не требует всего комплекта;
установка описана в CONTRIBUTING. Навыки `plugins/unica/skills/` описывают
работу с 1С через продукт: читай только затронутые. Каталог tools и
описаний в `AI_DEV.md` нужен для настройки процесса, не для каждой правки.

## Класс задачи и независимая проверка

Перед правкой назови класс и достаточные проверки. Оценивай последствия,
а не расширение файла или число строк. Изменение теста классифицируй по тому,
что он начинает или перестаёт проверять. При расширении области пересмотри
класс; требования нескольких подходящих классов объединяются.

| Класс | Что меняется | Проверки |
| --- | --- | --- |
| Косметика | Только оформление или опечатки; смысл и обязательства сохраняются | Самопроверка diff |
| Локальное поведение | Реализация в существующих контрактах и ответственности | Проверки поведения и независимый reviewer |
| Правила и требования | Обязанности агента, процесс или критерии приёмки, в том числе в Markdown | Скептик до введения правил и независимый reviewer результата |
| Архитектура и публичные контракты | Совместимость, публичная поверхность, состояние, границы слоёв, упаковка или ответственность нескольких потребителей | Скептик до реализации, проверки поведения, reviewer, сверка правил и спецификаций |

Скептик проверяет замысел. Передай отдельному субагенту исходную задачу,
вариант решения, ограничения и свидетельства. Он ищет подмену задачи,
неподтверждённые допущения, второго владельца ответственности, лишние
преобразования, противоречия и пропущенные сценарии отказа или потребителей.
Для возражения нужны основание, последствия и способ проверки. Скептик
не редактирует проверяемые файлы и не выбирает архитектуру за человека.
Отсутствие подтверждённых замечаний допустимо.

Reviewer проверяет результат после реализации и необходимых проверок.
Передай текущий diff, исходную задачу, применимые контракты и результаты
проверок агенту, который не писал реализацию. Он сверяет итог с задачей,
разбирает замечания скептика и проверяет обещанные удаления. Зелёный CI
не заменяет эту сверку. После существенной правки повтори затронутую проверку;
после смены замысла вернись к скептику.

Скептик и reviewer — отдельные проходы. Explorer и tester нужны, когда есть
самостоятельная подзадача; отдельный агент на каждую команду не нужен.
Главный агент сводит выводы, проверяет итог, выполняет staging и commit.
Если субагенты недоступны, выполни те же проходы сам и явно назови отсутствие
независимого ревью.

Источник идеи классификации и независимой проверки —
[AGENTS.md v8-runner-rust](https://github.com/IngvarConsulting/v8-runner-rust/blob/ee3a6ee195524fec6f18d8b5838b90e7e5872e5d/AGENTS.md).

## Как разбирать замечания

Отделяй тип замечания от важности:

| Тип | Основание |
| --- | --- |
| Дефект | Нарушенный контракт и воспроизведение либо конкретный контрпример |
| Риск | Возможный отказ, последствия и ещё не проверенные предпосылки |
| Вопрос | Недостающий факт или решение и зависящее от него действие |
| Предпочтение | Альтернатива без доказанного нарушения |

Критическая важность — потеря данных, нарушение безопасности или невозможность
восстановления; высокая — нарушение основного сценария или обязательного
контракта; обычная — ограниченное влияние. Важность риска условна и не
доказывает дефект.

Для существенного замечания зафиксируй проверяемый исход в обсуждении задачи:
исправлено с проверкой; опровергнуто свидетельством; риск принят человеком
со ссылкой на решение; вынесено за границу задачи с обоснованием происхождения
и местом дальнейшего учёта. Для предпочтения объясни выбор. Не заводи для
этого отдельный реестр или отчёт в Git.

Дефект в области задачи блокирует завершение. Для критического или высокого
риска проверь предпосылки до зависимых изменений; неснятый риск принимает
человек. Вопрос задерживает только зависимое действие. Спор, разрешимый кодом
или тестом, разбери сам. Противоречие принятому правилу разрешается по
[AGENTS.md](../../../AGENTS.md#противоречие-принятому-правилу).

Если устраняешь дублирование или повторяющийся дефект, назови причину,
единственного владельца ответственности и проверку возвращения проблемы,
включая появление под другим именем. Выбор проверки и воспроизведение до
исправления описаны в unica-testing. Происхождение дефекта из ревью определяет,
в каком PR его исправлять; применяй порядок PR по ссылке выше.

## Когда менять архитектурное правило

Правило фиксирует устойчивую гарантию продукта: публичный контракт, инвариант,
разделение данных, границу ответственности или место обязательной проверки.
Проверка пригодности записи: какое наблюдаемое нарушение продукта она запрещает
и какой содержательный тест обнаружит его? Одна запись — одно обязательство.

Папку в `arch/rules/` выбирай по области продукта, которую защищает гарантия,
а не по префиксу `id`, имени теста или общему слову вроде «кеш». Для гарантии
на стыке областей выбирай место по её основному предмету; из связанных правил
ссылайся на неё без копирования. Подпапка нужна, когда внутри области выделяется
отдельная тема с несколькими правилами. При переносе сохраняй `id` и `check`,
обновляй ссылки. Деление на папки помогает найти записи, но не ограничивает
поиск применимых гарантий одной областью.

Новое правило нужно при согласовании новой гарантии; изменение правила — когда
меняются её условия, граница или допустимый результат. Исправление реализации
в рамках гарантии, локальный рефакторинг и правка процесса сами по себе записи
не требуют. Архитектура не описывает порядок работы агента.

До введения или изменения обязательства покажи человеку формулировку,
последствия и проверку. При конфликте или более простом решении через замену
правила применяй порядок AGENTS. Согласование уже сделанное в задаче действует.
После решения обнови правило и содержательный тест одним изменением.

Если человек явно согласовал отложенную реализацию, запиши целевое правило
с `gap` — ссылкой на issue с текущим разрывом и критериями приёмки. В `check`
оставь только тесты, подтверждающие новую гарантию; если их нет — `[]`.
Проверки прежнего, противоположного поведения перечисли в issue как
свидетельства разрыва. После реализации заполни `check` и убери `gap`, когда
содержательные проверки подтвердят выполнение всего обязательства. Одного
закрытия issue недостаточно.

Формат `id`/`check` задан в [arch/README.md](../../../arch/README.md);
понятный текст готовь по unica-writing, качество теста — по unica-testing.
ADR, индекс и цепочка преемников для этого не нужны. В других документах
ссылайся на правило, не копируй его нормативную формулировку.

## Изменение продукта

Сохраняй действующие ограничения до согласованной смены контракта:
один публичный MCP-сервер `unica`, инструменты `unica.*`, один каталог плагина
для Codex и Claude. Оба манифеста имеют одну версию, `.mcp.json` не зависит
от хоста. Новые необязательные ключи проверяй на самом старом поддерживаемом
клиенте: неизвестный ключ может сорвать загрузку.

Продуктовые скиллы направляют в нативные `unica.*`; не возвращай прямой запуск
упакованных скриптов там, где есть инструмент, кроме описанных утилитарных
исключений. Изменение публичной поверхности, маршрутизации, упаковки или слоёв
требует проверок затронутых потребителей. Меняя состав инструментов,
обновляй `docs/tool-surface.md` его генератором.

При изменении продуктовых скиллов сохраняй предпросмотр перед разрушительными,
инкрементальными, частичными и относящимися к внешнему набору исходников
операциями. Используй актуальную схему вызова и её связь preview/apply.
Примеры должны исполняться над детерминированной фикстурой или управляемым
локальным поставщиком: чтение без записи, мутация через preview. Разбор JSON
и проверка грамматики адреса сами по себе не доказывают успешный вызов.
Поставляемая справка должна быть достижима из нужного скилла напрямую или
через ссылки в справке; новое содержимое не добавляй в список недостижимого
долга теста. Применяй `tests/ci/test_reference_reachability.py` и проверки
затронутых примеров, не создавай тесты на формулировки инструкций.

Перед добавлением кода отказа сравни его смысл с существующим словарём.
Используй имеющийся код, если он передаёт нужную причину и продолжение.
Новый код нужен для различимой вызывающим причины отказа или требуемого
действия. Другое место возникновения той же ошибки само по себе нового
кода не требует.

Для проверки MCP используй бинарь текущего checkout с нужным cwd и отдельным
состоянием демона. Читай схему нужного инструмента и результат сценария;
`tools/list` нужен при проверке состава поверхности и выбранного профиля.
Успех установленного плагина не доказывает работу этой сборки. Внутренние
движки продукта не подключай как дополнительные публичные MCP-серверы агента.

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

При обновлении внешнего анализатора BSL согласуй его исходный коммит
с `parser` и `syntax` в Cargo. Проверь лицензии и NOTICE выбранной ревизии,
происхождение и контрольные суммы опубликованных артефактов. Совместимость
проверяй вызовом через Unica из собранного пакета; вывод `--help` отдельного
движка не подтверждает работу адаптера. Новые возможности зависимости
сами по себе не становятся публичным контрактом Unica.

При изменении платформенного стража не добавляй исключения для отдельных
файлов: разрешённые области определяются структурой платформенных каталогов.
Проверяй распознавание запрещённого кода на примерах и текущем репозитории;
зелёная проверка репозитория с новым исключением сама по себе не доказывает
сохранение границы.

Версии встроенных инструментов задаёт `plugins/unica/third-party/tools.lock.json`.
Записи происхождения ссылаются на него через `toolLockRef`, не создавая
второй источник версии или commit. При смене сопровождаемого движка проверяй
происхождение immutable-релиза, защиту основной ветки, неизменность тега
и релиза, нативный аудит и build-attestation в репозитории этого движка.
Проверка допустимого URL загрузки в Unica не доказывает эти условия.

## Материалы работы

Планы сессии, черновики решений и журналы выполнения
храните в контексте агента. Если нужен файл, используйте игнорируемый каталог
`.session-temp/`, например `.session-temp/plans/`. Сюда же относятся служебные
таблицы соответствий старых и новых записей, списки переноса и отчёты разбора
документов. Они не коммитятся независимо от формата и названия. Это
переопределяет места сохранения в скиллах `brainstorming` и `writing-plans`.
Не используйте `git add -f` для игнорируемых путей.

Долгую работу между сессиями ведите через тематический или зонтичный issue:
цель, согласованные решения, оставшаяся работа и ссылки на PR. Поддерживайте
актуальное состояние; последовательность локальных шагов остаётся в сессии.
Согласованную гарантию продукта отражайте в действующем правиле или
спецификации: закрытый issue не заменяет её описание.

В Git сохраняйте материалы, нужные продукту и его поддержке после завершения
задачи: код, содержательные тесты, фикстуры, правила продукта, спецификации,
документацию и действующие инструкции разработки. Таблица преобразования
данных, которую использует продукт или проверка его поведения, имеет такое
назначение. Таблица переноса старых документов остаётся служебной;
переименование её в фикстуру или добавление теста на её наличие этого не меняет.

Завершённые планы и заменённые документы не переносите в архивные каталоги.
Прежние закоммиченные версии доступны через Git; ещё не сохранённые важные
решения зафиксируйте в issue/PR или действующем документе. Формат правил
продукта описан в `arch/README.md`.

При разборе старых решений, архитектурных записей и планов сначала оцени
их актуальность: существует ли исходная проблема, не заменено ли решение
более новым, есть ли полезная гарантия помимо деталей реализации.
Сверяй с действующими правилами, решениями человека, кодом и тестами.
Дата или статус принятия старой записи сами по себе не требуют возвращать
её ограничения. Не меняй современный продукт ради соответствия архиву.
Неясное противоречие покажи человеку с рекомендацией; код сам по себе
не отменяет действующее согласованное правило.

Актуальную гарантию перенеси в правило, порядок работы — в подходящий скилл,
инструкцию пользователю — в профильную документацию. Используй существующее
место, если оно уже описывает нужное. Устаревшее и дубли удаляй без замены.
Разобранный документ удаляй; не дописывай его как хранилище остатков.
Вопросы разбора держи в сессии или `.session-temp/`, долгую работу — в issue.
Отсутствие теста у старого обещания не повод автоматически начинать его
реализацию: сначала установи, нужно ли сохранять само обещание.

Перед удалением старого документа проверь ссылки и потребителей, включая
`rg <path> tests/ scripts/`. Ещё действующие требования сохрани в правилах
или спецификациях, данные для проверки поведения продукта — в фикстурах.
Проверка наличия прежней прозы не является таким потребителем поведения.