# 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
---