type: standard
aspect: naming
title: "Единый стандарт именования платформы"
version: 3.2.0
date: 2026-03-30
status: active
replaces: naming-files.md v1.0.0, naming-standard.md (draft)

Единый стандарт именования платформы

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

Стандарт описывает именование в $WORKSPACE (git-репозиторий):
документы, код, конфигурации, компоненты платформы.

Не описывает:
- $DATASPACE — файлы данных (*.csv, *.xlsx, бэкапы, медиа) → отдельный стандарт
- Внешние ресурсы (API, S3, БД) → architect/concept/RESOURCES.md

ЧАСТЬ 1 — ФАЙЛЫ

Четыре типа файлов в $WORKSPACE:

Тип	Примеры	Правила именования
Документы	`naming-workspace.md`, `platform.draft.md`	Формула `aspect-object.role.md`
Служебные	`CLAUDE.md`, `index.yaml`, `README.md`	Фиксированные имена
Код	`.py`, `.go`, `*.ts`	По правилам языка → `format-code.md`
Конфиги	`docker-compose.yaml`, `.env`	По правилам инструмента

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

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

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

1.2 Девять аспектов (фиксированные)

Aspect	Вопрос	Пример
`typology`	ЧТО это?	`typology-project-types.md`
`structure`	КАК УСТРОЕНО?	`structure-workspace.md`
`format`	КАК ВЫГЛЯДИТ?	`format-document.md`
`naming`	КАК НАЗЫВАТЬ?	`naming-workspace.md`
`lifecycle`	КАК ЖИВЁТ?	`lifecycle-project-states.md`
`policy`	ЧТО МОЖНО?	`policy-security.md`
`process`	КАК ДЕЛАТЬ?	`process-deployment.md`
`operation`	КАКИЕ ДЕЙСТВИЯ?	`operation-cleanup.md`
`guidance`	КАК ПРИМЕНЯТЬ?	`guidance-project-development-ai.md`

1.3 Роли файлов

Суффикс перед расширением — показывает назначение файла:

Role	Статус	Назначение	Пример
(нет)	active	Основной документ	`naming-workspace.md`
`.draft`	active	Черновик в работе	`platform.draft.md`
`.idea`	active	Сырая идея	`concept.idea.md`
`.task`	active	Задача в очереди	`2026-03-30-deploy.task.yaml`
`.tpl`	planned	Шаблон документа	`project.tpl.md`
`.spec`	planned	Спецификация, ТЗ	`feature.spec.md`
`.data`	planned	Данные (machine-readable)	`catalog.data.csv`
`.cache`	planned	Автогенерируемый файл	`state.cache.yaml`

find . -name "*.draft.md"   # все черновики
find . -name "*.idea.md"    # все идеи
find . -name "*.task.yaml"  # все задачи
find . -name "AI.md"        # все AI-инструкции компонентов

1.4 Формат файла задачи

[YYYY-MM-DD]-[name].task.yaml

Дата — ISO 8601. Обеспечивает хронологическую сортировку при ls.

2026-03-30-deploy-worker.task.yaml
2026-02-14-platform-revision.task.yaml

1.5 Отчёты и логи событий

Отчёт — событие в жизни проекта. Место — LOG.md.
Большой отчёт → LOG-[тема].md:

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

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

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

Код — именуется по правилам языка → format-code.md

1.7 Регистр, разделители и язык

Правило регистра зависит от типа файла:

Формульные файлы (аспект-объект):   lowercase + дефисы
Служебные файлы (README, CLAUDE):   UPPERCASE без подчёркиваний
Машинные файлы (index.yaml, .env):  lowercase

Формульные файлы — только lowercase и только дефисы:

✅ typology-project-types.md
✅ naming-workspace.md
❌ Typology_Project_Types.MD    (UPPERCASE + подчёркивания)
❌ typologyProjectTypes.md      (camelCase)
❌ naming_workspace.md          (подчёркивания запрещены везде и всегда)

Язык — зависит от раздела:

Платформа (infra/, system/, library/, architect/) — только латиница:

✅ deploy-worker.task.yaml
❌ план-миграции.md        (кириллица запрещена)

Проекты (projects/org/*/) — латиница рекомендуется, кириллица допустима:

✅ migration-plan.md       (рекомендуется)
✅ план-миграции.md        (допустимо)
❌ ПЛАН_МИГРАЦИИ.md        (подчёркивания запрещены везде)

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

Служебные файлы не используют формулу аспектов. Имена фиксированные.

UPPERCASE  →  человек / AI читает    (README.md, CLAUDE.md, AI.md, STATUS.md)
lowercase  →  машина читает          (index.yaml, .env)

Универсальные (в любой папке):

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

Правила размещения CLAUDE.md и AI.md:

Файл	Где создавать	Где НЕ создавать
`CLAUDE.md`	Корень workspace, ключевые разделы (`architect/`, `infra/`, `projects/org/`), компонент — если есть нюансы	Каждая вложенная папка (`scripts/`, `css/`)
`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 — без реальных значений)

ЧАСТЬ 2 — ПАПКИ

Обычные папки

Имена в lowercase, разделитель — дефис:

architect/standards/
projects/org/
library/connectors/

Два режима @ папок

@name        — категория / классификатор (без точки)
  projects/org/@biz-lideravto/
  @templates/@org/
  @templates/@mkt/          ← категория внутри категории — допустимо

@name.type   — компонент платформы (с точкой)
  infra/@md-viewer.service/
  system/@projector.agent/
  library/@utils.lib/

@name.qualifier.type   — компонент с уточнением (квалификаторы добавляются слева)
  @lider.drupal.web/         ← Drupal веб-приложение lider
  @ozon.import.connector/    ← коннектор импорта Ozon
  @admin.auth.service/       ← сервис авторизации admin
  Правило: тип — крайний правый; квалификаторы — левее типа.

Системные папки (`.` prefix)

Скрытые встроенные службы воркспейса. Не деплоятся отдельно:

.queue/      ← очередь задач
.monitor/    ← мониторинг и алерты
.claude/     ← конфиг Claude Code

Отличие: .name/ — встроено в воркспейс. @name.type/ — деплоится и управляется.

Специальные префиксы папок — только два: . и @. Подчёркивания не используются.

Служебные папки

arh/     ← архив устаревшего
tmp/     ← временные файлы (в .gitignore)

Черновики не собираются в папку — файл получает роль .draft или .idea и остаётся на месте.

ЧАСТЬ 3 — КОМПОНЕНТЫ ПЛАТФОРМЫ

Иерархия

INSTANCE → COMPONENT → SERVICE

Уровень	Термин	Формат	Пример
Физический сервер / VM	Instance	`name`	`papa`, `worker`
Логическая единица	Component	`@name.type`	`@papa.gateway`
Процесс внутри компонента	Service	`service-name`	`wireguard`, `nginx`

Типы компонентов

Инфраструктура:

Type	Назначение	Пример
`.server`	Сервер / VPS	`@dev-pro.server`
`.pc`	Компьютер оператора	`@kt-scraper.pc`
`.gateway`	Сеть: VPN / DNS / proxy / nginx	`@papa.gateway`
`.storage`	Файлы, бэкапы, S3	`@beget-s3.storage`
`.infra`	Инфраструктурный комплекс	`@kt-station.infra`

Приложения:

Type	Назначение	Пример
`.app`	Полноценное приложение (логика + UI)	`@nocodb.app`
`.ui`	Только веб-интерфейс	`@admin.ui`
`.web`	Сайт	`@beget-panel.web`
`.service`	Платформенный сервис / демон	`@md-viewer.service`
`.system`	Сложный комплекс сервисов	`@bot-platform.system`

AI и данные:

Type	Назначение	Пример
`.agent`	AI-агент (Claude)	`@projector.agent`
`.model`	LLM	`@ollama.model`
`.db`	База данных	`@postgres.db`
`.cache`	Кэш, очереди	`@redis.cache`
`.data`	MDM, каталоги	`@catalog.data`
`.knowledge`	Wiki, RAG	`@wiki.knowledge`

Интеграции и инструменты:

Type	Назначение	Пример
`.connector`	Подключение к внешнему API	`@openrouter.connector`
`.adapter`	Адаптер формата / данных	`@ozon.adapter`
`.integration`	Бизнес-интеграция	`@ozon-1c.integration`
`.lib`	Библиотека, утилиты	`@utils.lib`
`.tool`	Утилита, CLI	`@doctor.tool`
`.registry`	Git, пакеты, образы	`@gitea.registry`
`.monitor`	Наблюдение, алерты	`@prometheus.monitor`

Структура компонента-агента

system/@projector.agent/
├── AI.md              ← определение агента: роль, правила, протоколы
├── CLAUDE.md          ← навигатор папки (короткий, загружается автоматически)
└── index.yaml         ← зависимости компонента

Карта инстансов Platform 2.0

Instance: mama           ← закрыт, источник истины
└── @mama.registry

Instance: papa           ← единственный публичный вход
└── @papa.gateway

Instance: projector      ← управление проектами
├── @projector.agent
└── @scheduler.service

Instance: worker         ← production окружение
├── @app.service
├── @postgres.db
└── @redis.cache

Instance: llm            ← языковые модели
└── @ollama.model

Instance: backup         ← резервное хранилище
└── @backup.storage

Instance: data           ← MDM / каталоги
└── @catalog.data

Instance: knowledge      ← база знаний / wiki
└── @wiki.knowledge

ЧАСТЬ 4 — ИЕРАРХИЯ ВОРКСПЕЙСА

Корневая структура

$WORKSPACE/
│
├── architect/       ← МЕТОДОЛОГИЯ: теория, стандарты, концепция
├── system/          ← ЯДРО: агенты, сервисы платформы
├── library/         ← БИБЛИОТЕКА: переиспользуемые компоненты
├── infra/           ← ИНФРАСТРУКТУРА: серверы, сервисы, конфиги
├── projects/        ← ПРОЕКТЫ: бизнес-проекты организации
│
├── @templates/      ← ШАБЛОНЫ: коллекции шаблонов (@org/, @mkt/, @ops/)
│
├── .queue/          ← системная: очередь задач
├── .monitor/        ← системная: мониторинг
└── .claude/         ← системная: конфиг Claude Code

Правило: только эти папки в корне. Всё остальное — внутри них или в arh/.

Иерархия проектов

projects/
└── org/                         ← организация
    ├── @biz-lideravto/          ← бизнес-проект с @ классификатором
    │   ├── it/                  ← IT-раздел
    │   ├── biz/                 ← бизнес-раздел
    │   └── management/          ← управление
    │
    ├── pirotehnika/             ← plain (небольшой или экспериментальный)
    │
    └── @it-site-lideravto/      ← IT-проект с @ классификатором

Когда @biz-name/: активный бизнес-проект с формальной структурой (it/, biz/, management/).
Когда plain name/: прототип, эксперимент, небольшой проект.

Классификаторы @ в org/:

Префикс	Смысл	Пример
`@biz-`	Бизнес-проект	`@biz-lideravto/`
`@it-`	IT-проект / сайт	`@it-site-lideravto/`
`@legal`	Юридическая сущность	`@legal/`

Иерархия внутри компонента

Компонент @name.type/ может иметь произвольную внутреннюю структуру.
Стандартные подпапки:

@name.type/
├── CLAUDE.md         ← контекст
├── index.yaml        ← зависимости
├── scripts/          ← скрипты
├── config/           ← конфиги
├── docs/             ← документация
└── src/              ← исходный код (если есть)

Правила вложенности

Максимальная глубина от корня воркспейса — 6 уровней
Глубже 6 уровней → сигнал что нужна реструктуризация
Пример допустимого: projects/org/@biz-lideravto/it/docs/oem/ (6 уровней)

workspace/           ← 1
  projects/          ← 2
    org/             ← 3
      @biz-xxx/      ← 4
        it/          ← 5
          docs/      ← 6  ← предел

Что НЕ должно быть в корне

❌ L0-ORG/, L2-DATA/, L3-INFRA/     → arh/ (устаревшая L-модель)
❌ constructors/                     → architect/projects/custom-db/
❌ solutions/                        → arh/ или projects/
❌ exchange/                         → .gitignore (рабочие логи)
❌ security/                         → .gitignore (логи аудита)
❌ node_modules/                     → .gitignore
❌ generated/                        → .gitignore или tmp/
❌ lideravto/, pirotehnika/          → переместить в projects/org/
❌ *.csv, *.html в корне             → переместить в проект или tmp/

CHANGELOG

2026-03-30 — v3.2.0

Реструктуризация: 5 частей → 4 части
Служебные файлы перемещены в Часть 1 (файлы) — логически они файлы, не отдельный раздел
Часть 2: Папки (бывшая Часть 3)
Часть 3: Компоненты (бывшая Часть 4)
Часть 4: Иерархия воркспейса (бывшая Часть 5)
Добавлено: правило @name.qualifier.type — составные типы через квалификаторы слева
Добавлено: AI.md заменяет name.ai.md (роль .ai удалена)
Добавлено: правила размещения CLAUDE.md/AI.md/README.md с таблицей

2026-03-30 — v3.1.0

Удалена папка _draft/ — избыточна, черновики используют роли .draft / .idea
Правило подчёркиваний стало абсолютным: запрещены везде и всегда, без исключений
Специальные префиксы папок — только . и @

2026-03-30 — v3.0.0

Добавлена Часть 5: Иерархия воркспейса
Исправлено: .tpl пример → project.tpl.md (lowercase)
Добавлено: .env.example — пометка что в git без реальных значений
Объединены все правила из structure-workspace.md (ИМЕНОВАНИЕ) в этот документ

2026-03-30 — v2.1.1

Исправлено: _archive/ → arh/, _tmp/ → tmp/ (по реальной практике)
Исправлено: пример .draft — platform.draft.md (lowercase)
Уточнено: роль .ai не использует формулу аспектов
Уточнено: README.md (краткое) vs INDEX.md (полный структурированный)

2026-03-30 — v2.1.0

Добавлена роль .ai — инструкция AI-агента
Добавлена роль .task (active) с форматом [YYYY-MM-DD]-[name].task.yaml
index.yaml добавлен в служебные файлы
Правило регистра: UPPERCASE = человек читает, lowercase = машина читает
Добавлен паттерн .name/ — системные папки платформы
@ режимы: два — категория и компонент
Правило языка: платформа — только Latin; проекты — Latin/кириллица допустима
Отчёты → LOG.md / LOG-тема.md
Подчёркивания запрещены везде

2026-03-30 — v2.0.0

Переименован из naming-files.md → naming-workspace.md
Добавлен двойной режим @: категория vs компонент
Типы компонентов

2026-02-19 — v1.0.0

Базовая формула aspect-object-detail.md
9 аспектов, lowercase, дефисы

Версия: 3.2.0
Статус: active
Владелец: architect
Заменяет: naming-files.md v1.0.0, naming-standard.md (draft), раздел ИМЕНОВАНИЕ из structure-workspace.md