unica-writing git:20261016.9c6355cA

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

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

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

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

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

- Начинай со смысла для читателя: что происходит, при каком условии и к чему
  это приводит. Название внутреннего механизма само по себе ничего не объясняет.
- Держи одну основную мысль в абзаце. Удаляй повторы, канцелярские обороты,
  неподтверждённые оценки, риторические вопросы и декоративные противопоставления.
- Объясняй необходимый термин при первом употреблении. Например,
  «ревизия — внутренний идентификатор состояния исходников». Имена файлов,
  тестов, инструментов и полей протокола оставляй точными; пояснение не должно
  превращаться в переименование машинного контракта.
- Добавляй короткий пример, когда без него легко неверно понять правило.
  Бери ситуацию из кода, теста или задачи; вымышленный пример обозначай как
  иллюстрацию. Пример и отдельные подзаголовки не обязательны для каждого текста.
- Сверяй утверждения с источником: кодом, тестом, выводом запуска или решением
  владельца. Отличай текущее поведение от предложения, проверенный результат
  от ожидаемого. Не расширяй гарантию при упрощении: проверка Linux не означает
  проверку всех ОС, отсутствие поля не равно значению `null`.
- В постоянной инструкции — скилле, правиле или процедуре — сохраняй деталь,
  если без неё читатель может ошибиться в выборе действия, условиях применения
  или критерии завершения. Внутреннее имя уместно, когда нужно найти код
  или выполнить описанное действие.
- Из исследования переноси в инструкцию применимый вывод. Историю изменений
  и результаты отдельных прогонов размещай в материалах работы.
- Отрицание уместно, когда уточняет границу описанного действия или устраняет
  неоднозначность его формулировки.

В английских названиях возможностей компоновки данных используй 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.