AI Style Guide — генерация RENAR-артефактов

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

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

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 §2.1 Forward]

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

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

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

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

2.1 ADAPT

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

Обязательные секции:

  • ## Краткое содержание — 3-5 параграфов для одностраничного чтения клиентом.
  • ## Term mapping — таблица «клиент → инженер».
  • ## Forward: интерпретация по разделам ТЗ — раздел на каждый § ТЗ.
  • ## Backward: обнаруженные проблемы — записи B-NNN с lifecycle.
  • ## Резюме 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 §5):

  • ## Назначение
  • ## 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 / state machine references.

2.5 TC — Test Case

Body: 30-80 строк.

Обязательные секции:

  • ## Given (Предусловия) — 2-5 строк.
  • ## When (Действие) — 1-3 строки.
  • ## Then (Pass) — бинарный, наблюдаемый, воспроизводимый критерий.
  • ## Fail criteria — список наблюдаемых признаков нарушения, включая возможные побочные эффекты (security leaks, missing audit logs).
  • ## Not in scope — out-of-scope с pointer на покрывающие TC.

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

2.6 Impact Analysis

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

Обязательные секции:

  • ## Затронутые требования — таблица с типом изменения.
  • ## Затронутые SPEC — таблица с действием.
  • ## Затронутые TC — таблица с действием.
  • ## Затронутые задачи в backlog.
  • ## Open questions — что нужно уточнить со stakeholder через 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/SPECMarketing language.
«Качественный»измеримые quality characteristics из ISO/IEC 25010Subjective.
«Быстрый»p95/p99 latency с числомVague.
«Надёжный»uptime / reliability с числомVague.
«Возможно» / «Может быть»(никогда в требованиях)Hedging.
«Скорее всего»(никогда)Same.
«Желательно»priority: should / could во frontmatterMixing channels.
«Понятный»criteria for clarity (Flesch reading ease, etc.)Subjective.
«Гладкий experience»UX criteria в SPEC-UIMarketing.
«Бесшовный»конкретный технический критерийMarketing.
«Поддерживать» (без объяснения как)конкретный SR-уровень criteriaVague.
«Интегрироваться с X» (без contract)SPEC-INT с counterpartyVague.

3.3 Use Cases vs Stories vs Requirements

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

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 §2.1 Forward]

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

5.2 Derived маркер

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

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

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

5.3 Multi-source

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

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

5.4 Что НЕ citation

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

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

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

  1. Role: «Ты архитектор требований по стандарту RENAR».
  2. Style guide reference: ссылка на этот документ.
  3. Glossary reference: ссылка на 01-glossary.md.
  4. Constraints:
    • Каждое утверждение либо с citation, либо derived с объяснением.
    • Использовать только canonical термины.
    • Структура и длина — согласно §2 этого документа.
    • Никаких запрещённых слов из §3.2.
  5. Output schema: точный YAML frontmatter format (см. 02-schemas.md).
  6. 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:

МодельTendencyMitigation
Claude OpusVerbose, склонен к hedging («может быть», «возможно»)Explicit constraint в prompt: «без hedging modal verbs».
Claude SonnetКонкретный, может пропустить edge caseAdversarial critic catches gaps.
GPT-4 / o-seriesMarketing language tendencyExplicit blacklist слов из §3.2.
Mini / HaikuHallucinated citationsCitation validator hook (см. AIR-07).
Gemini ProИногда смешивает RU/ENLang constraint в prompt + post-validation.

Style guide не запрещает использование любой модели, но требует enforcement через post-generation 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 §3.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 / adversarial / approval).

Validator hooks — substrate-нативные. На git — pre-commit; на Raven — pre-save document validator; на любом другом — equivalent gate.

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 поля — всегда canonical (английская латиница):

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

UI отображает русские переводы (см. 01-glossary.md §3.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. Cross-references

AI Style Guide RENAR 1.0-draft — renar.tech