type: standard
aspect: naming
title: "Стандарт именования платформы"
version: 1.0.0
date: 2026-03-30
status: active
owner: architect
replaces: naming-workspace.md v3.2.0, naming-dataspace.draft.md v0.1.0, naming-database.md v1.0.0

Стандарт именования платформы

ОБЛАСТЬ ПРИМЕНЕНИЯ

Стандарт описывает правила именования во всех пространствах платформы.

Пространство	Где	Что хранит
$WORKSPACE	git `/opt/claude-workspace`	Код, документы, конфиги, компоненты
$DATASPACE	S3 `/mnt/beget-s3`	Данные: xlsx, csv, медиа
$BACKUPSPACE	`/mnt/beget-infra` (S3 или папка на сервере)	Резервные копии
$DATABASE	PostgreSQL	Базы, таблицы, колонки
$INFRASTRUCTURE	DNS, Docker, Git, env	Инфраструктурные ресурсы

Не описывает:
- Переменные и функции в коде → naming-variables.md
- Структуру папок → structure-workspace.md
- Типы компонентов → typology-components.md
- Типы файлов (11 классов) → format-file-types.md

ОБЩИЕ ПРАВИЛА

Регистр

Формульные документы:   lowercase            (naming-workspace.md)
Сервисные файлы:        UPPERCASE            (README.md, CLAUDE.md, INDEX.md)
Машинные файлы:         lowercase            (index.yaml, .env)

Разделители

Дефис (-)    — стандарт для файлов, папок, компонентов
Точка (.)    — разделитель роли и расширения  (naming-platform.draft.md)
               разделитель типа компонента     (@name.type)

Язык

Пространство	Правило
$WORKSPACE	Только латиница — везде без исключений
$DATASPACE, $BACKUPSPACE, $DATABASE, $INFRASTRUCTURE	Только латиница

Подчёркивания

Пространство	Правило	Обоснование
$WORKSPACE	❌ Запрещены везде и всегда	Дефис — стандарт web, URL, CSS
$DATASPACE	✅ Допустимы в именах файлов	Python/SQL/1С генерируют `_`
$BACKUPSPACE	✅ Допустимы	Следуют конвенции источника
$DATABASE	✅ Обязательны (snake_case)	Стандарт SQL
$INFRASTRUCTURE	Зависит от инструмента	См. раздел

$WORKSPACE

Документы — Формула

[aspect]-[object]-[detail].[role].format

Часть	Обязательность	Описание
`aspect`	✅	Тема/раздел (9 фиксированных)
`object`	✅	Объект описания
`detail`	опционально	Уточнение
`role`	опционально	Состояние файла
`format`	✅	Расширение

Категории стандартов (фиксированные)

Категория	Тема	Пример
`typology`	ЧТО это? Классификация сущностей	`typology-project-types.md`
`structure`	Структура файлов и папок	`structure-workspace.md`
`format`	Форматы и шаблоны	`format-document.md`
`naming`	Правила именования	`naming-platform.md`
`lifecycle`	Жизненный цикл	`lifecycle-project-states.md`
`policy`	Политики и ограничения	`policy-security.md`
`process`	Процессы и протоколы	`process-deployment.md`
`operation`	Операции и команды	`operation-cleanup.md`
`guidance`	Руководства по применению	`guidance-project-development-ai.md`

Роли файлов

Role	Статус	Назначение	Когда использовать
(нет)	active	Основной документ	Финализирован, применяется
`.draft`	active	Черновик в работе	Пишется / обсуждается, не применять
`.idea`	active	Сырая идея	Мысль, не проработанная
`.task`	active	Задача в очереди	Тикет для исполнителя
`.ai`	active	Документ / код для AI	Инструкция, протокол или промпт для AI-агента
`.tpl`	planned	Шаблон	Заготовка для создания нового документа
`.spec`	planned	Спецификация / ТЗ	Требования к фиче или системе
`.data`	planned	Машиночитаемые данные	CSV/YAML как данные, не конфиг
`.cache`	planned	Автогенерируемый файл	Создаётся инструментом, не редактируется

Формат задачи: [YYYY-MM-DD]-[name].task.yaml

2026-03-30-deploy-worker.task.yaml

find . -name "*.draft.md"    # все черновики
find . -name "*.idea.md"     # все идеи
find . -name "*.task.yaml"   # все задачи
find . -name "*.ai.md"       # все файлы предназначенные для AI-агентов
find . -name "AI.md"         # все определения агентов (корень @name.agent/)

Форматы файлов

Format	Когда	Читатель
`.md`	Документы, стандарты, инструкции	человек
`.yaml`	Конфиги, метаданные, задачи — основной	машина
`.yml`	То же, для совместимости с инструментами	машина
`.json`	API, обмен данными	машина
`.csv`	Таблицы < 100KB (больше → $DATASPACE)	машина

Правила именования

Формульные файлы:   lowercase + дефисы
Служебные файлы:    UPPERCASE без подчёркиваний
Машинные файлы:     lowercase

✅ naming-platform.md
✅ structure-workspace.md
✅ CLAUDE.md, INDEX.md, README.md
✅ index.yaml, .env
❌ naming_workspace.md     (подчёркивания запрещены везде и всегда)
❌ NamingWorkspace.md      (camelCase запрещён)
❌ NAMING-WORKSPACE.MD     (UPPERCASE для формульных)

Язык: только латиница — везде в $WORKSPACE без исключений.

Служебные файлы

Универсальные:

Файл	Читатель	Назначение
`CLAUDE.md`	AI + человек	Навигатор папки: что здесь, куда идти. Загружается автоматически при входе. Только навигация — не правила.
`AI.md`	AI + человек	Определение агента: роль, правила, протоколы. Только в компонентах-агентах.
`INDEX.md`	человек	Полный структурированный индекс раздела
`README.md`	человек	Краткое описание — только для публичных/внешних компонентов
`CHANGELOG.md`	человек	История изменений кода/версий
`index.yaml`	машина	Манифест компонента: зависимости, метаданные

Правила размещения:

Файл	Где создавать ✅	Где НЕ создавать ❌
`CLAUDE.md`	Корень workspace, ключевые разделы (`architect/`, `infra/`, `projects/org/`), компонент — только если есть нюансы	Каждая вложенная папка (`scripts/`, `css/`, `src/`)
`AI.md`	Только в компонентах-агентах (`@name.agent/`, `system/agents/`)	Обычные компоненты, проекты, папки
`README.md`	Публичные компоненты, GitHub-репозитории	Внутри платформы — не нужен

Шаблон CLAUDE.md:

# [Папка] — [одна строка: что это]

## СОДЕРЖИМОЕ
| Файл / Папка | Назначение |

## НАВИГАЦИЯ
| Задача / тема | Куда идти |

## ВАЖНО   ← только если есть реальные нюансы

Проектные:

Файл	Назначение
`PROJECT.md`	Описание проекта (9 вопросов)
`STATUS.md`	Текущее состояние
`ROADMAP.md`	Планы и фазы
`TODO.md`	Список задач
`LOG.md`	Журнал: решения, события, отчёты
`ARCHITECTURE.md`	Архитектура решения

Конфиденциальные (всегда в .gitignore):

Файл	Назначение
`SECRETS.md`	Секреты и ключи
`.credentials.md`	Учётные данные
`.env`	Переменные окружения (не в git)
`.env.example`	Шаблон переменных (в git, без реальных значений)

Отчёты и логи:

❌ MIGRATION_COMPLETE_REPORT.md   (отдельный файл-отчёт)
✅ LOG.md                         (запись о миграции внутри)
✅ LOG-migration.md               (отдельный лог если большой)

$DATASPACE

Файлы данных — Формула

Датированные файлы (прайсы, выгрузки, отчёты):

{source}-{YYYY-MM-DD}.{ext}
{source}-{YYYY-MM-DD}-{suffix}.{ext}

Часть	Описание	Пример
`source`	Источник: поставщик, система	`jf`, `maxsem`, `ozon`, `1c`
`YYYY-MM-DD`	Дата ISO 8601	`2026-03-30`
`suffix`	Уточнение (опционально)	`orders`, `prices`

✅ jf-2026-03-30.xlsx
✅ ozon-2026-03-30-orders.csv
✅ 1c-2026-03-30-export.xml
✅ jf_2026-03-30.xlsx          (подчёркивание допустимо — конвенция Python/1С)
❌ MASTER_PRICE_LIST (1).xlsx  (пробелы, скобки, UPPERCASE)
❌ 16.10 Прайс Maxsem.xlsx     (кириллица, пробелы)
❌ new-prices.xlsx             (нет даты — неясно когда актуально)

Файлы без временного контекста (справочники, медиа):

{entity}-{detail}.{ext}       — справочники
{article}-{view}.{ext}        — медиа товаров

✅ categories-mapping.csv
✅ 12345-front.jpg
❌ photo1.jpg                  (неинформативно)

Где хранить по размеру

Размер	Хранилище
CSV < 100KB	$WORKSPACE допустимо
CSV < 10K строк	$DATASPACE
CSV 10K–100K строк	SQLite или CSV в $DATASPACE
CSV > 100K строк	PostgreSQL
Excel, изображения	$DATASPACE (не в git)

Папки DATASPACE

$DATASPACE/
├── projects/              ← данные проектов (зеркало $WORKSPACE/projects/)
│   ├── my/
│   │   └── {project}/
│   │       ├── inbox/
│   │       ├── media/     ← медиа проекта (физически здесь; может быть примонтирован диск)
│   │       │   ├── images/
│   │       │   ├── video/
│   │       │   └── documents/
│   │       └── archive/
│   └── org/
│       └── {project}/
│           ├── inbox/
│           ├── prices/
│           ├── products/
│           ├── exports/
│           ├── media/     ← медиа проекта (физически здесь; может быть примонтирован диск)
│           │   ├── images/
│           │   ├── video/
│           │   └── documents/
│           └── archive/
├── releases/              ← сборки компонентов для деплоя (.zip, .tar.gz)
│   ├── connectors/
│   ├── extensions/
│   └── applications/
└── archive/               ← архивные данные

Что куда:

Файл	Путь в $DATASPACE
Прайс-листы, CSV, Excel	`projects/{type}/{project}/prices/`
Выгрузки, данные	`projects/{type}/{project}/exports/`
Фото > 50KB, видео	`projects/{type}/{project}/media/images/`
PDF, DOCX	`projects/{type}/{project}/media/documents/`
Собранный модуль для деплоя	`releases/`
SVG, PNG < 50KB	$WORKSPACE допустимо

Медиа-стратегия проекта — фиксируется в index.yaml:

# projects/org/lideravto/index.yaml
media_storage: dataspace    # папка media/ в $DATASPACE (по умолчанию)
# media_storage: mounted     # media/ — точка монтирования отдельного S3/диска
# media_storage: cdn         # внешний CDN (Cloudflare, CloudFront)

Путь media/ в проекте всегда один и тот же. Отличается только то, что за ним стоит физически.

Стандартная структура проекта в projects/:

projects/org/{project}/
├── inbox/           ← входящие необработанные файлы
├── prices/          ← прайс-листы поставщиков
│   └── {supplier}/  ← по поставщику: jf/, maxsem/
├── products/        ← данные номенклатуры
│   └── 1c/          ← выгрузки из 1С
├── exports/         ← выгрузки для внешних систем
└── archive/
    └── {YYYY-MM}/   ← архив по месяцу

Обязательные: inbox/, archive/
Рекомендуемые: prices/, products/, exports/

Жизненный цикл файла в projects/:

inbox/  →  {тематическая}/  →  archive/{YYYY-MM}/

Зеркальность с $WORKSPACE:

$WORKSPACE/projects/my/{project}/          ← личные: код, доки
$DATASPACE/projects/my/{project}/          ← личные: данные, выгрузки
$DATASPACE/projects/my/{project}/media/    ← медиа (физически здесь или примонтировано)

$WORKSPACE/projects/org/{project}/         ← общественные/бизнес: код
$DATASPACE/projects/org/{project}/         ← данные, выгрузки
$DATASPACE/projects/org/{project}/media/   ← медиа (физически здесь или примонтировано)

Правило: media/ — всегда папка внутри проекта в $DATASPACE. Код обращается по одному пути независимо от физического хранилища за ним.

$BACKUPSPACE

Структура

$BACKUPSPACE/{server}/backup/
├── L0-SECRETS/          ← SSH ключи, credentials
├── L1-SYSTEM/           ← системные файлы
├── L2-DOCKER/           ← Docker volumes
├── L3-WORKSPACE/        ← исходный код (git bundle)
│   └── git-bundle/
├── L4-CLAUDE/           ← Claude конфиги и память
│   ├── claude-md/
│   └── settings/
├── L5-STATE/            ← состояние (опционально)
├── golden/              ← эталонные ручные копии
├── postgres/            ← дампы PostgreSQL
└── restic/              ← Restic repository

Формулы именования

{type}-{source}-{YYYYMMDD}-{HHMM}.{ext}

Тип	Формула	Пример
CLAUDE.md	`CLAUDE-{branch}-{YYYYMMDD}-{HHMM}.md`	`CLAUDE-main-20260330-0603.md`
Git bundle полный	`workspace-full-{YYYYMMDD}.bundle`	`workspace-full-20260330.bundle`
Git bundle инкремент	`workspace-incr-{YYYYMMDD}.bundle`	`workspace-incr-20260330.bundle`
PostgreSQL дамп	`{dbname}-{YYYYMMDD}-{HHMM}.sql`	`platform-20260330-0400.sql`
Workspace tar	`workspace-{YYYYMMDD}-{HHMM}.tar.gz`	`workspace-20260330-0500.tar.gz`
Docker volume	`{volume}-{YYYYMMDD}.tar.gz`	`postgres-data-20260330.tar.gz`
Эталонная копия	`{type}-golden-{YYYYMMDD}.{ext}`	`CLAUDE-golden-20260330.md`

Расписание

Тип	Частота	Ротация
CLAUDE.md	каждые 6ч	сегодня все; вчера 1; 7–30д воскресенья; 30–365д конец месяца
PostgreSQL	каждые 4ч	последние 7 дней
Git bundle	полный вс, инкремент пн–сб	4 полных + текущая неделя инкрементов
Workspace tar	ежедневно 05:00	последние 7 дней
Restic	каждые 6ч	24h hourly, 7d daily, 4w weekly, 6m monthly

$DATABASE

Формула таблицы

{type}_{level}_{entity}[_{instance}]

Часть	Описание	Примеры
`type`	3-буквенный код проекта	`crm`, `pir`, `lid`
`level`	Уровень данных	`app`, `sol`, `prj`, `usr`
`entity`	Имя сущности (snake_case)	`users`, `orders`, `funnel_stages`
`instance`	Экземпляр (если нужно несколько)	`spb`, `msk`, `retail`

crm_app_users          ← CRM, приложение, пользователи
crm_prj_clients        ← CRM, проект, клиенты
pir_prj_orders_retail  ← Пиротехника, заказы, розница

Коды типов

Код	Проект
`crm`	CRM
`mrk`	Маркетинг
`pir`	Пиротехника
`lid`	Лидер Авто
`ozn`	Ozon
`anl`	Аналитика
`doc`	Документы
`tsk`	Задачи
`sys`	Системные

Уровни данных

Код	Уровень	Что хранит
`app`	Application	Пользователи, настройки, логи
`sol`	Solution	Справочники, шаблоны, конфиги
`prj`	Project	Бизнес-данные: клиенты, заказы
`usr`	User	Персональные настройки

Колонки

snake_case, единственное число
✅ first_name, order_id, created_at
❌ FirstName, orderId, createdAt

Системные поля в каждой таблице:

Поле	Тип
`id`	UUID / INT
`created_at`	TIMESTAMP
`updated_at`	TIMESTAMP
`created_by`	UUID → `app_users.id`

Имена баз данных

{system}_{base}

dev_main      ← основная БД dev-pro
prd_main      ← продакшен
dev_archive   ← архивные данные

$INFRASTRUCTURE

S3 бакеты

{org}-{purpose}

beget-s3      ← данные проектов ($DATASPACE)
beget-infra   ← бэкапы ($BACKUPSPACE, если используется S3)

DNS и субдомены

{service}.{domain}

docs.0kt.ru      ← документация
api.0kt.ru       ← API
admin.0kt.ru     ← администрирование

Docker образы

{type}-{name}:{version}

nginx-proxy:1.2.0
mcrm-app:2.1.0
nocodb:latest

Docker контейнеры

Роль	Формат	Пример
База данных	`{type}-db`	`nocodb-db`, `postgres-db`
Приложение	`{type}-app`	`mcrm-app`
Сервис	`{type}-{service}`	`mcrm-whatsapp`, `pir-sync`
Volume	`{type}-{purpose}-data`	`postgres-main-data`
Network	`{type}-net`	`platform-net`

Nginx конфиги

{домен}              ← crm.0kt.ru
api.{домен}          ← api.crm.0kt.ru
{тип}.{домен}        ← piro.0kt.ru

Git ветки

main              ← основная
feature/{name}    ← новая функциональность
fix/{name}        ← исправление
release/{version} ← релиз

v{major}.{minor}.{patch}   ← теги релизов

Переменные окружения

UPPER_SNAKE_CASE

APP_*        ← настройки приложения
DB_*         ← база данных
S3_*         ← объектное хранилище
TG_*         ← Telegram
OZON_*       ← Ozon API

Systemd сервисы

{type}.service           ← mcrm.service
{type}-worker.service    ← mcrm-worker.service
{type}-{task}.timer      ← pir-sync.timer

Redis ключи

{namespace}:{entity}:{id}:{field}

user:123:session
cache:products:list
lock:import:ozon
queue:tasks:pending

Типы компонентов и сервисов: → typology-components.md, typology-service-types.md

CHANGELOG

2026-03-30 — v1.0.0

Создан на основе reform-naming-arch как объединение трёх стандартов
Добавлен раздел $INFRASTRUCTURE: Nginx конфиги
Роли: добавлены .draft, .idea, .task, .ai, .tpl, .spec, .data, .cache; добавлена колонка Статус
Форматы: добавлен .yml как вариант совместимости
Конфиденциальные: добавлен .credentials.md
БД коды: полный список — crm, mrk, pir, lid, ozn, anl, doc, tsk, sys (anl/doc/tsk — новые)
Язык: только латиница везде в $WORKSPACE без исключений
$DATASPACE: media/ — папка внутри проекта, не отдельная зона
Обоснования: HTML-комментарии к каждому разделу

Версия: 1.0.0
Статус: active
Владелец: architect
Заменяет: naming-workspace.md v3.2.0, naming-dataspace.draft.md v0.1.0, naming-database.md v1.0.0