type: standard
aspect: naming
title: "Стандарт именования файлов"
version: 1.0.0
date: 2026-02-19
status: active

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

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

ФОРМУЛА

[aspect]-[object]-[detail].md

Части:
- aspect — аспект/папка (1 слово)
- object — объект описания (1-2 слова)
- detail — детализация (1-3 слова, опционально)

РЕГИСТР И РАЗДЕЛИТЕЛИ

Регистр

Lowercase (маленькие буквы) для всех файлов:

✅ typology-project-overview.md
✅ format-file-types.md
✅ naming-code-imports.md

❌ Typology-Project-Overview.md      (не PascalCase)
❌ TYPOLOGY-PROJECT-OVERVIEW.md      (не UPPERCASE)
❌ typologyProjectOverview.md        (не camelCase)

Исключения (UPPERCASE):
- README.md
- CLAUDE.md
- CHANGELOG.md
- INDEX.md
- PROJECT.md (в бизнес-проектах)
- ARCHITECTURE.md (в IT-проектах)

Разделители

Дефис - для разделения:

✅ typology-project-types.md         (дефис)
❌ typology_project_types.md         (подчёркивание)
❌ typology.project.types.md         (точка)

Правило: Дефис используется:
- Между частями формулы: aspect-object-detail
- Внутри составных слов: file-types, code-imports

ЧАСТИ ФОРМУЛЫ

1. Aspect (аспект)

9 фиксированных значений:

Aspect	Описание	Вопрос	Примеры
`typology`	Типизация, классификация	ЧТО это?	project, entity, document
`structure`	Структура, организация	КАК УСТРОЕНО?	workspace, project, hierarchy
`format`	Форматы	КАК ВЫГЛЯДИТ?	markdown, data, code
`naming`	Именование	КАК НАЗЫВАТЬ?	database, files, projects
`lifecycle`	Жизненный цикл	КАК ЖИВЁТ?	project, code, document
`policy`	Политики, правила	ЧТО МОЖНО/НЕЛЬЗЯ?	security, backup, rollback
`process`	Процессы	КАК ДЕЛАТЬ?	deployment, development
`operation`	Операции	КАКИЕ ДЕЙСТВИЯ?	resource-check, cleanup
`guidance`	Руководства	КАК ИСПОЛЬЗОВАТЬ?	architect, coder

2. Object (объект)

1-2 слова, существительное в единственном числе:

Простые объекты (1 слово):

project
entity
document
workspace
database
code

Составные объекты (2 слова через дефис):

file-types                 ← типы файлов
code-imports               ← импорты в коде
security-credentials       ← учётные данные
resource-allocation        ← выделение ресурсов

3. Detail (детализация)

Опционально. 1-3 слова.

Типичные детализации:

Detail	Когда использовать
`overview`	Обзор, введение в объект
`structure`	Структура полей/компонентов
`types`	Типология, классификация
`classification`	Система классификации
`rules`	Правила работы
`examples`	Примеры использования
`guide`	Пошаговое руководство
`reference`	Справочник

Составные детализации:

commercial-business        ← коммерческие бизнес-типы
commercial-it              ← коммерческие IT-типы
field-structure            ← структура полей
type-taxonomy              ← таксономия типов

ДЛИНА НАЗВАНИЯ

Длина	Оценка	Действие
< 30 символов	✅ Отлично	Идеально
30-50 символов	✅ Хорошо	Приемлемо
50-70 символов	⚠️ Длинно	Попробовать сократить
> 70 символов	❌ Слишком	Обязательно сократить

Примеры

✅ format-markdown.md                           (17 символов)
✅ typology-project-types.md                    (28 символов)
✅ naming-database.md                           (17 символов)

⚠️ typology-project-classification.md           (37 символов)
⚠️ policy-security-credentials.md               (33 символа)

❌ typology-commercial-business-project-types.md  (48 символов - длинно)

Как сокращать

Убрать лишние слова:

❌ typology-project-classification-system.md
✅ typology-project-classification.md

Использовать сокращения:

❌ documentation-generation-templates.md
✅ docs-generation-templates.md

Разбить на несколько файлов:

❌ commercial-business-and-it-project-types.md

✅ typology-project-commercial-business.md
✅ typology-project-commercial-it.md

ПОЛНЫЕ ПРИМЕРЫ

Typology (типология)

typology-project-overview.md              ← Что такое проект
typology-project-structure.md             ← Структура полей (9 вопросов)
typology-project-types.md                 ← Типы проектов
typology-project-classification.md        ← Система классификации
typology-project-commercial.md            ← Коммерческие типы

typology-entity-types.md                  ← Типы сущностей
typology-document-types.md                ← Типы документов
typology-artifact-classes.md              ← Классы артефактов
typology-service-types.md                 ← Типы сервисов
typology-role-types.md                    ← Типы ролей
typology-process-types.md                 ← Типы процессов

Structure (структура)

structure-workspace.md                    ← Структура workspace
structure-project.md                      ← Структура проекта
structure-hierarchy.md                    ← Иерархия уровней
structure-organization.md                 ← Структура организации
structure-components.md                   ← Компоненты платформы
structure-tree-representation.md          ← Визуализация дерева
structure-subprojects.md                  ← Подпроекты

Format (формат)

format-markdown.md                        ← Стандарт Markdown
format-data.md                            ← YAML, JSON, CSV, Excel
format-code.md                            ← Стиль кода
format-document.md                        ← Типы документов
format-file-types.md                      ← Классы файлов
format-notifications.md                   ← Формат уведомлений

Naming (именование)

naming-files.md                           ← Этот стандарт
naming-database.md                        ← Таблицы/поля БД
naming-projects.md                        ← Именование проектов
naming-code-imports.md                    ← Импорты в коде
naming-terminology.md                     ← Словарь терминов

Lifecycle (жизненный цикл)

lifecycle-project.md                      ← ЖЦ проекта
lifecycle-code.md                         ← ЖЦ кода
lifecycle-document.md                     ← ЖЦ документа
lifecycle-artifact.md                     ← ЖЦ артефакта
lifecycle-data.md                         ← ЖЦ данных

Policy (политики)

policy-security-credentials.md            ← Безопасность credentials
policy-backup.md                          ← Политика бэкапов
policy-rollback.md                        ← Откат изменений
policy-resource-allocation.md             ← Выделение ресурсов
policy-deployment.md                      ← Деплой на prod
policy-data.md                            ← Политика данных

Process (процессы)

process-deployment.md                     ← Процесс деплоя
process-development.md                    ← Процесс разработки
process-testing.md                        ← Процесс тестирования
process-backup.md                         ← Процесс бэкапа
process-monitoring.md                     ← Процесс мониторинга
process-documentation.md                  ← Процесс документирования

Operation (операции)

operation-resource-check.md               ← Проверка ресурсов
operation-cleanup.md                      ← Очистка диска
operation-monitoring.md                   ← Мониторинг системы
operation-disk-audit.md                   ← Аудит диска

Guidance (руководства)

guidance-architect.md                     ← Для архитектора
guidance-coder.md                         ← Для кодера
guidance-projector.md                     ← Для проектора
guidance-infra.md                         ← Для инфры
guidance-terminal.md                      ← Для терминала

guidance-project-creation.md              ← Создание проекта
guidance-business-to-it-flow.md           ← Бизнес → IT поток

СПЕЦИАЛЬНЫЕ ФАЙЛЫ

БЕЗ префикса аспекта

Служебные файлы (UPPERCASE):

Файл	Назначение	Расположение
`README.md`	Индекс папки, навигация	В каждой папке
`CLAUDE.md`	Инструкции для Claude	Корень проекта/папки
`CHANGELOG.md`	История изменений	Корень проекта
`INDEX.md`	Полный индекс документации	architect/

Конфиденциальные (с точкой):

Файл	Назначение	.gitignore
`.credentials.md`	Учётные данные	✅ Да
`.env`	Переменные окружения	✅ Да
`.env.example`	Шаблон переменных	❌ Нет

Проектные документы (UPPERCASE):

Для бизнес-проектов в projects/:

Файл	Назначение
`PROJECT.md`	Описание проекта (9 вопросов)
`ARCHITECTURE.md`	Архитектура решения
`DEPLOYMENT.md`	Инструкции по деплою
`TESTING.md`	Инструкции по тестированию

С префиксом аспекта

Стандарты и документация:

Все файлы в architect/standards/ используют префиксы:

typology-project-overview.md
structure-workspace.md
format-markdown.md
naming-files.md

СТРУКТУРА ПАПОК

architect/standards/
├── README.md                               ← Без префикса (служебный)
│
├── 1-structure/
│   ├── README.md                           ← Без префикса
│   ├── structure-workspace.md
│   ├── structure-project.md
│   └── structure-hierarchy.md
│
├── 5-format/
│   ├── README.md
│   ├── format-markdown.md
│   ├── format-data.md
│   └── format-code.md
│
├── 6-naming/
│   ├── README.md
│   ├── naming-files.md                     ← Этот стандарт
│   ├── naming-database.md
│   └── naming-projects.md
│
└── 7-typology/
    ├── README.md
    ├── typology-project-overview.md
    ├── typology-project-types.md
    └── typology-entity-types.md

ПРЕИМУЩЕСТВА СТАНДАРТА

1. Уникальность

Каждый файл имеет уникальное имя:

# Можно переместить без конфликтов
mv 7-typology/typology-project-types.md 5-format/

# Имя остаётся уникальным
ls *typology-project-types.md

2. Ясность

Из названия сразу понятно содержимое:

typology-project-commercial.md
    ↓         ↓          ↓
  аспект   объект   детализация

= Типология коммерческих проектов

3. Поиск

# Найти всё про проекты
ls *-project-*.md
find . -name "*-project-*.md"

# Найти всю типологию
ls typology-*.md

# Найти всё про базы данных
grep -r "naming-database" .

4. Сортировка

Автоматическая группировка:

format-code.md
format-data.md
format-markdown.md
naming-database.md
naming-files.md
naming-projects.md
typology-entity-types.md
typology-project-types.md

5. Git

История чистая и понятная:

git log --oneline typology-project-types.md

# Rename тоже отслеживается
git log --follow typology-project-types.md

МИГРАЦИЯ СУЩЕСТВУЮЩИХ ФАЙЛОВ

Алгоритм переименования

Шаг 1: Определить aspect

Файл в папке 7-typology/ → aspect = "typology"
Файл в папке 5-format/   → aspect = "format"

Шаг 2: Определить object

PROJECT.md           → object = "project"
ENTITY.md            → object = "entity"
FILE_TYPES.md        → object = "file-types"
CODE_IMPORTS.md      → object = "code-imports"

Шаг 3: Определить detail

PROJECT.md               → overview (базовое описание)
PROJECT_TYPES.md         → types (типизация)
PROJECT_CLASSIFIER.md    → classification (классификация)
COMMERCIAL_PROJECTS.md   → commercial (коммерческие типы)

Шаг 4: Собрать формулу

aspect-object-detail.md

typology-project-overview.md
typology-project-types.md
typology-project-classification.md
typology-project-commercial.md

Примеры миграции

Typology:

PROJECT.md                 → typology-project-overview.md
PROJECT_TYPES.md           → typology-project-types.md
PROJECT_CLASSIFIER.md      → typology-project-classification.md
COMMERCIAL_PROJECTS.md     → typology-project-commercial.md
ENTITY.md                  → typology-entity-types.md
DOCUMENT.md                → typology-document-types.md
ARTIFACT_CLASSES.md        → typology-artifact-classes.md
SERVICE.md                 → typology-service-types.md
ROLE.md                    → typology-role-types.md
PROCESS.md                 → typology-process-types.md

Format:

MARKDOWN.md                → format-markdown.md (уже есть)
DATA.md                    → format-data.md (уже есть)
CODE.md                    → format-code.md (уже есть)
DOCUMENT.md                → format-document.md (уже есть)
FILE_TYPES.md              → format-file-types.md (уже есть)
NOTIFICATIONS.md           → format-notifications.md (уже есть)

Structure:

WORKSPACE.md               → structure-workspace.md
PROJECT.md                 → structure-project.md
HIERARCHY.md               → structure-hierarchy.md
ORGANIZATION.md            → structure-organization.md
COMPONENTS.md              → structure-components.md

ВАЛИДАЦИЯ

Чеклист проверки названия

[ ] Все буквы lowercase (кроме специальных файлов)
[ ] Используются только дефисы - (не _ или .)
[ ] Формула соблюдена: aspect-object-detail.md
[ ] Aspect из списка 9 разрешённых
[ ] Object — существительное в единственном числе
[ ] Длина < 50 символов (рекомендуется)
[ ] Название понятно без открытия файла

Скрипт валидации

#!/bin/bash
# validate-filenames.sh

for file in architect/standards/**/*.md; do
  filename=$(basename "$file")

  # Пропустить специальные файлы
  if [[ "$filename" =~ ^(README|CLAUDE|CHANGELOG|INDEX)\.md$ ]]; then
    continue
  fi

  # Проверить lowercase
  if [[ "$filename" =~ [A-Z] ]]; then
    echo "❌ $file - содержит заглавные буквы"
  fi

  # Проверить формат
  if ! [[ "$filename" =~ ^[a-z]+-[a-z-]+\.md$ ]]; then
    echo "⚠️ $file - не соответствует формату aspect-object-detail.md"
  fi

  # Проверить длину
  length=${#filename}
  if (( length > 50 )); then
    echo "⚠️ $file - слишком длинное ($length символов)"
  fi
done

CHANGELOG

2026-02-19 — v1.0.0

Создан стандарт именования файлов
Формула: aspect-object-detail.md
9 аспектов, lowercase, дефисы
Специальные файлы и исключения
Примеры миграции

Версия: 1.0.0
Статус: active
Владелец: architect