sfera-new/CLAUDE.md

# СИСТЕМНЫЕ ПРАВИЛА ДЛЯ CLAUDE CODE

## 📚 СТРУКТУРА ПРАВИЛ СИСТЕМЫ

### 🏗️ НОВАЯ АРХИТЕКТУРА ПРАВИЛ (АКТИВНАЯ):

- **`docs/`** - новая модульная архитектура правил, соответствующая структуре кода
- **`MODULAR_ARCHITECTURE_PATTERN.md`** - ОБЯЗАТЕЛЬНАЯ архитектура для новых компонентов >500 строк

### 📁 LEGACY ПРАВИЛА (АРХИВ):

- **`legacy-rules/rules-complete1.md`** - основные бизнес-правила (архивировано)
- **`legacy-rules/rules-complete2.md`** - система партнерства (архивировано)
- **`legacy-rules/workflow-catalog.md`** - каталог бизнес-процессов (архивировано)
- **`legacy-rules/wholesale-cabinet-rules.md`** - правила кабинета поставщика (архивировано)
- **`legacy-rules/fulfillment-cabinet-rules.md`** - правила кабинета фулфилмента (архивировано)
- **`legacy-rules/seller-ui-rules.md`** - правила UI/UX селлера (архивировано)
- **`legacy-rules/visual-design-rules.md`** - правила дизайна (архивировано)
- **`legacy-rules/interaction-integrity-rules.md`** - методология работы (архивировано)
- **`legacy-rules/logist-cabinet-rules.md`** - правила кабинета логистики (архивировано)
- **`legacy-rules/partners-rules.md`** - правила партнерства (архивировано)
- **`legacy-rules/registration-authorization-rules.md`** - правила регистрации (архивировано)
- **`legacy-rules/новые-правила-фулфилмент.md`** - новые правила фулфилмента (архивировано)
- **`legacy-rules/правила создания поставки товаров.md`** - правила поставок (архивировано)
- **`legacy-rules/backups/`** - бэкапы и вспомогательные файлы (архивировано)

### Автоматическая активация правил:

- Упоминание "поставщик", "wholesale", "/warehouse", "/supplier-orders" → legacy-rules/wholesale-cabinet-rules.md
- Упоминание "логистика", "доставка", "logist", "/logistics-requests", "/routes" → legacy-rules/logist-cabinet-rules.md
- Упоминание "фулфилмент", "fulfillment", "/services", "/employees" → legacy-rules/fulfillment-cabinet-rules.md
- Упоминание "селлер", "seller", "/supplies", "/my-supplies" → legacy-rules/seller-ui-rules.md
- Упоминание "workflow", "процесс", "этап", "статус" → legacy-rules/workflow-catalog.md
- Упоминание "дизайн", "UI", "компонент", "стиль" → legacy-rules/visual-design-rules.md
- Упоминание "компонент", "создание", "dashboard", ">500 строк", "архитектура" → MODULAR_ARCHITECTURE_PATTERN.md

## 🛑 ЗАПРЕТ ПРЕДПОЛОЖЕНИЙ

**КРИТИЧЕСКИ ВАЖНО:** При любой неоднозначности в запросе - ОСТАНОВИТЬСЯ немедленно и уточнить.

### ОБЯЗАТЕЛЬНЫЙ АЛГОРИТМ ПРИ НЕОДНОЗНАЧНОСТИ:

1. **СТОП-СИГНАЛ**: Если можно понять запрос двумя или более способами
2. **НЕМЕДЛЕННАЯ ОСТАНОВКА**: Прекратить любые действия
3. **ОБЯЗАТЕЛЬНЫЙ ВОПРОС**: "Не уверен. Уточните, пожалуйста:"
4. **ПЕРЕЧИСЛИТЬ ВАРИАНТЫ**: Показать все возможные понимания
5. **ДОЖДАТЬСЯ ОТВЕТА**: Не предпринимать действий до получения четкого указания

### ПРИМЕРЫ СТОП-СИГНАЛОВ:

- Упоминание "таблица поставщика" - КАКАЯ именно таблица? В каком файле?
- "Удали колонку" - ИЗ КАКОЙ таблицы? Какой компонент?
- "Исправь ошибку" - КАКУЮ ошибку? В каком файле?
- "Добавь функцию" - В КАКОЙ файл? Какая именно функция?

### ЗАПРЕЩЕННЫЕ ФРАЗЫ:

❌ "Возможно, вы имеете в виду..."
❌ "Скорее всего, нужно..."  
❌ "Попробую в этом файле..."
❌ "Наверное, это..."

### ОБЯЗАТЕЛЬНЫЕ ФРАЗЫ:

✅ "Не уверен. Уточните, пожалуйста:"
✅ "Какой именно файл/компонент?"
✅ "Вы имеете в виду X или Y?"
✅ "Правильно ли я понимаю, что..."

### НАКАЗАНИЕ ЗА НАРУШЕНИЕ:

- Откат ВСЕХ изменений через комментарии
- Полная остановка работы до получения уточнений
- Начало заново с правильных вопросов

## 🚨 ПЕРЕХОД К НОВОЙ АРХИТЕКТУРЕ ПРАВИЛ

**ВАЖНО:** Система правил реорганизована для соответствия архитектуре кода:

- **СТАРЫЕ ПРАВИЛА** перемещены в `legacy-rules/` для сохранения истории
- **НОВАЯ СТРУКТУРА** в папке `docs/` соответствует слоям архитектуры кода
- Постепенный переход от legacy к новой модульной структуре

❌ **НЕ СУЩЕСТВУЕТ:**

- development-checklist.md (удален)
- rules.md (удален)
- rules1.md (удален)
- rules2.md (удален)
- CLAUDE.md устаревших версий

## 🎯 WORKFLOW РАЗРАБОТКИ

### ⚠️ СТОП-СИГНАЛЫ (когда ОБЯЗАТЕЛЬНО спрашивать):

- Запрос содержит слова: "удали", "убери", "забудь", "не делай", "откати" (уточнить на сколько действий)
- Можно понять задачу несколькими способами
- Изменения затрагивают критические части системы
- Есть сомнения в интерпретации требований

### Обязательный порядок действий:

1. **При необходимости прочитать `legacy-rules/rules-complete1.md`** - для справки по бизнес-правилам
2. **Читать `legacy-rules/rules-complete2.md`** - при работе с партнерством/контрагентами
3. **Следовать правилам взаимодействия** - см. [legacy-rules/interaction-integrity-rules.md](./legacy-rules/interaction-integrity-rules.md)
4. **Проверить специфичные правила кабинета** - если работа с конкретным типом организации
5. **Проверить архитектурные требования** - для компонентов >500 строк читать MODULAR_ARCHITECTURE_PATTERN.md
6. **Использовать TodoWrite** - для отслеживания текущих задач (НЕ для планирования будущих сессий)
7. **Следовать техническим правилам** - GraphQL, TypeScript, система партнерства
8. **Проверять реализацию** - соответствие правилам и архитектуре

## 📋 КЛЮЧЕВЫЕ ПРИНЦИПЫ

> ⚠️ **ВАЖНО**: Все детальные правила взаимодействия и поведенческие принципы перенесены в **[interaction-integrity-rules.md](./interaction-integrity-rules.md)**

### Основные принципы разработки:

1. **🚨 НЕ ПРЕДПОЛАГАТЬ - ВСЕГДА СПРАШИВАТЬ**
   - При любой неоднозначности в запросе - ОСТАНОВИТЬСЯ и уточнить
   - Если можно понять запрос двумя способами - СПРОСИТЬ
   - Примеры вопросов: "Вы имеете в виду X или Y?", "Уточните, пожалуйста..."
   - ЛУЧШЕ ЛИШНИЙ РАЗ СПРОСИТЬ, ЧЕМ СДЕЛАТЬ НЕ ТО
2. **ПРОВЕРЯТЬ СХЕМЫ** - GraphQL и Prisma должны соответствовать коду
3. **СЛЕДОВАТЬ WORKFLOW** - не нарушать последовательность статусов
4. **ДОКУМЕНТИРОВАТЬ** - обновлять legacy-rules/rules-complete1.md/rules-complete2.md при решениях проблем

### ⚡ Принципы качества кода:

- **Качество кода важнее скорости** - лучше потратить время на правильное решение
- **Pre-commit hooks существуют для защиты проекта** - никогда не обходить их
- **Исправлять ошибки, а не обходить их** - каждая ошибка ESLint должна быть исправлена
- **Обход проверок создает технический долг** - `--no-verify` использовать только в крайних случаях
- **Профессиональный подход к конфигурации** - точная настройка инструментов, не "заметание под ковер"

### 🔍 ПРАВИЛО ИССЛЕДОВАНИЯ КОДА (КРИТИЧЕСКИ ВАЖНО):

**МАНТРА**: _"Код не лжет. Читай код, а не догадывайся."_

#### **ОБЯЗАТЕЛЬНЫЙ АЛГОРИТМ**:

1. **ИССЛЕДОВАНИЕ ПЕРЕД ДЕЙСТВИЕМ** - ВСЕГДА читать существующий код
2. **НЕ ПРЕДПОЛАГАТЬ** - только факты из кода, никаких догадок
3. **ИСПОЛЬЗОВАТЬ ИНСТРУМЕНТЫ**: `Read`, `Grep`, `Glob` для изучения кода
4. **ПОСЛЕДОВАТЕЛЬНОСТЬ**: Найти → Прочитать → Понять → Решить → Проверить

#### **СТОП-СИГНАЛЫ**:

- ❌ Если предлагаю решение без чтения кода - **ОСТАНОВИТЬСЯ!**
- ❌ Фразы типа "попробуй это", "возможно", "наверное" - **ЗАПРЕЩЕНЫ!**
- ✅ Каждое предложение должно начинаться: "Я нашел в коде..."

#### **ЗАПРЕЩЕНО**:

- Придумывать варианты без изучения кода
- Предполагать структуру CSS/JS без чтения файлов
- Советовать изменения без обоснования из реального кода

### 📏 ПРАВИЛО РАСЧЕТА РАЗМЕРОВ И ОТСТУПОВ:

#### **ФОРМУЛА РАСЧЕТА КОНТЕЙНЕРОВ**:

```
Высота контейнера = Высота контента + отступ сверху + отступ снизу
```

#### **ОБЯЗАТЕЛЬНЫЙ ПРОЦЕСС**:

1. **ВСЕГДА рассчитывать точную высоту** вместо произвольных значений
2. **Учитывать ВСЕ отступы** (padding, margin) в общей формуле
3. **Проверять визуальный результат** vs теоретический расчет
4. **НЕ полагаться только на анализ кода** - важно видеть реальный результат

#### **ПРИМЕР ИЗ ПРАКТИКИ**:

- Карточка 164px + отступы по 16px = контейнер 196px
- НЕ ставить высоту "на глазок" или произвольно

#### **ЗАПРЕЩЕНО В РАЗМЕРАХ**:

- Устанавливать размеры без математического обоснования
- Игнорировать отступы в расчетах
- Предполагать результат без проверки

> 📋 **Подробные правила**: см. разделы 1.2-1.3 в [interaction-integrity-rules.md](./interaction-integrity-rules.md#12--принципы-качества-кода)

### Правила взаимодействия (кратко):

- **Двухэтапный процесс**: Планирование → Одобрение → Выполнение
- **Неизменность планов**: согласованные планы нельзя менять без разрешения
- **Честность и прозрачность**: открыто сообщать о неопределенностях
- **Протоколы по сложности**: для каждого типа задач свой подход

## 🔧 КОМАНДЫ ПРОВЕРКИ КОДА

### Обязательные команды после изменений:

```bash
# TypeScript проверка типов
npm run typecheck

# Проверка линтером
npm run lint

# Запуск тестов
npm test

# Dev сервер для проверки работы
npm run dev
```

> ⚠️ **ВАЖНО**: Всегда выполнять эти команды перед завершением задачи!

## 🔄 КОМАНДЫ ОТКАТА

### Откат через комментарии:

**Основная команда:**

```
"откати [описание] через комментарии"
```

**Примеры:**

- `"откати центрирование поиска через комментарии"`
- `"откати изменения кнопки через комментарии"`
- `"откати новую логику через комментарии"`

**Дополнительные команды:**

- `"очисти комментарии"` - удалить закомментированные варианты
- `"переключи на вариант 2"` - активировать закомментированный код
- `"покажи варианты"` - показать доступные варианты

> 📖 **Подробнее**: см. раздел 6.4 в `legacy-rules/interaction-integrity-rules.md`

## 💾 РАБОТА С КОНТЕКСТОМ

### Файлы для сохранения контекста:

- **`current-session.md`** - текущая сессия работы (активные задачи, решения, контекст)
- **`CLAUDE.md`** - системные правила и команды (этот файл)
- **TodoWrite инструмент** - для отслеживания текущих задач в рамках сессии

### При потере контекста:

1. **Первым делом прочитать**: `current-session.md`
2. **Проверить статус задач**: через TodoWrite
3. **Восстановить контекст**: из истории изменений в current-session.md

### Рекомендации для длинных сессий:

- Обновлять `current-session.md` после каждой важной задачи
- Фиксировать принятые решения и обоснования
- Документировать обнаруженные проблемы и их решения
- Использовать `--resume` флаг для продолжения сессий

## 🚨 НАПОМИНАНИЕ

**Этот файл служит для корректной работы system-reminder'ов. Все детальные правила находятся в `legacy-rules/rules-complete1.md` и `legacy-rules/rules-complete2.md`! Новая архитектура правил в папке `docs/` находится в разработке.**