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
4. Проверить специфичные правила кабинета - если работа с конкретным типом организации
5. Проверить архитектурные требования - для компонентов >500 строк читать MODULAR_ARCHITECTURE_PATTERN.md
6. Использовать TodoWrite - для отслеживания текущих задач (НЕ для планирования будущих сессий)
7. Следовать техническим правилам - GraphQL, TypeScript, система партнерства
8. Проверять реализацию - соответствие правилам и архитектуре

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

⚠️ ВАЖНО: Все детальные правила взаимодействия и поведенческие принципы перенесены в 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

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

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

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

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

# 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/ находится в разработке.