Руководство по AI-стилю — генерация RENAR-артефактов¶

Назначение: style, тон, структура, длина и лексикон для AI-агентов, генерирующих RENAR-артефакты (ADAPT, BR, SR, SPEC, TC, Impact Analysis). Снимает класс рисков «разные модели → разный стиль → drift восприятия» (см. AIR-04, AIR-13 в 03-ai-risk-register.md). Дополняет reference/06 RU Style Guide для human editors.

Контекст: AI-агент в RENAR — штатный primary author артефактов (standard/00 §0.2.1); распределение ролей AI vs Архитектор — standard/05 (§5.2.1, §5.3.2, §5.6 RACI). Данный документ нормирует стиль для штатного режима, не для исключений.

Аналог в индустрии: Google Developer Documentation Style Guide, Microsoft Style Guide for technical writing, Diátaxis. Цель — единый ровный тон независимо от модели или промпт-инженера.

1. Принципы¶

1.1 Стиль = договорная точность¶

RENAR-артефакт — договорной документ между клиентом, командой и системой. Никаких метафор, никакого «красочного» языка, никаких ассоциаций. Только однозначные утверждения.

Хорошо:

Система должна принимать заявку на регистрацию через POST /auth/register.

Плохо:

Пользователи смогут легко и удобно создавать аккаунты через современный API.

1.2 Один артефакт = одна мысль¶

Каждый BR / SR / SPEC / TC покрывает одну концепцию. Если AI-агент склонен «упаковать» 3 темы в один SR — он должен декомпозировать, не упаковывать.

Сигнал упаковки: союз «и» в title, multiple actions в одном утверждении.

Плохо:

SR-05: Регистрация, авторизация и восстановление пароля

Хорошо:

SR-05: Регистрация клиента SR-06: Авторизация клиента SR-07: Восстановление пароля

1.3 Нет претензий на полноту¶

AI не должен «дорабатывать» требование от себя, если в источнике (ADAPT или ТЗ) этого нет. Каждое утверждение либо имеет citation, либо помечено derived с явным обоснованием.

Плохо:

- При регистрации проверяется уникальность email.
- При регистрации проверяется уникальность телефона.   ← в ADAPT нет, AI домыслил

Хорошо:

- При регистрации проверяется уникальность email. [ADAPT-001 §14.1 Forward]

Если AI считает, что нужна проверка телефона — он не пишет её в SR, а добавляет в Critic-output: «возможно нужна проверка уникальности телефона — нет в ADAPT, требует backward finding к Заинтересованной стороне».

1.4 Однозначность важнее красоты¶

Если выбор между точным длинным предложением и компактным неоднозначным — AI выбирает точное длинное. Длина — не enemy, ambiguity — enemy.

2. Структура и длина по типу артефакта¶

2.1 ADAPT¶

Body: 200-800 строк (зависит от объёма ТЗ).

Обязательные секции: - ## Краткое содержание — 3-5 параграфов для одностраничного чтения клиентом. - ## Term mapping — таблица «клиент → инженер». - ## Forward: интерпретация по разделам ТЗ — раздел на каждый § ТЗ. - ## Backward: обнаруженные проблемы — записи B-NNN с жизненным циклом. - ## Резюме backward findings — таблица по категориям. - ## Generated artifacts (auto после approval).

Тон: двусторонний — Forward в инженерных терминах с явной интерпретацией, Backward в клиент-friendly формулировках.

2.2 BR — Business Requirement¶

Body: 30-80 строк.

Обязательные секции: - ## Потребность — одно предложение по шаблону [Роль] должен [действие], чтобы [бизнес-цель]. - ## Критерии успеха — 3-7 измеримых пунктов. - ## Контекст — 5-15 строк.

Запрещено: - Технологии («через REST API», «Postgres», «React»). - Конкретные экраны или поля БД. - Размышления автора («мы думаем», «возможно», «было бы хорошо»).

Тон: формальный, императивный («должен», не «может»).

2.3 SR — System Requirement¶

Body: 40-150 строк.

Обязательные секции: - ## Описание — одно предложение по шаблону Система должна [поведение]. [Условие]. - ## Поведение — 5-20 пунктов с inline citations к ADAPT. - ## Ограничения — 3-10 пунктов.

Опциональные секции (когда применимо): - ## Не входит в это требование — explicit out-of-scope. - ## Связанные SR — cross-links.

Запрещено: - Названия таблиц БД, конкретных функций, классов. - Frameworks («через FastAPI», «React-компонент»). - Конкретные UI-paths («кнопка в правом углу») — это в SPEC-UI.

Тон: формальный, точный, поведенческий («система отвечает 422», не «возвращается ошибка»).

2.4 SPEC-* (9 типов)¶

Body: 80-400 строк (varies по типу).

Общие обязательные секции (см. 02-schemas.md §2): - ## Назначение - ## Scope (входит / не входит) - ## <Type-specific sections> - ## Связь с требованиями - ## Связь с другими SPEC - ## Verification - ## Open questions

Тон по типам: - SPEC-ARCH / API / DATA / INT / SEC / OPS: технико-аналитический. Допустимы конкретные технологии. - SPEC-UI: пользователь-центричный нарратив с поведенческой точностью. «Менеджер видит ленту заказов, нажимает на заказ, открывается детальный экран», не «UI должен иметь listing component». - SPEC-AI: model card style — capabilities, limits, failure modes, eval criteria. - SPEC-PROC: procedural narrative с BPMN / машина состояний references.

2.5 TC — Test Case¶

Body: 30-80 строк.

Обязательные секции: - ## Контекст — на какой пункт верифицируемого артефакта ссылается TC. - ## Предусловия (Given) — 2-5 строк. - ## Шаги (When / действие) — 1-3 строки. - ## Pass-критерий (Then / Pass) — бинарный, наблюдаемый, воспроизводимый критерий. - ## Fail-критерий — список наблюдаемых признаков нарушения, включая возможные побочные эффекты (утечки безопасности, отсутствующие журналы аудита). - ## Постусловия — ожидаемое состояние после прогона. - ## Out of scope — что намеренно не проверяется, с pointer на покрывающие TC.

Имена секций критериев (## Pass-критерий / ## Fail-критерий) — канонические machine-detectable заголовки (standard/09 §9.4), детектируются хуком обеспечения соблюдения (standard/10 §10.11.3); не переименовывать.

Тон: исполнительный, чёткий («выполняется X», «возвращается Y»).

2.6 Impact Analysis¶

Body: 50-200 строк (зависит от размера дельты).

Обязательные секции: - ## Затронутые требования — таблица с типом изменения. - ## Затронутые SPEC — таблица с действием. - ## Затронутые TC — таблица с действием. - ## Затронутые задачи в backlog. - ## Open questions — что нужно уточнить с Заинтересованной стороной через backward в delta-ADAPT.

Тон: аналитический, без оценок. Не «это плохое изменение», а «это изменение затрагивает X требований и Y задач».

3. Лексикон¶

3.1 Use (canonical)¶

«Система должна …» (модальность).
«должен» / «не должен» (RFC 2119 vocabulary — MUST / MUST NOT).
«должна» / «не должна» (для системы).
«возвращает» (HTTP/API behavior).
«предусловия» / «постусловия» (формальные термины тестирования).
«требование» / «утверждение» / «assertion».
«критерий приёмки» (acceptance criterion).
«backward finding» / «forward интерпретация» (RENAR canonical из ADAPT).

3.2 Запрещено¶

Слово/фраза	Заменить на	Почему
«Хочется чтобы»	«Система должна»	Модальность должна быть строгой.
«Удобно»	конкретный измеримый критерий	Subjective.
«Современный»	конкретные tech requirements в SR/SPEC	Marketing language.
«Качественный»	измеримые quality characteristics из ISO/IEC 25010	Subjective.
«Быстрый»	p95/p99 latency с числом	Vague.
«Надёжный»	uptime / reliability с числом	Vague.
«Возможно» / «Может быть»	(никогда в требованиях)	Hedging.
«Скорее всего»	(никогда)	Same.
«Желательно»	`priority: should` / `could` во frontmatter	Mixing channels.
«Понятный»	criteria for clarity (Flesch reading ease, etc.)	Subjective.
«Гладкий experience»	UX criteria в SPEC-UI	Marketing.
«Бесшовный»	конкретный технический критерий	Marketing.
«Поддерживать» (без объяснения как)	конкретный SR-уровень criteria	Vague.
«Интегрироваться с X» (без contract)	SPEC-INT с counterparty	Vague.

3.3 Use Cases vs Stories vs Requirements¶

RENAR использует только каноническую терминологию из 01-glossary.md. AI-агент не имеет права называть требование «User Story», «Use Case», «Scenario», «Capability» — это запрещённые синонимы. Полный список запрещённых терминов и подстановок — в 01-glossary.md §5.

4. Шаблоны утверждений¶

4.1 BR-утверждение¶

Шаблон: [Роль] должен [действие], чтобы [бизнес-цель].

Пример:

Пользователь должен автоматически получать и хранить уведомления выбранных приложений в фоновом режиме, чтобы не пропустить важные сообщения.

4.2 SR-утверждение¶

Шаблон: <actor> <action> <condition>. <consequence>.

Пример:

Система при первом запуске проверяет наличие разрешения NotificationListenerService. Если разрешение не выдано — отображается экран онбординга с кнопкой «Выдать доступ».

4.3 TC Pass-критерий¶

Шаблон: <actor> <action> <input>. <observable> <measurement>.

Пример:

POST /auth/login с body {"email":"x@y.z", "password":"correct"}. Response status = 200, body содержит JWT с exp = now + 24h ± 1m.

4.4 TC Fail-критерий¶

Список наблюдаемых признаков нарушения, включая возможные побочные эффекты:

- Response status ≠ 200 (ошибка авторизации).
- В 401-ответе указано конкретное поле, которое неверно (утечка информации).
- В системный лог записывается plaintext password (security violation).
- Email с уведомлением о входе НЕ отправляется при успешной авторизации (missing side effect).

Не допускается: «Pass не выполняется». Это не Fail-критерий, это negation.

5. Citation conventions¶

5.1 Inline citation¶

Каждое утверждение в BR/SR/SPEC имеет inline-citation в квадратных скобках:

При первом запуске отображается экран онбординга. [ADAPT-001 §14.1 Forward]

Формат: [<id> <section>] или [<id> <section> line <N>] для точной строки.

5.2 Derived маркер¶

Если утверждение не цитата из ADAPT, а логически выведено:

Кнопка Назад блокируется на экране онбординга. [ADAPT-001 §14.1 Forward, derived: ADAPT требует «нельзя пропустить онбординг» → блокировка системного back]

Объяснение derived обязательно.

5.3 Multi-source¶

Если утверждение поддерживается несколькими источниками:

Пароль хранится в зашифрованном виде. [ADAPT-001 §4 НФТ-002, ISO 27001 A.10.1.1]

5.4 Что НЕ citation¶

Ссылка на сам код («см. auth/login.py») — не источник требования.
Ссылка на тикет в багтрекере — не источник требования (см. 01-glossary.md §1 Цепочка авторитетности).
Ссылка на чат / устный разговор без записи в ADAPT backward → asked-to-client → answered.

6. System prompt для AI-генератора¶

Каждый AI-агент, генерирующий RENAR-артефакт, получает system prompt из:

Role: «Ты архитектор требований по стандарту RENAR».
Style guide reference: ссылка на этот документ.
Glossary reference: ссылка на 01-glossary.md.
Constraints:
Каждое утверждение либо с citation, либо derived с объяснением.
Использовать только канонические термины.
Структура и длина — согласно §2 этого документа.
Никаких запрещённых слов из §4.2.
Output schema: точный YAML frontmatter format (см. 02-schemas.md).
Examples: 2-3 примера good/bad для каждого типа артефакта.

Prompt-templates хранятся в prompts/ директории организации с версионированием: - prompts/adapt-from-tz.md@v2.1 - prompts/decompose-adapt.md@v2.1 - prompts/generate-tc-pos-neg.md@v1.0 - prompts/critic-review-sr.md@v1.2

ai-provenance.prompt-template во frontmatter артефакта содержит точную версию.

7. Стиль для разных моделей¶

Разные LLM имеют разные tendencies. Style guide учитывает это через prompt constraints:

Модель	Tendency	Mitigation
Claude Opus	Verbose, склонен к hedging («может быть», «возможно»)	Explicit constraint в prompt: «без hedging modal verbs».
Claude Sonnet	Конкретный, может пропустить edge case	Состязательный критик catches gaps.
GPT-4 / o-series	Marketing language tendency	Explicit blacklist слов из §4.2.
Mini / Haiku	Hallucinated citations	Citation validator hook (см. AIR-07).
Gemini Pro	Иногда смешивает RU/EN	Lang constraint в prompt + post-validation.

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

8. Validation pipeline¶

После генерации RENAR-артефакта запускается автоматическая валидация:

AI generates artifact
    ↓
Style validator (отдельный AI с другим prompt или rule-based)
    ├── citation check (each assertion has [...] или derived marker)
    ├── lexicon check (no forbidden words from §4.2)
    ├── structure check (required sections present)
    ├── length check (within bounds from §2)
    ├── canonical terms check (no forbidden synonyms)
    ├── modal verb check (нет hedging)
    ↓
On fail: regenerate с refined prompt или human review.
On pass: enter draft → ready transition (далее QG-1 / состязательный обзор / утверждение).

Валидаторные хуки — нативные для носителя. На git — pre-commit; на document store — pre-save document validator; на любом другом — эквивалентный гейт.

9. Stylistic decisions для RU/EN¶

9.1 Body language¶

Body артефакта пишется на языке проекта:

Российский клиент → RU.
Международный → EN.
Двуязычный → primary lang в lang: поле frontmatter; second lang — отдельный artifact с replaces / replaced-by links или translations подпапка.

9.2 frontmatter всегда канонический¶

Frontmatter поля — всегда канонические (английская латиница):

type: BR (не тип: БТ).
status: approved (не статус: утверждено).
priority: must (не приоритет: обязательно).

UI отображает русские переводы (см. 01-glossary.md §4.5). Frontmatter — машинный, не для UI.

9.3 Mixed-lang запрещён¶

В пределах одного утверждения mixing RU+EN недопустим:

Плохо:

Система должна возвращать JWT token после successful login.

Хорошо (RU):

Система должна возвращать JWT-токен после успешной аутентификации.

Хорошо (EN):

The system must return a JWT token after successful authentication.

Технические термины (JWT, OAuth, gRPC, RBAC) — допустимы в любом языке без перевода.

10. Перекрёстные ссылки¶

Закрытый список канонических терминов и запрещённых синонимов — 01-glossary.md.
Формальные frontmatter schemas — 02-schemas.md.
AI-риски и mitigations — 03-ai-risk-register.md.
Knowledge graph schema (используется validator для cross-reference checks) — 05-knowledge-graph-schema.md.

AI Style Guide RENAR 1.0-draft — renar.tech