agent/_process/doc_rules_v3/documentation-rules.md

Documentation Rules V3

1. Общий контракт

• Документация строится на основе системной аналитики, но на более детальном уровне.
• Заголовки отражают только суть раздела; метаданные в заголовках запрещены.
• Метаданные указываются во frontmatter и/или отдельными строками в body.
• Структура документа определяется только template соответствующего типа.
• Правила написания конкретного раздела определяются только соответствующим common-elements файлом.
• Manifest типа документа хранится во frontmatter соответствующего template.
• Генератор секции всегда пишет только тело секции, а не сам заголовок секции.
• Дублирование заголовков запрещено: нельзя повторно выводить заголовок текущей секции внутри ее тела.
• Если template уже содержит ### <Заголовок секции>, то внутри тела допустимы только подзаголовки более глубокого уровня (#### и ниже).
• Нельзя повышать уровень заголовка внутри тела секции до ## или повторять ### с тем же названием секции.

2. Источники требований

При генерации документа учитывать:

• /Users/alex/Dev_projects_v2/ai driven app process/v2/agent/_process/04. Analitycs artefacts - documentation.md
• /Users/alex/Dev_projects_v2/ai driven app process/v2/agent/_process/04. Analitycs artefacts - features.md
• правила v2 из src/app/core/agent/processes/v2/doc_rules_v2

3. Разрыв аналитика vs документация

• Аналитика: концептуальная, укрупненная.
• Документация: технически детальная.
• Технический use case в документации не копирует аналитический 1-в-1, а детализирует его.
• Функциональные требования расширяют сценарий и не дублируют шаги без новой информации.

4. Заполнение пробелов

Если атрибуты/детали отсутствуют в аналитике:

1. восстановить из формулировок аналитики;
2. уточнить по репозиторию (код, контракты, существующие документы);
3. зафиксировать в документации явно.

5. Сборка итогового промпта

1. Загрузить global-правила.
2. Загрузить template типа документа.
3. Прочитать YAML frontmatter template как manifest.
4. Загрузить общие блоки, указанные в manifest.
5. Применить body template как единственный источник структуры.
6. Проверить чек-лист совместимости с аналитикой (domain/sub_domain, роли слоев, интеграции, ошибки).

6. Специальные инварианты для api_method

• Во frontmatter обязательно должно присутствовать поле endpoint.
• Внутри ## Details секция ### Контракт должна присутствовать ровно один раз.
• Внутри тела секции ### Контракт запрещено повторять заголовки ## Контракт и ### Контракт.
• Внутри ### Технический use case запрещено повторять заголовок ### Технический use case.
• Внутри ### Функциональные требования запрещено повторять заголовок ### Функциональные требования.

7. Формат manifest типа документа

Manifest типа документа хранится во frontmatter templates/<doc_type>.template.md.

Минимальная схема:

• doc_type
• required_common_elements

Дополнительно можно указывать:

• special_rules