format-document.md

type: standard
aspect: format
title: "Стандарт документов платформы"
status: active
version: 2.0.0
date: 2026-02-19
owner: architect
supersedes: v1.0.0 (2025-11-28)

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

Типы документов и правила работы с ними в платформе.

ПРИНЦИП

Документация = код. Хранится в git, версионируется, проходит review.

Формат: Markdown (.md) — основной формат всей документации.

ФОРМАТЫ ДОКУМЕНТОВ

1. Markdown (.md)

Основной формат для всей документации платформы.

Почему Markdown:
- ✅ Читабелен в сыром виде
- ✅ Git-friendly (diff, merge)
- ✅ Рендерится в docs.0kt.ru
- ✅ Универсальный (GitHub, GitLab, любой редактор)
- ✅ Конвертируется в HTML, PDF

.md          - обычный документ
.ai.md       - AI-агент (промпт для Claude)
.credentials.md - секреты (НЕ в git)

2. YAML (.yaml, .yml)

Для структурированных данных и метаданных.

Использование:
- Индексы (index.yaml)
- Конфигурация (config.yaml)
- Frontmatter в .md файлах
- Схемы данных

---
type: project
title: "Pirotehnika"
status: active
owner: business
---

3. JSON (.json)

Для конфигурации инструментов и приложений.

Использование:
- package.json
- tsconfig.json
- .vscode/settings.json
- Схемы данных

ТИПЫ ДОКУМЕНТОВ ПО НАЗНАЧЕНИЮ

1. CLAUDE.md — Инструкции для агента

Назначение: Промпт для Claude агента, описание роли и контекста.

$WORKSPACE/CLAUDE.md                    ← корневой (главный)
architect/CLAUDE.md                     ← роль Архитектора
projects/{name}/CLAUDE.md               ← контекст проекта
library/{module}/CLAUDE.md              ← контекст модуля

# {Название контекста}

**Версия:** X.Y.Z
**Дата:** YYYY-MM-DD
**Тип:** {role|context|prompt}

## РОЛЬ

Кто ты в этом контексте.

## ЧТО ДЕЛАЕШЬ

Основные функции.

## ЧТО НЕ ДЕЛАЕШЬ

Ограничения.

## ССЫЛКИ

Связанные документы.

Примеры:
- $WORKSPACE/CLAUDE.md - главный промпт
- architect/CLAUDE.md - роль Архитектора
- projects/org/pirotehnika/CLAUDE.md - контекст проекта

2. PROJECT.md — Описание проекта

Назначение: Полное описание бизнес-проекта или IT-решения.

projects/{org}/{project}/PROJECT.md

---
type: project
status: active|development|archived
owner: {team}
---

# {Название проекта}

## ОПИСАНИЕ

Что это за проект, для чего.

## СТРУКТУРА

Как организован.

## ТЕХНОЛОГИИ

Стек технологий.

## ДАННЫЕ

Источники данных, БД.

## DEPLOYMENT

Как разворачивается.

## ССЫЛКИ

Связанные ресурсы.

3. README.md — Описание модуля/папки

Назначение: Краткое описание содержимого папки или модуля.

# {Название модуля}

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

## Содержание

Что находится в этой папке.

## Использование

Как использовать (если код).

## Ссылки

Связанные документы.

Правило именования:
- README.md (UPPERCASE) - для важных модулей
- readme.md (lowercase) - для вспомогательных

Примеры:
- library/connectors/api/telegram/README.md
- system/agents/README.md

4. STANDARDS — Стандарты

Назначение: Правила и требования платформы.

architect/standards/{category}/{NAME}.md

standards/
├── 5-format/        - форматы (файлы, документы, данные)
├── structure/      - структуры (папки, проекты)
├── processes/      - процессы (как делать)
├── 7-typology/          - типы систем
└── roles/          - роли агентов

---
type: standard
status: active|draft|deprecated
version: X.Y.Z
---

# Стандарт {название}

## ЗАЧЕМ

Проблема которую решает.

## ПРАВИЛА

Жесткие требования.

## ПРИМЕРЫ

Как применять.

## ИСКЛЮЧЕНИЯ

Когда можно нарушить (если есть).

Примеры:
- architect/standards/5-format/format-file-types.md
- architect/standards/AGENT_RULES.md

5. DECISIONS (ADR) — Архитектурные решения

Назначение: Фиксация архитектурных решений с обоснованием.

architect/decisions/{NNN}-{slug}.md

---
type: decision
id: ADR-{NNN}
status: accepted|proposed|deprecated|superseded
date: YYYY-MM-DD
---

# ADR-{NNN}: {Название решения}

## Контекст

Какая проблема, почему возникла.

## Решение

Что решили делать.

## Альтернативы

Что рассматривали, почему отказались.

## Последствия

Что изменится, плюсы/минусы.

## Связанные решения

Ссылки на другие ADR.

Примеры:
- architect/decisions/001-agents.md
- architect/decisions/002-platform-architecture.md

6. TICKETS — Тикеты/задачи

Назначение: Отслеживание задач, багов, технического долга.

architect/arh/operations/tickets/TICKET-{NNN}-{slug}.md

---
type: ticket
id: TICKET-{NNN}
status: TODO|IN_PROGRESS|DONE|CANCELLED
priority: LOW|MEDIUM|HIGH|CRITICAL
created: YYYY-MM-DD
owner: {team}
---

# TICKET-{NNN}: {Название}

## ПРОБЛЕМА

Что не так.

## РЕШЕНИЕ

Как исправить.

## ПЛАН

Шаги выполнения.

## КРИТЕРИИ ГОТОВНОСТИ

Когда считать выполненным.

Примеры:
- architect/arh/operations/tickets/TICKET-004-platform-restructure.md
- architect/arh/operations/tickets/TICKET-005-standards-structure-reform.md

7. TEMPLATES — Шаблоны

Назначение: Заготовки для создания новых документов/проектов.

architect/templates/{TYPE}_TEMPLATE.md

---
type: template
for: {project|document|agent}
---

# {Название шаблона}

[Инструкция по заполнению]

## Секция 1

[Что сюда писать]

## Секция 2

[Что сюда писать]

Примеры:
- architect/templates/PROJECT_TEMPLATE.md
- architect/templates/AGENT_TEMPLATE.md

8. INDEX — Индексы

Назначение: Навигация по большому разделу документации.

{section}/INDEX.md
{section}/index.yaml  (машиночитаемый)

# Индекс {раздела}

## Категория 1

| Документ | Статус | Описание |
|----------|--------|----------|
| [NAME.md](path) | active | Краткое описание |

## Категория 2

...

section: architect
version: 1.0.0
documents:
  - path: standards/format-file-types.md
    type: standard
    status: active
    title: "Стандарт типов файлов"

СТРУКТУРА ДОКУМЕНТА

Frontmatter (метаданные)

---
type: standard|project|decision|ticket|template
title: "Название документа"
status: active|draft|archived
version: X.Y.Z          # для standards
date: YYYY-MM-DD
owner: architect|team
---

id: TICKET-001          # для tickets/decisions
priority: HIGH          # для tickets
created: YYYY-MM-DD     # для tickets
supersedes: ADR-005     # для decisions/standards
tags: [api, security]   # для поиска

Заголовки

Правила:
- H1 (#) - ОДИН на документ (название)
- H2 (##) - основные секции
- H3 (###) - подсекции
- Не пропускать уровни (нельзя H1 → H3)

# Название документа (H1)

## Основная секция (H2)

Текст секции.

### Подсекция (H3)

Текст подсекции.

## Другая секция (H2)

Секции (рекомендуемые)

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

## ОПИСАНИЕ       - что это
## СТРУКТУРА      - как организовано
## ТЕХНОЛОГИИ     - стек
## ДАННЫЕ         - источники данных
## DEPLOYMENT     - как разворачивать
## ССЫЛКИ         - связанные ресурсы

## РОЛЬ           - кто ты
## ЧТО ДЕЛАЕШЬ    - функции
## ЧТО НЕ ДЕЛАЕШЬ - ограничения
## ССЫЛКИ         - связанные документы

Ссылки

[Другой документ](format-file-types.md)
[Секция в этом документе](#секция)

[Документация](http://docs.0kt.ru/architect/standards/format-file-types.md)

Правило: Внутри репозитория - относительные ссылки.

ИМЕНОВАНИЕ ДОКУМЕНТОВ

Правила

Slug (ЧПУ)

Тип	Формат	Примеры
Главные	UPPERCASE.md	CLAUDE.md, PROJECT.md, README.md
Стандарты	UPPERCASE.md	format-file-types.md, AGENT_RULES.md
Решения	NNN-slug.md	001-agents.md, 002-platform.md
Тикеты	TICKET-NNN-slug.md	TICKET-001-session-gap.md
Обычные	lowercase.md	index.md, readme.md

001-agents.md
002-platform-architecture.md
TICKET-005-standards-reform.md

001_agents.md              (underscore)
002platformarchitecture.md (без разделителя)
TICKET-005.md              (нет описания)

РАБОТА С ДОКУМЕНТАМИ

Создание нового документа

1. Выбрать тип (стандарт/проект/решение/тикет)

standards/     - стандарты
decisions/     - ADR
tickets/       - тикеты
projects/      - проекты

cp architect/templates/STANDARD_TEMPLATE.md \
   architect/standards/5-format/NEW_STANDARD.md

git add architect/standards/5-format/NEW_STANDARD.md
git commit -m "docs: Add NEW_STANDARD.md"

Обновление документа

cat document.md | grep "^version:"

3. Обновить версию (semver):
- Patch: 1.0.0 → 1.0.1 (исправления, мелкие правки)
- Minor: 1.0.1 → 1.1.0 (новые секции, расширение)
- Major: 1.1.0 → 2.0.0 (breaking changes, переписывание)

## CHANGELOG

### 2026-02-19 — v2.0.0
- Полное переписывание
- Добавлено 8 типов документов
- Расширены правила

### 2025-11-28 — v1.0.0
- Первая версия

git add document.md
git commit -m "docs: Update DOCUMENT.md to v2.0.0

- Complete rewrite
- Add 8 document types
- Expand guidelines
"

Архивирование документа

Когда архивировать:
- Документ устарел
- Заменён новым
- Больше не актуален

status: archived
archived_date: YYYY-MM-DD
superseded_by: path/to/new-document.md  # если есть замена

mv architect/standards/old.md \
   architect/arh/standards/old_vX.Y.Z_YYYY-MM-DD.md

СПЕЦИАЛЬНЫЕ ДОКУМЕНТЫ

.ai.md — AI-агенты

system/agents/{name}.ai.md
architect/architect.ai.md

# {Имя агента}

**Роль:** {краткое описание}
**Модель:** haiku|sonnet|opus

## КОНТЕКСТ

Что ты знаешь.

## ЗАДАЧИ

Что ты делаешь.

## ИНСТРУМЕНТЫ

Какие инструменты используешь.

## ПРИМЕРЫ

Примеры работы.

.credentials.md — Секреты

Назначение: Хранение паролей, токенов, API keys.

projects/{name}/.credentials.md
{module}/.credentials.md

# Credentials: {Проект/Модуль}

## API Keys

| Сервис | Key | Описание |
|--------|-----|----------|
| OZON | 123456 | API ключ |

## Пароли

| Где | Логин | Пароль |
|-----|-------|--------|
| БД | admin | pass123 |

## SSH Keys

chmod 600 .credentials.md  # только владелец может читать

ПРАВИЛА ОФОРМЛЕНИЯ

Язык

Основной: Русский
Технические термины: Английский (в оригинале)
Код: Английский (комментарии на русском если нужно)

Используй метод `fetch()` для запроса к API.

Стиль

Заголовки:
- Короткие (< 60 символов)
- Понятные
- Без точки в конце

Абзацы:
- Один абзац = одна мысль
- Пустая строка между абзацами

Списки:
- Пункты начинаются с маленькой буквы (если не предложение)
- Точки в конце - только если полные предложения

Длина строки

Почему:
- Удобно читать
- Хорошие diff в git
- Работает в терминале

Исключения:
- Таблицы
- Длинные ссылки
- Код

ВЕРСИОНИРОВАНИЕ

MAJOR.MINOR.PATCH

1.0.0 → первая стабильная версия
1.0.1 → исправления
1.1.0 → новые возможности (обратно совместимо)
2.0.0 → breaking changes

Правила:
- PATCH - исправления опечаток, уточнения, мелкие правки
- MINOR - новые секции, расширение функциональности, сохранение совместимости
- MAJOR - изменение структуры, удаление секций, несовместимые изменения

ЧЕКЛИСТ СОЗДАНИЯ ДОКУМЕНТА

ССЫЛКИ

CHANGELOG

2026-02-19 — v2.0.0

2025-11-28 — v1.0.0

Версия: 2.0.0
Автор: Claude Opus (Architect)
Статус: ACTIVE