architect/_archive/2025-11-cleanup/NAMING_QUICK_REFERENCE.md

БЫСТРАЯ СПРАВКА: Именование и Структура

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

Полная документация: platform/docs/NAMING_STANDARD.md


🎯 ОСНОВНЫЕ ПРИНЦИПЫ

  1. Максимально использовать штатное Claude Code
  2. Единообразие > Гибкость (все проекты одинаковые)
  3. Явное > Неявное (говорящие имена)

📂 ШТАТНОЕ VS НАШЕ

Штатные механизмы Claude Code

✅ .claude/settings.json    ← Конфигурация (ВСЕГДА есть)
✅ .claude/sessions/        ← История (автоматически)
✅ Автоматическое чтение claude.md при входе в папку

Наши расширения Platform v1

✅ CLAUDE.md               ← Точка входа (документация)
✅ *.ai.md, *.ai.yaml      ← AI-специфичные файлы
✅ INFRA.yaml              ← Метаданные инфраструктуры
✅ PROJECT.yaml            ← Метаданные проекта
✅ .claude/current-mode.txt ← Текущий режим
✅ .claude/patches/         ← Заплатки

📝 ПРАВИЛА ИМЕНОВАНИЯ

Регистр символов

Что Формат Примеры
Важные документы ЗАГЛАВНЫЕ.md README.md, CLAUDE.md, PROJECT.md
Метаданные ЗАГЛАВНЫЕ.yaml INFRA.yaml, PROJECT.yaml
AI-файлы name.ai.md terminal.ai.md, rules.ai.md
Шаблоны name.template.md readme.template.md
Код lowercase app.py, module.js
Конфиги lowercase settings.json, config.yaml

Зарезервированные имена

CLAUDE.md          ← Точка входа для Claude Code (ОБЯЗАТЕЛЬНО)
PROJECT.md         ← Описание проекта (в design/)
INFRA.yaml         ← Метаданные инфраструктуры (в корне infra-проекта)
README.md          ← Документация для людей
CHANGELOG.md       ← История изменений
TODO.md            ← Список задач
ARCHITECTURE.md    ← Архитектура (в design/)
DEPLOYMENT.md      ← Развёртывание (в infrastructure/)

🏗️ СТАНДАРТНАЯ СТРУКТУРА

Для приложения (projects/)

projects/{name}/
├── CLAUDE.md              ← ОБЯЗАТЕЛЬНО
├── .claude/
│   ├── settings.json     ← ОБЯЗАТЕЛЬНО
│   └── sessions/         ← Автоматически
├── design/
│   └── PROJECT.md        ← ОБЯЗАТЕЛЬНО
├── management/
│   └── README.md         ← ОБЯЗАТЕЛЬНО
└── solution/
    └── {code}

Для инфраструктуры (infra/)

infra/{name}/
├── INFRA.yaml            ← ОБЯЗАТЕЛЬНО
├── CLAUDE.md             ← ОБЯЗАТЕЛЬНО
├── .claude/
│   └── settings.json     ← ОБЯЗАТЕЛЬНО
├── design/
│   └── PROJECT.md        ← ОБЯЗАТЕЛЬНО
├── infrastructure/
│   └── CONNECTION.md     ← ОБЯЗАТЕЛЬНО
└── management/
    └── README.md         ← ОБЯЗАТЕЛЬНО

📋 СТРУКТУРА .claude/

Минимальная (только штатное)

.claude/
├── settings.json       ОБЯЗАТЕЛЬНО
└── sessions/           Автоматически

Стандартная (штатное + Platform v1)

.claude/
├── settings.json            Конфигурация
├── sessions/                История
├── current-mode.txt         Текущий режим
├── last-session.md          Восстановление
└── docs/                    Доп. документация

🔧 settings.json

Минимальный

{
  "workspace": {
    "name": "project-name",
    "version": "1.0.0",
    "location": "/path/to/project"
  }
}

Расширенный (с Platform v1)

{
  "workspace": {
    "name": "project-name",
    "version": "1.0.0",
    "location": "/path/to/project"
  },
  "project": {
    "type": "application | infrastructure | platform",
    "role": "production | development | control-plane",
    "status": "active | development | inactive"
  },
  "security": {
    "dangerous_commands": ["rm -rf", "DROP DATABASE"],
    "confirm_for_production": true
  }
}

✅ ЧЕКЛИСТ ДЛЯ НОВОГО ПРОЕКТА

Приложение

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


🚀 БЫСТРОЕ СОЗДАНИЕ

Новое приложение

cd /opt/claude-workspace/projects/
mkdir my-app && cd my-app

# Создать минимальную структуру
mkdir -p .claude design management solution

# settings.json
cat > .claude/settings.json << EOF
{
  "workspace": {
    "name": "my-app",
    "version": "1.0.0",
    "location": "$PWD"
  },
  "project": {
    "type": "application",
    "status": "development"
  }
}
EOF

# CLAUDE.md
echo "# My App - Документация для Claude Code" > CLAUDE.md

# PROJECT.md
echo "# Проект: My App" > design/PROJECT.md

# README.md
echo "# My App - Управление" > management/README.md

Новая инфраструктура

cd /opt/claude-workspace/infra/
mkdir @infra-prod && cd @infra-prod

# Создать минимальную структуру
mkdir -p .claude design infrastructure management

# settings.json
cat > .claude/settings.json << EOF
{
  "workspace": {
    "name": "@infra-prod",
    "version": "1.0.0",
    "location": "$PWD"
  },
  "project": {
    "type": "infrastructure",
    "role": "production",
    "status": "active"
  }
}
EOF

# INFRA.yaml
cat > INFRA.yaml << EOF
infrastructure:
  name: "Production Server"
  type: vps
  ip: "1.2.3.4"
projects: []
version: "1.0.0"
EOF

# CLAUDE.md
echo "# @infra-prod - Документация для Claude Code" > CLAUDE.md

# PROJECT.md
echo "# Инфраструктура: Production Server" > design/PROJECT.md

# CONNECTION.md
echo "# Connection" > infrastructure/CONNECTION.md

# README.md
echo "# Production Server - Управление" > management/README.md

📚 ДОКУМЕНТАЦИЯ

Быстрая справка: Этот файл
Полные правила: platform/docs/NAMING_STANDARD.md (1600+ строк)
Инфраструктура: INFRA_QUICK_START.md, platform/docs/INFRA_RULES.md


❓ FAQ

Q: CLAUDE.md или claude.md?
A: CLAUDE.md (ЗАГЛАВНЫМИ) - для единообразия с README.md

Q: Где должен быть .claude/?
A: В корне КАЖДОГО проекта/инфраструктуры

Q: Обязателен ли settings.json?
A: ДА! Это единственный обязательный файл в .claude/

Q: Можно ли свою структуру папок?
A: НЕТ. Всегда: design/, infrastructure/, management/, solution/

Q: *.ai.md для чего?
A: Для файлов ТОЛЬКО для AI (не для людей)


Версия: 1.0.0
Дата: 2025-11-17
Статус: ✅ Активный стандарт