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

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

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

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

Предпосылки задачи сверяй после `git fetch` с `origin/main` или названной
релизной веткой, а при правках по ревью открытого PR — с его head-веткой.
Локальные ветки могут отставать, а описание задачи — относиться к другой
ревизии.

При продолжении долгой работы прочитай связанный 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С через продукт: читай только затронутые. Обзор маршрутов
в `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` и проверки
затронутых примеров, не создавай тесты на формулировки инструкций.

Перед добавлением кода отказа сравни его смысл с существующим словарём.
Используй имеющийся код, если он передаёт нужную причину и продолжение.
Новый код нужен для различимой вызывающим причины отказа или требуемого
действия. Другое место возникновения той же ошибки само по себе нового
кода не требует. `tests/ci/test_refusal_detail_ratchet.py` считает упоминания
`RefusalCode::ProviderUnavailable` в production-коде `crates/unica-coder/src`
без тестов, строк и комментариев и требует равенства с потолком. Уточнённый
отказ строй через `RefusalDetail`: `ViewError::detailed` и
`DomainResult::canonical_rejection_detailed` выводят код из уточнения и этого
упоминания не содержат. Новое упоминание роняет проверку, а сокращение
упоминаний требует опустить потолок в том же изменении.

Для проверки 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/`. Ещё действующие требования сохрани в правилах
или спецификациях, данные для проверки поведения продукта — в фикстурах.
Проверка наличия прежней прозы не является таким потребителем поведения.