architect/_archive/2025-11-26-cleanup/system-docs/specifications/naming-rules.md

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

Версия: 1.0.0
Дата: 2025-11-19

Общие принципы

1. Самодокументирование

Идея: Имя должно объяснять назначение

Правильно:
- create_product() — понятно что делает
- user_authentication.py — понятно что внутри

Неправильно:
- func1() — не понятно
- utils.py — слишком общее

2. Консистентность

Идея: Одинаковые вещи называть одинаково

Правильно:
- create_product(), create_order(), create_user()

Неправильно:
- create_product(), add_order(), new_user()

3. Длина

Оптимально:
- Папки: 1-2 слова
- Файлы: 1-3 слова
- Функции: 2-4 слова
- Переменные: 1-2 слова

Папки

Корневые папки workspace

Формат: lowercase, одно слово

system/
platform/
projects/
infra/
components/
library/
templates/
scripts/

Исключения:
- platform-v2/ — с суффиксом версии

Папки проектов

Формат: lowercase, дефисы для разделения

projects/marketplace/
projects/pim-drupal/
projects/platform-v2/

Правило: {name}/

Папки инфраструктуры

Формат: prefix + дефис + name

infra/@infra-dev-pro/        # @ для VPS
infra/@remote-beget-kondurov/ # @ для remote
infra/infra-yandex-disk/      # без @ для облака

Префиксы:
- @infra- — VPS серверы
- @remote- — Shared hosting
- infra- — Cloud storage, services

Папки внутри проекта

Стандартные имена:

design/          # Проектирование
management/      # Управление
infrastructure/  # Инфра (опц)
solution/        # Решение

Не менять! Эти имена стандартны для всех проектов.

Файлы

Корневые файлы

Формат: ЗАГЛАВНЫЕ

CLAUDE.md
README.md
LOCATION.md

Почему: Сразу видно важность файла

Документы

Формат: ЗАГЛАВНЫЕ или kebab-case

CONCEPT.md                    # ЗАГЛАВНЫЕ — важные концепции
ARCHITECTURE.md               # ЗАГЛАВНЫЕ — важная архитектура
file-formats.md               # kebab-case — спецификации
naming-rules.md               # kebab-case — детали

Код Python

Формат: snake_case

crud.py
user_auth.py
database_helper.py

Конфигурации

Формат: kebab-case.{ext}

config.yaml
index.yaml
structure.yaml

Тесты

Формат: test_{name}.py

test_products.py
test_orders.py
test_auth.py

Переменные и функции

Python

Переменные: snake_case

user_name = "John"
product_list = []
order_count = 10

Функции: snake_case

def create_product():
    pass

def get_user_by_id(user_id):
    pass

Классы: PascalCase

class ProductManager:
    pass

class OzonAPI:
    pass

Константы: SCREAMING_SNAKE_CASE

MAX_RETRY = 3
API_BASE_URL = "https://api.example.com"

JavaScript

Переменные: camelCase

let userName = "John";
const productList = [];

Функции: camelCase

function createProduct() {}
function getUserById(userId) {}

Классы: PascalCase

class ProductManager {}
class OzonAPI {}

Константы: SCREAMING_SNAKE_CASE

const MAX_RETRY = 3;
const API_BASE_URL = "https://api.example.com";

Git

Ветки

Формат: {type}/{description}

feature/export-to-excel
bugfix/date-formatting
release/v1.1.0
hotfix/critical-bug

Типы:
- feature/ — новая функция
- bugfix/ — исправление бага
- release/ — релиз
- hotfix/ — критичное исправление

Commits

Формат: {type}: {description}

feat: add export to Excel
fix: correct date formatting
docs: update README
refactor: simplify auth logic
test: add product tests
chore: update dependencies

Типы:
- feat: — новая функция
- fix: — исправление бага
- docs: — документация
- refactor: — рефакторинг
- test: — тесты
- chore: — рутина (dependencies, etc.)

Tags

Формат: v{MAJOR}.{MINOR}.{PATCH}

v1.0.0
v1.1.0
v2.0.0

Специальные префиксы

@ — Инфраструктура

Использование: Для ссылок на инфраструктуру

infrastructure: "@infra-dev-pro"

В путях:

infra/@infra-dev-pro/
infra/@remote-beget-kondurov/

_ — Приватные

Использование: Приватные функции/переменные

def _internal_helper():  # приватная функция
    pass

_cache = {}  # приватная переменная

__ — Очень приватные

Использование: Name mangling в Python

class Example:
    def __private_method(self):  # очень приватный метод
        pass

Суффиксы

.ai.md — Для AI

Использование: Файлы только для AI агентов

system/orchestrator.ai.md
system/claude-code.ai.md

.template.* — Шаблоны

Использование: Шаблоны для генерации

templates/project/CLAUDE.template.md
templates/project/README.template.md

.tmp — Временные

Использование: Временные файлы

cache.tmp
processing.tmp

Правило: Добавить в .gitignore

Архивы

Папки

Формат: {YYYY-MM-DD}-{name}-old

archive/2025-11-09-marketplace-old/
archive/2025-10-15-projector-v1/

Файлы

Формат: {name}DRAFT.md или {name}_archived{date}.md

ARCHITECTURE_v2_DRAFT.md
config_archived_2025-11-09.yaml

Символические ссылки

Версии

Формат: @{version}

@latest → v2.0.0
@stable → v1.5.2
@v1     → v1.9.3

Типы

Формат: @{type}

@current  → текущая версия
@previous → предыдущая версия
@next     → следующая версия

Примеры полных путей

Проект APPLICATION

projects/marketplace/
├── CLAUDE.md
├── README.md
├── index.yaml
├── design/
│   ├── PROJECT.md
│   └── spec.md
├── management/
│   └── README.md
└── solution/
    └── code/
        ├── modules/
        │   └── products/
        │       └── crud.py
        └── tests/
            └── test_products.py

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

infra/@infra-dev-pro/
└── config.yaml

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

infra/infra-new-server/
├── config.yaml
├── CLAUDE.md
├── design/
│   └── plan.md
└── solution/
    └── terraform/
        ├── main.tf
        └── variables.tf

Что НЕ делать

❌ Пробелы в именах:

my project/        # ПЛОХО
my-project/        # ХОРОШО

❌ Кириллица в именах папок/файлов:

проект/            # ПЛОХО
project/           # ХОРОШО

❌ Слишком длинные имена:

this_is_a_very_long_function_name_that_does_something_with_products()  # ПЛОХО
process_products()  # ХОРОШО

❌ Аббревиатуры без контекста:

usrmgr.py          # ПЛОХО (что это?)
user_manager.py    # ХОРОШО

❌ Смешивание стилей:

getUserName()      # JavaScript style
get_user_age()     # Python style
# ПЛОХО — выбрать один стиль

Следующий документ

Назад: file-formats.md — форматы файлов

Следующий: ../reference/glossary.md — глоссарий