git:20261009.c1a0958 to git:20261016.9c6355c

16 added, 27 removed. Audit A to A.

---

name: unica-writing

description: Понятные тексты о самом Unica — архитектурные правила, документация, комментарии к коду, страницы сайта, сообщения коммитов и тексты issues/PR. Используй при их создании, редактировании или ревью.

---

# Понятные тексты Unica

Помоги читателю понять поведение продукта, причину изменения или следующий

шаг. Сохраняй язык и формат, выбранные пользователем или принятые в конкретном

артефакте. Русский язык этой инструкции не задаёт язык всех текстов проекта.

## Общие приёмы

- Начинай со смысла для читателя: что происходит, при каком условии и к чему

это приводит. Название внутреннего механизма само по себе ничего не объясняет.

- Держи одну основную мысль в абзаце. Удаляй повторы, канцелярские обороты,

неподтверждённые оценки, риторические вопросы и декоративные противопоставления.

- Отрицания и исключения, от которых зависит смысл, сохраняй.

- Объясняй необходимый термин при первом употреблении. Например,

«ревизия — внутренний идентификатор состояния исходников». Имена файлов,

тестов, инструментов и полей протокола оставляй точными; пояснение не должно

превращаться в переименование машинного контракта.

- Добавляй короткий пример, когда без него легко неверно понять правило.

Бери ситуацию из кода, теста или задачи; вымышленный пример обозначай как

иллюстрацию. Пример и отдельные подзаголовки не обязательны для каждого текста.

- Сверяй утверждения с источником: кодом, тестом, выводом запуска или решением

владельца. Отличай текущее поведение от предложения, проверенный результат

от ожидаемого. Не расширяй гарантию при упрощении: проверка Linux не означает

проверку всех ОС, отсутствие поля не равно значению `null`.

- - Оставляй ровно столько деталей, сколько нужно для понимания и действия.

- Ограничения, предпосылки и причины сохраняй; внутренние названия добавляй,

- когда по ним читатель сможет найти нужное место в коде.

+ - В постоянной инструкции — скилле, правиле или процедуре — сохраняй деталь,

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

+ или критерии завершения. Внутреннее имя уместно, когда нужно найти код

+ или выполнить описанное действие.

+ - Из исследования переноси в инструкцию применимый вывод. Историю изменений

+ и результаты отдельных прогонов размещай в материалах работы.

+ - Отрицание уместно, когда уточняет границу описанного действия или устраняет

+ неоднозначность его формулировки.

В английских названиях возможностей компоновки данных используй DCS (Data Composition System); в русском тексте — СКД. Не переименовывай ради этого поля внешних схем SetMainSKD/setMainSKD и донорские пути: их написание задаётся совместимостью.

## Архитектурное правило

- Применяй этот раздел только при работе над правилом продукта. Формат записи

- описан в [arch/README.md](../../../arch/README.md).

- Прочитай само правило и тело названного в `check` теста. Сформулируй одну

- гарантию продукта понятным действием: что система сохраняет или предотвращает

- в заданной ситуации. Заголовок должен передавать это действие. Порядок работы

- агента, оформление PR и стиль текста остаются в инструкциях разработки.

- При редактуре сохраняй `id`, ссылки `check`, условия и исключения. Не добавляй

- новое обязательство ради пояснения или шаблона. Если формулировка обещает

- больше, чем проверено, покажи расхождение; не ослабляй принятое правило молча.

- Согласование изменения гарантии выполняется по AGENTS.md.

- Описание теста нужно, когда оно объясняет границу гарантии: например,

- обработанную ошибку записи и аварийное завершение процесса нельзя смешивать.

- Не пересказывай assertions строка за строкой и не создавай тест на слова

- в правиле. Пример уже выполненной редактуры —

- [правило отката](../../../arch/rules/workspace/retained-apply-rollback.md).

- При упоминании обязательства в другом документе ссылайся на его файл.

+ Критерии и сопровождение записи задаёт [unica-rules](../unica-rules/SKILL.md).

+ При работе над правилом используй его вместе с общими приёмами редактуры

+ выше; остальные жанры не требуют этого перехода.

## Другие тексты

Перед подготовкой правки issue применяй

[правило исходного пользовательского текста](../unica-development/SKILL.md#исходный-текст-пользовательского-issue).

Оно определяет, можно ли редактировать описание или нужен отдельный материал.

Выбирай подсказку по задаче; это не обязательные разделы готового текста.

| Текст | Что нужно читателю |

| --- | --- |

| Комментарий к коду | Неочевидная причина, ограничение или последствие изменения. Не пересказывай операции, которые и так видны в коде; не добавляй комментарий без полезного пояснения. |

| Документация и описание возможности | Что можно сделать, необходимые условия, пример использования и ожидаемый результат. Указывай ограничения там, где они влияют на применение. |

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

| Сообщение коммита | Конкретное изменение в заголовке; причина и существенное ограничение в теле, если они нужны. Соблюдай принятый формат репозитория. |

| Issue | Наблюдаемая проблема или желаемое поведение. Для дефекта — условия воспроизведения и ожидаемый результат; для предложения — задача и ожидаемый результат. В обоих случаях — раздел «Критерии приёмки» из проверяемых утверждений: чем будет доказано выполнение. |

| Комментарий в issue или PR | Ответ на конкретный вопрос или замечание, основание и оставшееся действие. Утверждение о дефекте отделяй от предположения и предпочтения. |

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

В диагностике RLM указывай имя программы, поколение индекса или путь к нему,

если это помогает найти и исправить проблему. Эти детали могут меняться

между версиями; не представляй их как стабильный API. Это разрешение не

отменяет скрытие секретов.

Перед внешним общением учитывай [CODE_OF_CONDUCT.md](../../../CODE_OF_CONDUCT.md).

Подготовка текста не даёт разрешения отправить комментарий, открыть issue/PR

или опубликовать страницу: выполняй только действия, порученные пользователем.

## Самопроверка

Перечитай результат как человек, который не видел обсуждения и реализации:

понятны ли смысл, необходимые условия и существенное ограничение? Проверь

- факты и ссылки, убери фразы, которые ничего не добавляют. Не превращай эту

+ факты и ссылки. При редактуре постоянной инструкции мысленно удали деталь

+ и назови конкретную ошибку применения, которую это допускает. Если выбор,

+ действия и критерий завершения не изменились, убери деталь. Не превращай эту

проверку в отдельный отчёт, сводный реестр или тест на наличие формулировок.

- Навык самодостаточен: внешний `/post` не нужен. Приёмы ясного письма

- адаптированы из `post` Люды Сарычевой и Никиты Архипова и уточнены на пилоте

- архитектурных правил Unica.

+ Приёмы ясного письма адаптированы из `post` Люды Сарычевой и Никиты Архипова

+ и уточнены на пилоте архитектурных правил Unica.