unica-development git:20261104.e1bb9d1A

Immutable. This exact content never changes and is served at /api/v1/blob/8f8c9c0e9b974d49.

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

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

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

## Граница поручения

Поручение реализовать изменение Unica по умолчанию включает проверки,
ревью и доставку через PR в `main` или явно указанную целевую ветку.
Прочитай [порядок PR](references/pull-requests.md) в начале такой работы
и сопровождай изменение до подтверждённого слияния и проверки результата
в целевой ветке. Открытый PR, зелёный CI и постановка в очередь — этапы работы.

Явное ограничение человека — только исследование, ревью, локальная правка,
draft или запрет публикации — определяет границу поручения. Доступ к GitHub
сам по себе её не расширяет. Полный цикл изменения не включает выпуск версии
или работу с посторонними PR; выпуск задаётся отдельным поручением.
Уже согласованную доставку повторно не согласуй.

## Параллельная работа

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

Пересекающуюся изменяемую часть поручай одному исполнителю; независимые
части, чтение и ревью могут продолжаться параллельно. Для самостоятельных
PR используй отдельные ветки и рабочие копии, каждую со своим каталогом
сборки: не задавай копиям разных ревизий общий `CARGO_TARGET_DIR`. Иначе
cargo может не пересобрать path-крейт из исходников этой копии и дать
ложную ошибку компиляции или ложный зелёный результат. Внутри одного изменения
разделяй области записи; staging и commit остаются у главного агента.
Если нескольким задачам нужна общая предпосылка, сначала доведи её
самостоятельный PR до целевой ветки, затем начинай зависимые изменения
от обновлённой базы по [порядку PR](references/pull-requests.md).

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

## Результат и критерий приёмки задачи

Ставь задачу в issue, только когда в ней понятны ожидаемый результат и
критерий приёмки. Результат говорит, что изменится для пользователя или
агента. Критерий приёмки — раздел «Критерии приёмки» из проверяемых
утверждений: какой тест, сценарий приёмочного корпуса, проверка из `check`
правила, живой прогон или вывод reviewer-а докажут выполнение. Для дефекта
критерием может служить воспроизведение, которое после исправления даёт
ожидаемое поведение. Дефект MCP в рабочем сценарии принимается вместе
со сценарием приёмочного корпуса, если его маршрут выражается классом ответа
корпуса. Сценарий и манифест шагов оформляй по
[CONTRIBUTING.md](../../../CONTRIBUTING.md#приёмочные-сценарии-поверхности).

Перед тем как взять задачу в работу, убедись, что можешь назвать результат
и проверку, которая его докажет, без догадок о намерении автора. Если
результат и проверка очевидны из поручения, назови их одной фразой в плане.
Критерий, уже согласованный в issue или в этой работе, повторно не
согласуй. Если результат или критерий неясны либо требуют продуктового
выбора, до реализации задай человеку вопрос с вариантами, их ценой и
рекомендацией. Расхождение с принятым правилом разбирай по
[AGENTS.md](../../../AGENTS.md#противоречие-принятому-правилу).
Согласованный критерий зафиксируй в описании PR. Место уточнения в issue
выбирай по [правилу исходного текста](#исходный-текст-пользовательского-issue).

## Исходный текст пользовательского issue

Перед изменением issue прочитай его автора, заголовок и описание. Установи,
принадлежит ли задача владельцу поручения или внешнему пользователю.
Права записи, роль администратора и текущий аккаунт GitHub сами по себе
не доказывают принадлежность. Если она не установлена, считай issue внешним.

Исходные заголовок и описание issue внешнего пользователя не редактируй.
Не дописывай туда свои критерии, не заменяй формулировки и не приписывай
автору другой объём работы. Сохранение оригинала в `details`
или истории редактирования не разрешает его замену. Комментарии автора
также сохраняй. Поручение «обнови задачу, план или критерии» не отменяет
этот порядок.

Разбор, уточнения и критерии сопровождающего размещай в отдельном комментарии
или задаче владельца, явно отделяя их от исходного запроса. Если результат
или объём существенно меняются, оформляй новое issue владельца со ссылкой
на исходное внешнее. Issue владельца и задачи, созданные агентом по его
поручению, можно перерабатывать в пределах поручения. Этот порядок не даёт
разрешения на публикацию: создание issue и отправка комментария должны
входить в поручение человека.

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

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

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

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

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

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

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

| Работа | Что открыть |
| --- | --- |
| Предложение, изменение или отмена правила; разбор его расхождения с кодом или тестом | [unica-rules](../unica-rules/SKILL.md) |
| Выбор, написание, запуск или разбор проверки | [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) |
| Обновление встроенных инструментов, заимствованных материалов, baseline или снимка донора | [Сопровождение апстримов](references/upstream-maintenance.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` нужен для настройки процесса, не для каждой правки.

При повторяющемся пояснении или ошибке сначала проверь существующий навык
и маршрут к нему. Уточняй каноническую инструкцию, когда это помогает
выбирать верное действие; не добавляй по подсказке на каждый инцидент.
Процедуры сопровождай в навыках, принятие или смену гарантии продукта —
по unica-rules. Общую справку по командам и конфигурацию существующих
линтеров в инструкции не копируй. Подключай необходимые материалы по ходу
задачи. Наличие ссылки на файл не означает, что его содержимое уже прочитано.

## Команды на разных ОС

Команды в скиллах записаны для bash и zsh на macOS и Linux. На Windows
агент работает в PowerShell или Git Bash; готовность хоста проверяет
`scripts/dev/host-preflight.py`, установка описана в
[CONTRIBUTING.md](../../../CONTRIBUTING.md#рекомендуемое-окружение).

- `python3.12` в команде означает Python 3.12. На Windows вызывай `py -3.12`
  в любой оболочке: `python3.12` там нет, а `python` и `python3` могут
  оказаться заглушкой Microsoft Store.
- На Windows Python работает только с `PYTHONUTF8=1` в окружении. Без него
  скрипты читают файлы репозитория в кодовой странице ANSI (cp1251 при
  русской локали) и падают или искажают текст.
- Временные файлы клади в `.session-temp/` своей рабочей копии, а не в `/tmp`.
  В PowerShell `/tmp` нет. На macOS `/tmp` и `mktemp -d` ведут через симлинки
  в `/private`, и демон Unica может отвергнуть такой путь с `Not a directory`.
  Физический путь каталога показывает `pwd -P`, выполненная внутри него.
- Домашний каталог в аргументе команды пиши как `$HOME`: он раскрывается
  в bash, zsh и PowerShell. `~` PowerShell внешней программе не раскрывает,
  а `%USERPROFILE%` раскрывает только cmd.
- Каталог сборки по умолчанию — `target/` внутри рабочей копии, он уже свой.
  Если `CARGO_TARGET_DIR` задан глобально, переопредели его для копии:
  `export CARGO_TARGET_DIR="$PWD/target"` в bash и zsh,
  `$env:CARGO_TARGET_DIR = "$PWD\target"` в PowerShell.
- Не набирай в строке команду с двойными кавычками внутри одинарных,
  например запрос GraphQL или выражение jq. PowerShell 5.1 срезает внутренние
  кавычки при передаче программе. Держи запрос в файле
  (`gh api graphql -F query=@<файл>`) или в скрипте. Одинарные кавычки
  без вложенных двойных, как в `-E 'test(...)'` у nextest, работают
  во всех этих оболочках.

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

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

| Класс | Что меняется | Проверки |
| --- | --- | --- |
| Косметика | Только оформление или опечатки; смысл и обязательства сохраняются | Самопроверка 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 по ссылке выше.

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

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

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

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

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

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

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

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

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

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

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

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

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