---
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).
При упоминании обязательства в другом документе ссылайся на его файл.

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

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

| Текст | Что нужно читателю |
| --- | --- |
| Комментарий к коду | Неочевидная причина, ограничение или последствие изменения. Не пересказывай операции, которые и так видны в коде; не добавляй комментарий без полезного пояснения. |
| Документация и описание возможности | Что можно сделать, необходимые условия, пример использования и ожидаемый результат. Указывай ограничения там, где они влияют на применение. |
| Страница сайта | Конкретная задача пользователя и подтверждённая польза продукта. Технические детали нужны, если помогают выбрать или использовать продукт. Не придумывай возможности, показатели и обещания ради убедительности. |
| Сообщение коммита | Конкретное изменение в заголовке; причина и существенное ограничение в теле, если они нужны. Соблюдай принятый формат репозитория. |
| Issue | Наблюдаемая проблема или желаемое поведение. Для дефекта — условия воспроизведения и ожидаемый результат; для предложения — задача и критерий успеха. |
| Комментарий в issue или PR | Ответ на конкретный вопрос или замечание, основание и оставшееся действие. Утверждение о дефекте отделяй от предположения и предпочтения. |
| Описание PR | Проблема, итоговое поведение, выполненные проверки и существенные ограничения. Описывай конечное изменение, а не историю переписки. Для простой правки достаточно одного-двух предложений и результата проверки; учитывай шаблон репозитория. |

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

Перед внешним общением учитывай [CODE_OF_CONDUCT.md](../../../CODE_OF_CONDUCT.md).
Подготовка текста не даёт разрешения отправить комментарий, открыть issue/PR
или опубликовать страницу: выполняй только действия, порученные пользователем.

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

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

Навык самодостаточен: внешний `/post` не нужен. Приёмы ясного письма
адаптированы из `post` Люды Сарычевой и Никиты Архипова и уточнены на пилоте
архитектурных правил Unica.