git:20261016.9c6355c to git:20261105.f636757

3 added, 0 removed. Audit A to A.

---

name: unica-writing

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

---

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

+ - Код, комментарии, документация, скилы и описания PR описывают действующее

+ правило и поведение. Не пиши, кто и когда это решил («решение владельца»,

+ даты, «по поручению»): история изменения живёт в git и PR.

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

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

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

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

Критерии и сопровождение записи задаёт [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` Люды Сарычевой и Никиты Архипова

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