unica-development git:20261106.0ca8308A

Immutable. This exact content never changes and is served at /api/v1/blob/023e1b2ad391c23b.

---
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
решает, что пересобрать, по времени изменения файлов, а `OUT_DIR` у path-крейта
один для всех копий. Поэтому он может не пересобрать крейт из исходников этой
копии и не перезапустить её `build.rs`: остаются устаревший список модулей,
ложная ошибка компиляции или ложный зелёный результат. Внутри одного изменения
разделяй области записи; staging и commit остаются у главного агента.
Если нескольким задачам нужна общая предпосылка, сначала доведи её
самостоятельный PR до целевой ветки, затем начинай зависимые изменения
от обновлённой базы по [порядку PR](references/pull-requests.md).

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

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

Ставь задачу в issue, только когда в ней понятны ожидаемый результат и
критерий приёмки. Результат говорит, что изменится для пользователя или
агента. Критерий приёмки — раздел «Критерии приёмки» из проверяемых
утверждений: какой тест, сценарий приёмочного корпуса, тест с пометкой
правила, живой прогон или вывод 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/` по изменяемому поведению,
границе ответственности, путям исходников и тестов; проверь затронутые
смежные области. Прочитай сами записи и тела тестов с их пометкой
(`python scripts/dev/rule-marks.py tests <ID>`).
Совпадение путей помогает найти правило, но не исчерпывает его область действия.
Отсутствие автоматической подгрузки не отменяет принятое обязательство;
отсутствие записи не разрешает менять существующую гарантию или удалять
её проверку.

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

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