61 lines
2.2 KiB
Markdown
61 lines
2.2 KiB
Markdown
# Frontmatter Rules
|
|
|
|
## Назначение
|
|
|
|
Этот файл фиксирует правила YAML frontmatter для документов в `docs/documentation/`.
|
|
|
|
Frontmatter обязателен для каждого markdown-документа и нужен для:
|
|
- идентификации документа;
|
|
- определения типа документа;
|
|
- фиксации связей с кодом и другими документами;
|
|
- выделения сущностей, тегов и домена;
|
|
- поддержки индексирования в RAG.
|
|
|
|
Общие правила построения документации описаны в:
|
|
- `.analysis/rules/documentation-rules.md`
|
|
|
|
Шаблоны markdown body описаны в:
|
|
- `.analysis/rules/templates/*.md`
|
|
|
|
---
|
|
|
|
## Общие правила
|
|
|
|
1. Frontmatter размещается в начале файла.
|
|
2. Формат — YAML между двумя строками `---`.
|
|
3. Все документы в `docs/documentation/` должны содержать frontmatter.
|
|
4. Поля должны быть стабильными и заполняться единообразно.
|
|
5. Не использовать произвольные поля без необходимости.
|
|
6. Если значение неизвестно и его нельзя уверенно вывести из evidence, поле лучше не заполнять, кроме обязательных полей.
|
|
7. Списковые поля должны оформляться как YAML-массивы.
|
|
8. Идентификаторы и ссылки должны быть стабильными и пригодными для машинной обработки.
|
|
|
|
---
|
|
|
|
## Базовый frontmatter
|
|
|
|
Каждый документ должен начинаться с frontmatter вида:
|
|
|
|
```yaml
|
|
---
|
|
id: api-orders-create
|
|
title: Метод создания заказа
|
|
doc_type: api_method
|
|
domain: orders
|
|
status: draft
|
|
owner: system-analyst
|
|
source_of_truth: code
|
|
related_docs:
|
|
- ui-order-create-page
|
|
- logic-order-validation
|
|
related_code:
|
|
- src/orders/api/create_order.py
|
|
entities:
|
|
- Order
|
|
- CreateOrder
|
|
tags:
|
|
- api
|
|
- orders
|
|
- create
|
|
---
|