57 lines
4.6 KiB
Markdown
57 lines
4.6 KiB
Markdown
# 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 как единственный источник структуры.
|
|
5. Проверить чек-лист совместимости с аналитикой (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`
|