Формат документа платформы

---
type:    standard          # тип документа (см. §2.3)
title:   "Название"        # человекочитаемый заголовок
status:  active            # текущий статус (см. §2.4)
date:    YYYY-MM-DD        # дата создания или последнего изменения
---

layer:   arch              # слой платформы: arch|project|domain|infra|system|service
object:  document          # что описывает файл
aspect:  format            # одна из 10 категорий

version:         1.0.0     # SemVer — для стандартов и концепций
knowledge_level: У1        # У0|У1|У2|У3|У4
form:            text      # сущность документа: text | table | schema | code
owner:           architect # кто отвечает

parent:      ../MASTER.md      # родительский документ (один)
deps:                          # зависимости (список)
  - path/to/doc-a.md
  - path/to/doc-b.md

locked:      true              # true = только @keeper.agent может изменить
lock_reason: "У0 LOCKED — фундамент платформы"

id:          ADR-001           # для decisions и tickets
priority:    HIGH              # для tickets: LOW|MEDIUM|HIGH|CRITICAL
derived_from: path/to.md       # от какого документа дериватив
part_of:     path/to.md        # частью чего является
phase:       3                 # фаза Проектора (0–15)
tags:        [api, security]
audience:    [architect, coder]

concept      — видение, как понимаем предмет
standard     — правило, как должно быть сделано
decision     — ADR, почему решили именно так
pattern      — рецепт, типовое решение задачи
template     — заготовка для заполнения
research     — активное изучение внешних систем
analysis     — осмысление: выводы, закономерности
practice     — накопленный опыт, статистика
plan         — что и когда делать
instruction  — как делать шаг за шагом
ticket       — задача / баг / технический долг

draft        — черновик, не действует
active       — действует, является истиной
deprecated   — устарело, есть замена (поле replaced_by: обязательно)
archived     — убран в архив, не используется

suspended    — заморожено временно (опционально)
cancelled    — отменено, не будет завершено (опционально)

text         — нарратив, объяснение, рассуждение
table        — справочник, список с атрибутами
schema       — диаграмма, структура, граф
code         — готовый код, конфиг, шаблон

---
frontmatter
---

# Заголовок

Краткое описание (1–3 предложения).

---

## 1. ПЕРВЫЙ РАЗДЕЛ

...

## СВЯЗАННЫЕ ДОКУМЕНТЫ

- [Файл](./path.md) — что описывает

## ЗАЧЕМ          — проблема / цель
## ПРАВИЛА        — жёсткие требования
## ПРИМЕРЫ        — как применять
## ИСКЛЮЧЕНИЯ     — когда можно нарушить

## Контекст       — какая проблема, почему возникла
## Решение        — что решили делать
## Альтернативы   — что рассматривали, почему отказались
## Последствия    — что изменится, плюсы / минусы

## Цель           — чего хотим достичь
## Scope          — что входит, что нет
## Фазы           — последовательность шагов
## Риски          — что может пойти не так

## Описание           — что не так / что нужно
## Критерии готовности — когда считать выполненным
## Откат              — как вернуть назад

## ОПРЕДЕЛЕНИЕ    — что это такое
## ЗАЧЕМ          — почему существует
## КАК УСТРОЕНО   — структура / принципы
## ПРИМЕРЫ        — конкретные случаи

ОПТИМАЛЬНО       — до 500 строк (🟢)
РЕКОМЕНДУЕТСЯ ДРОБИТЬ — 500–800 строк (🟡)
ОБЯЗАТЕЛЬНО ДРОБИТЬ  — более 800 строк (🔴)

GFM (GitHub Flavored Markdown) — база
  + Pandoc extensions          — frontmatter, footnotes, definition lists, fenced divs
  + Custom transclusion        — компиляция документов

✅ - пункт
❌ * пункт
❌ + пункт

✅ ---
❌ ***
❌ ___

✅ [Стандарт](./format-file-types.md)
✅ [Секция](#название-раздела)
✅ [Родитель](../MASTER.md)
❌ [Стандарт](/opt/claude-workspace/standards/file.md)

✅ ```python
✅ ```bash
✅ ```yaml
✅ ```text   ← для псевдокода
❌ ``` (без языка)

✅ H1 → H2 → H3
❌ H1 → H3 (пропуск уровня)
❌ Два H1 в одном документе

::: warning
**Внимание:** критически важное предупреждение.
:::

::: note
Примечание для читателя.
:::

::: example
Пример применения.
:::

MASTER.md                    ← обзор (до 300 строк)
  └── DETAIL_1.md            ← детали раздела
        └── SUBDETAIL_1.1.md ← реализация

---
parent: ../MASTER.md
---

## Детали структуры

[→ Читать отдельно](./details/STRUCTURE.md)

<!-- INCLUDE: ./details/STRUCTURE.md -->

python3 tools/md-compile.py INPUT.md OUTPUT.md

draft → active → deprecated → archived
                ↘ suspended (временно)
                ↘ cancelled (отменено)

export WORKSPACE=/opt/claude-workspace    # КОД (git)
export DATASPACE=/mnt/beget-s3            # ДАННЫЕ (S3)
export MEDIASPACE=$DATASPACE/media        # МЕДИА (S3)

.jpg → ТОЛЬКО $MEDIASPACE (NO EXCEPTIONS)
.png → $WORKSPACE если < 50KB, иначе $MEDIASPACE
.svg → ТОЛЬКО $WORKSPACE (векторная графика)

CODE:   .py .js .ts .tsx .jsx .php .go .c .cpp .h .sh .bat .ps1
DOCS:   .md .ai.md .txt .rst
CONFIG: .yaml .yml .json .toml .ini .conf .xml .env.example
WEB:    .html .css .less .scss .svg .woff2 .ttf
TPL:    .twig .tpl .j2
SQL:    .sql
IMAGES: .svg (любой), .png (<50KB), .ico (<20KB)
MISC:   .gitignore .gitkeep .editorconfig Dockerfile Makefile LICENSE

IMAGES:  .jpg .jpeg .gif .webp .png (>50KB)
MEDIA:   .mp4 .avi .mov .mp3 .wav
DOCS:    .pdf .docx .doc .rtf
DATA:    .xlsx .xls .ods .csv (>100KB)
DB:      .db .sqlite
CREDS:   .env .key .pem (приватные)
TEMP:    .pyc .log .tmp .cache
DEPS:    venv/ node_modules/ __pycache__/ .so .exe

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults
  host: prod.example.com

python3 -c "import yaml; yaml.safe_load(open('file.yaml'))"

jq empty file.json
python3 -m json.tool file.json

created_at: 2026-02-19T10:30:00Z          # UTC
updated_at: 2026-02-19T13:30:00+03:00     # Moscow time

# Project Name -- Оглавление

**Тип:** {business|saas|infrastructure}
**Статус:** {design|development|production}

[<- Назад к Parent Project](../INDEX.md)

## ОСНОВНЫЕ ДОКУМЕНТЫ

| Документ | Описание |
|----------|----------|
| [PROJECT.md](PROJECT.md) | Полное описание |

## О ПРОЕКТЕ

{1-2 абзаца}

## СВЯЗИ

- **Родительский:** [Parent](../INDEX.md)

[<- Назад к Parent Project](../INDEX.md)

test -f INDEX.md && echo "INDEX.md OK" || echo "INDEX.md missing"
test -f PROJECT.md && echo "PROJECT.md OK" || echo "PROJECT.md missing"
test -f CLAUDE.md && echo "CLAUDE.md OK" || echo "CLAUDE.md missing"
grep -q "Назад" INDEX.md && echo "Navigation OK" || echo "No navigation"

project-name/
├── INDEX.md              ← Оглавление
├── CONCEPT.md            ← 1. Концепция и идея
├── ANALYSIS.md           ← 2. Анализ рынка
├── BUSINESS_MODEL.md     ← 3. Бизнес-модель
├── IMPLEMENTATION.md     ← 4. План реализации
├── PROJECT.md            ← Полное описание (сводка)
└── CLAUDE.md             ← Контекст для Claude

1. Предложить: "Предлагаю добавить в глоссарий: [термин] -- [определение]. Ок?"
2. После подтверждения -- добавить в GLOSSARY_STANDARD.md
3. Если платформенный -- также обновить глоссарий платформы

### [Термин]
**Canonical:** единственное эталонное название
**Code:** машинный код в файлах/системах
**Synonyms:** варианты, SEO-формы, разговорные названия
**Docs:** ссылки на документы
**Note:** уточнение, контекст, примеры

[ТИП]: [краткое описание]

[детали если нужны]

[действие если нужно]

<Вопрос>?
  1) <Вариант 1>
  2) <Вариант 2>
  3) <Вариант 3>
  0) Отмена / Выход

Выбор [номер]: