Требования к Frontmatter для AI Search¶

Дата: 2026-04-07 Контекст: Cascade v4 (deployed) использует CONTAINSTABLE по Tags как первый сигнал ранжирования. Качество frontmatter напрямую определяет качество поиска.

Зачем¶

Cascade docs search работает так: 1. CONTAINSTABLE(Tags, AND) — точные совпадения всех слов в тегах 2. CONTAINSTABLE(Body, AND) — точные совпадения всех слов в теле 3. FREETEXTTABLE(Tags) — fuzzy-поиск по тегам (главный сигнал, ×5.0) 4. FREETEXTTABLE(Body) — fuzzy-поиск по телу 5. PageRank — авторитетность документа

Сигнал 1 (Tags) — основной точный сигнал: вес ×1.0 (CONTAINSTABLE). Сигнал 3 (FREETEXT Tags) — самый важный: вес ×5.0 (fuzzy matching). Документ без frontmatter не участвует в нём и проигрывает документам с frontmatter даже при идеальном совпадении в Body.

Текущее покрытие¶

Секция	Всего	С frontmatter	С tags	С box	Без FM
scenarios	2419	2398 (99%)	1 (0%)	0	21
boxes	2280	2234 (98%)	1898 (83%)	2206 (97%)	46
projects	1018	299 (29%)	206 (20%)	39 (4%)	719
admin-manual	757	757 (100%)	757 (100%)	0	0
domains	390	373 (96%)	373 (96%)	0	17
platform	169	132 (78%)	132 (78%)	0	37
regulations	132	130 (98%)	0 (0%)	0	2
other	111	37 (33%)	6 (5%)	0	74
reference	104	72 (69%)	72 (69%)	0	32
clients	120	67 (56%)	67 (56%)	0	53

Приоритет дозаполнения: projects (719 без FM), other (74), clients (53), platform (37), reference (32).

Обязательные поля¶

---
section: domains          # ОБЯЗАТЕЛЬНО. Одно из: domains, boxes, projects, platform,
                          # reference, regulations, guides, scenarios, clients,
                          # admin-manual, user-guide, mobile-guide, product, industry, blog
tags: [тег1, тег2, ...]   # ОБЯЗАТЕЛЬНО. Слова которые пользователь будет искать.
                          # Русский и английский. Через пробел в индексе.
                          # Примеры: [портал, виджет, дашборд, portal, widget]
---

Рекомендуемые поля (по типу документа)¶

Домены (`domains/`)¶

---
section: domains
domain: portal             # имя домена (совпадает с папкой)
layer: backend             # backend, frontend, data-flow, admin, database, mobile,
                           # business, entities, process, analytics, etc.
related: [admin-ui, grids] # связанные домены
tags: [домен, портал, виджет, блок, data-flow, sql, api]
---

Коробки (`boxes/`)¶

---
section: boxes
box: pm                    # имя коробки: crm, dev, finance, hr, impl, it,
                           # marketing, mgmt, pm, servicedesk, platform-user
layer: entities            # entities, process, analytics, automations, integrations,
                           # cross-links, questions, navigator, overview
tags: [коробка, конфигурация, pm, проекты, agile, вехи, ресурсы]
---

Проекты (`projects/`)¶

---
section: projects
project: ai-search         # slug проекта (совпадает с папкой)
tags: [поиск, ранжирование, FTS, cascade, MSSQL]
---

Платформа (`platform/`)¶

---
section: platform
domain: meet               # или frontend, backend, devops, testing, mobile, database
layer: backend             # опционально
tags: [видеоконференции, WebRTC, meet, транскрибация]
---

Регламенты (`regulations/`)¶

---
section: regulations
level: department          # company, department, team, instruction
owner_role: Технический директор
status: active             # draft, active, archived
effective_date: 2026-03-11
tags: [регламент, разработка, code-review, стандарты]
---

Справочники (`reference/`)¶

---
section: reference
tags: [справочник, API, endpoints, enums, database]
---

Правила для tags¶

Пиши как пользователь ищет. Не технические ID, а слова: портал не PortalBlock, дп не ExtParams (но технический термин тоже можно добавить вторым).
Русский + английский. [портал, portal, виджет, widget, дашборд, dashboard].
Через пробел (не запятую). В DocsChunks.Tags хранится как строка через пробел: портал виджет дашборд.
Синонимы. [ВКС, видеоконференции, meet, teams, видеовстречи].
Домен + бизнес. [портал, виджет, блок, dashboard] — и технический и бизнес-терминологию.
Без стоп-слов. Не [для, из, или]. Минимум 2 символа.
5-15 тегов на документ. Меньше — недостаточно для поиска. Больше — шум.

Как frontmatter попадает в поиск¶

md-файл с frontmatter
  ↓ git push
  ↓ SS 509 (docs-indexer-gitlab.js)
  ↓ regex-парсер YAML → колонки DocsChunks
  ↓
DocsChunks:
  - Frontmatter (полный YAML как текст) → FTS-каталог, CONTAINSTABLE
  - Tags (из tags: []) → отдельная колонка, FTS-каталог
  - Section (из section:) → колонка, WHERE-фильтр
  - Box (из box:) → колонка, WHERE-фильтр
  - Layer (из layer:) → колонка

Cascade v4 ищет по:
  1. CONTAINSTABLE(Tags, ...) — теги из YAML
  2. FREETEXTTABLE(Tags, ...) — fuzzy по тегам
  3. CONTAINSTABLE(Body, ...) — тело документа
  4. FREETEXTTABLE(Body, ...) — fuzzy по телу
  5. PageRank — авторитет

Секция (Section) фильтруется на уровне SQL-запроса: scenarios, clients исключены.

Вывод: всё что в frontmatter — searchable. Но tags выделен в отдельную колонку с повышенным весом. Поэтому tags — самое важное поле.

Правила для CONTRIBUTING.md¶

### Frontmatter

Каждый md-файл в `docs/` ОБЯЗАН содержать YAML frontmatter:

\`\`\`yaml
---
section: <section>   # обязательно
tags: [тег1, тег2]   # обязательно, 5-15 тегов
---
\`\`\`

Без frontmatter документ не участвует в поисковом ранжировании AI Search.
Теги пишутся на языке запроса пользователя (русский + английский).

CI: pre-commit hook TODO — требуется реализация проверки наличия `section:` и `tags:`.