architect/standards/arch-naming-workspace.md

type: standard
layer: arch
object: naming
aspect: workspace
form: text
title: "Именование в $WORKSPACE"
status: active
version: 1.0.0
date: 2026-04-15
knowledge_level: У1
parent: arch-platform-structure.md
deps:
- arch-platform-structure.md
- arch-document-system.md

Именование в $WORKSPACE

Стандарт именования файлов, папок, компонентов и модулей в $WORKSPACE. Охватывает: формулу arch-стандартов, служебные файлы, компоненты @name.type, проекты @type-name, регистр, разделители.

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

Регистр

Формульные документы:   lowercase        arch-platform-structure.md
Служебные файлы:        UPPERCASE        README.md, CLAUDE.md, INDEX.md
Машинные файлы:         lowercase        index.yaml, .env.example

Разделители

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

Язык

Только латиница — везде, без исключений.

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

Пространство Правило
$WORKSPACE Запрещены. Дефис — стандарт
$DATASPACE Допустимы (Python/SQL генерируют _)
$DATABASE Обязательны (snake_case)

2. ФОРМУЛА ИМЕНОВАНИЯ СТАНДАРТОВ

[layer]-[object]-[aspect].(тип).md
Часть Обязательность Значение Пример
layer да Слой платформы arch
object да Объект описания platform, project, document
aspect да Аспект (из 10 категорий) structure, policy, operation
(тип) нет Роль/статус файла .draft, .ai, .idea

10 фиксированных аспектов

Аспект Что описывает Пример
structure Файловая организация, схема arch-platform-structure.md
format Форматы, шаблоны, оформление arch-document-format.md
naming Правила именования arch-naming-workspace.md
lifecycle Жизненный цикл сущностей arch-project-lifecycle.md
policy Политики и ограничения arch-platform-policy.md
process Процессы и workflow arch-cicd-pipeline.md
operation Операции, команды, протоколы arch-deployment-operation.md
guidance Руководства по применению arch-project-it-structure.md
system Системные компоненты, реестры arch-agent-registry.md
protocol Протоколы взаимодействия arch-monitor-protocol.md

Примеры

arch-platform-structure.md        ← layer=arch, object=platform, aspect=structure
arch-document-format.md           ← layer=arch, object=document, aspect=format
arch-project-lifecycle.md         ← layer=arch, object=project, aspect=lifecycle
arch-naming-workspace.md          ← layer=arch, object=naming, aspect=workspace
arch-platform-policy.draft.md     ← тип=draft (черновик)
arch-agent-registry.ai.md         ← тип=ai (файл для AI-агента)

3. СЛУЖЕБНЫЕ ФАЙЛЫ УЗЛА

Четыре навигационных файла — обязательны на уровнях 0 (корень) и 1 (компоненты):

Файл Для кого Содержимое
AI.md любой AI роль, правила, что здесь
CLAUDE.md Claude Code AI.md + команды, пути, shortcuts
README.md люди / GitHub AI.md + объяснения и примеры
INDEX.md AI + люди каталог всех подпапок с описаниями и статусами

Порядок создания: AI.md → CLAUDE.md → README.md → INDEX.md

Раздел ТРОЙКА — обязателен в CLAUDE.md и README.md:

## ТРОЙКА
AI.md    — для агентов
CLAUDE.md — для Claude Code (вы здесь)
README.md — для людей
INDEX.md  — все файлы компонента с описаниями

Где создавать

Файл Где Где НЕ создавать
CLAUDE.md корень, компоненты, ключевые разделы вложенные папки (scripts/, src/)
AI.md только @name.agent/, system/agents/ обычные компоненты
README.md публичные компоненты / GitHub внутри платформы
INDEX.md уровни 0 и 1 по ситуации

Дополнительные служебные файлы

Проектные:

Файл Назначение
STATUS.md текущая стадия
LOG.md журнал решений (только пополняется)
BRIEF.md краткое описание задачи
CHANGELOG.md история изменений кода

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

Файл Назначение
.env переменные окружения
.env.example шаблон (в git, без значений)
.credentials.md учётные данные

Машинные:

Файл Назначение
index.yaml манифест компонента: class, deps, meta

4. КОМПОНЕНТЫ И МОДУЛИ

Два формата для двух сущностей:

Сущность Формат Пример
Компонент (уровень 1) {имя}/ architect/, library/
Модуль (есть lifecycle) @{тип}-{имя}/ @biz-lideravto/
Модуль (нет lifecycle) @{имя}.{тип}/ @ozon.api/

Проект — @{тип}-{имя}/

Имеет цель, стадию, команду. Lifecycle: IDEA → CLOSED.

Тип Что Пример
org Организация, холдинг @org-pirotehnika/
biz Коммерческое направление @biz-lideravto/
it IT-система @it-lideravto-drupal/
ops Операции / процессы @ops-logistics/
hr HR / команда @hr-onboarding/
fin Финансы @fin-budget/
mkt Маркетинг @mkt-seo/
rd Исследование @rd-catalog-ai/
phys Физический объект @phys-office/

Модуль — @{имя}.{тип}/

Единица кода без lifecycle. Только README.md.

@ozon.api/        OZON API коннектор
@mp1.service/     сервис маркетплейсов
@telegram.bot/    Telegram бот

Анти-паттерны

❌  @biz_lideravto/    — подчёркивание
❌  @Biz-Lideravto/    — заглавные буквы
❌  @lideravto/        — нет типа
❌  @ozon-api/         — модуль с дефисом (должно быть @ozon.api/)

✅  @biz-lideravto/
✅  @it-site-lideravto-ru/
✅  @ozon.api/
✅  @mp1.service/

5. ТРАНСЛИТЕРАЦИЯ

Правило Русский Транслит
х → h техника tehnika
ж → zh журнал zhurnal
ч → ch чат chat
й → j майор major
Пример Лидер Авто lideravto
Пример Пиротехника pirotehnika

6. РОЛИ ФАЙЛОВ (суффикс)

Суффикс Статус Назначение
(нет) active финальный документ
.draft wip черновик в работе
.idea wip сырая идея
.ai active файл для AI-агента
.tpl planned шаблон-заготовка 
find . -name "*.draft.md"   # все черновики
find . -name "*.ai.md"      # файлы AI-агентов
find . -name "AI.md"        # определения агентов

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