Дата: 2026-02-02
Статус: Draft для обсуждения
КОНТЕКСТБЛОК — это ПОЛНЫЙ ПРОМПТ для кодера (AI или человек).
Принцип:
Контекстблок содержит ВСЁ необходимое:
→ Кодер читает контекстблок
→ Кодер начинает кодить
→ Кодер НЕ задаёт вопросов (всё уже есть)
Содержит:
1. ✅ ЧТО делать (контекст, требования)
2. ✅ КАК делать (инструкции, примеры)
3. ✅ Что ЗАПРЕЩЕНО делать (constraints)
4. ✅ Входы/выходы (интерфейсы)
5. ✅ Критерии готовности (когда done)
Результат: Self-contained промпт без необходимости задавать вопросы
1. ПЛАНИРОВЩИК создаёт контекстблок:
└─→ planning/context.md (ЧТО делать)
└─→ planning/constraints.md (Что ЗАПРЕЩЕНО)
└─→ planning/requirements.md (Требования)
└─→ planning/interfaces.md (Входы/выходы)
└─→ dev/INSTRUCTIONS.md (КАК делать)
└─→ dev/examples.md (Примеры)
2. КОДЕР читает контекстблок:
└─→ Понимает ЧТО делать (context.md)
└─→ Понимает что НЕЛЬЗЯ (constraints.md)
└─→ Понимает требования (requirements.md)
└─→ Понимает интерфейсы (interfaces.md)
└─→ Следует инструкциям (INSTRUCTIONS.md)
└─→ Смотрит примеры (examples.md)
3. КОДЕР пишет код:
└─→ dev/src/
4. КОДЕР проверяет по критериям:
└─→ planning/criteria.md
Команда кодеру (AI):
Прочитай контекстблок projects/lideravto/dev/import/
и реализуй согласно dev/INSTRUCTIONS.md
Что делает кодер:
1. Читает planning/context.md → понимает что импорт BAZON, 13K товаров
2. Читает planning/constraints.md → понимает что НЕ трогать CS-Cart core
3. Читает planning/requirements.md → понимает FR-1, FR-2, FR-3, FR-4
4. Читает planning/interfaces.md → понимает формат CSV, структуру БД
5. Читает dev/INSTRUCTIONS.md → следует шагам 1-8
6. Читает dev/examples.md → смотрит как должно работать
7. Пишет код в dev/src/
8. Проверяет по planning/criteria.md
Вопросов НЕ задаёт — всё уже в контекстблоке!
контекстблок/
├── CLAUDE.md ← Метаданные, описание
├── CACHE.yaml ← Зависимости (что загрузить)
│
├── planning/ ← ВСЁ ДЛЯ КОДИНГА
│ ├── context.md ← 1. ГЛАВНАЯ ИНФОРМАЦИЯ
│ ├── constraints.md ← 2. ЗАПРЕТЫ (обязательно!)
│ ├── requirements.md ← 3. Требования (FR, NFR)
│ ├── interfaces.md ← 4. Интерфейсы (API, данные)
│ ├── blocks.md ← 5. Декомпозиция
│ └── criteria.md ← 6. Критерии готовности
│
├── dev/ ← РАЗРАБОТКА
│ ├── INSTRUCTIONS.md ← Пошаговые инструкции
│ ├── examples.md ← Примеры использования
│ └── src/ ← Код
│
├── testing/ ← Тесты
├── deploy/ ← Результаты
│
└── [под-блоки]/ ← Вложенные контекстблоки
Назначение: Ответить на главные вопросы перед кодингом
Обязательные секции:
## ЧТО
**Задача:** [Краткое описание в одном предложении]
**Проблема:** [Какую проблему решаем]
**Решение:** [Что предлагается]
## ЗАЧЕМ
**Бизнес-цель:** [Зачем это бизнесу]
**Польза:** [Кому и какая польза]
**Приоритет:** [Критично / Важно / Желательно]
## КОНТЕКСТ
**Откуда задача:**
- [Источник задачи]
**Что известно:**
- [Факт 1]
- [Факт 2]
**Что НЕ известно:**
- [Вопрос 1]
- [Вопрос 2]
**Предположения:**
- [Предположение 1]
- [Предположение 2]
# КОНТЕКСТ: Импорт товаров
## ЧТО
**Задача:** Импорт 13,347 товаров из BAZON в CS-Cart
**Проблема:** Ручной импорт невозможен (13K товаров)
**Решение:** Автоматический импорт через Advanced Import + обработка
## ЗАЧЕМ
**Бизнес-цель:** Наполнить каталог товарами для запуска магазина
**Польза:**
- Покупатели видят актуальный каталог
- Цены обновляются автоматически
- Остатки синхронизируются
**Приоритет:** Критично (блокирует запуск)
## КОНТЕКСТ
**Откуда задача:**
- Требование для запуска lideravto.ru
**Что известно:**
- Источник: BAZON CSV (битрикс формат)
- Количество: 13,347 товаров
- Обновление: 3 типа обменов (Full/New/Prices)
- CS-Cart: Advanced Import встроен
**Что НЕ известно:**
- Как обрабатывать дубли OEM?
- Какие категории создавать автоматически?
**Предположения:**
- OEM уникальны (можно использовать как ключ)
- Категории 4 уровня (Запчасти/Марка/Серия/Узел)
Назначение: ОБЯЗАТЕЛЬНО указать что НЕЛЬЗЯ делать
Принцип каскадности: Если изменить что-то наверху → каскадом идёт вниз → всё ломается.
Обязательные секции:
## ❌ ЗАПРЕЩЕНО ТРОГАТЬ
### Не изменять
**CS-Cart Core:**
- ❌ НЕ изменять файлы app/functions/
- ❌ НЕ изменять файлы app/controllers/
- ❌ НЕ изменять схему БД core таблиц
**Существующие модули:**
- ❌ НЕ изменять код сторонних аддонов
- ❌ НЕ перезаписывать хуки других модулей
**Данные:**
- ❌ НЕ удалять существующие товары
- ❌ НЕ изменять product_id вручную
- ❌ НЕ трогать таблицы cscart_users, cscart_orders
## ❌ ЗАПРЕЩЁННЫЕ ДЕЙСТВИЯ
**Код:**
- ❌ НЕ использовать глобальные переменные
- ❌ НЕ хардкодить пути (использовать Registry::get('config.dir'))
- ❌ НЕ дублировать код (использовать функции)
- ❌ НЕ писать SQL напрямую (использовать db_query)
**Данные:**
- ❌ НЕ хардкодить URLs (брать из data/MASTER.md)
- ❌ НЕ хранить credentials в коде (использовать .env)
- ❌ НЕ писать логи в /tmp (использовать var/log/)
**Архитектура:**
- ❌ НЕ создавать новые таблицы без префикса addon_
- ❌ НЕ обходить хуки (использовать штатные)
- ❌ НЕ блокировать другие модули
## 📍 ГРАНИЦЫ (SCOPE)
**Что МОЖНО изменять:**
- ✅ Создавать таблицы с префиксом lider_*
- ✅ Добавлять Product Features
- ✅ Создавать категории
- ✅ Регистрировать хуки в схемах
**Что НЕ входит в задачу:**
- ❌ Синхронизация заказов (другая задача)
- ❌ Обработка изображений (другой блок)
- ❌ SEO оптимизация (другой блок)
**Зависимости:**
- ⚠️ НЕ блокировать работу catalog блока
- ⚠️ НЕ конфликтовать с seo блоком
## 🌊 КАСКАДНЫЕ ОГРАНИЧЕНИЯ
**Уровень 1: Платформа (НЕ трогать)**
- CS-Cart Core
- PHP 7.4+
- MySQL 5.7+
- Nginx
**Уровень 2: Приложение (Осторожно)**
- Схема БД приложения
- Существующие модули
- Шаблоны темы
**Уровень 3: Модуль (МОЖНО)**
- Наши модули (lider_*)
- Наши хуки
- Наши данные
**Правило:** Изменения только на своём уровне. Не подниматься выше.
# ЗАПРЕТЫ: Импорт товаров
## ❌ ЗАПРЕЩЕНО ТРОГАТЬ
**CS-Cart Core:**
- ❌ app/functions/fn.catalog.php
- ❌ app/controllers/backend/products.php
- ❌ cscart_products (схема)
- ❌ cscart_categories (схема)
**Advanced Import:**
- ❌ Код Advanced Import аддона
- ❌ Схемы импорта (кроме products.post.php)
**Данные:**
- ❌ Существующие товары (если есть)
- ❌ Ручные категории
## ❌ ЗАПРЕЩЁННЫЕ ДЕЙСТВИЯ
**Код:**
- ❌ НЕ парсить CSV напрямую (использовать Advanced Import)
- ❌ НЕ создавать собственный парсер
- ❌ НЕ дублировать логику Advanced Import
**Данные:**
- ❌ НЕ хардкодить BAZON URL (брать из data/MASTER.md)
- ❌ НЕ хранить маппинг в коде (использовать БД/YAML)
**Модули:**
- ❌ НЕ создавать зависимость от сторонних аддонов
## 📍 ГРАНИЦЫ
**Что МОЖНО:**
- ✅ Регистрировать хук products.post.php
- ✅ Создавать Product Features (oem, node, aggregate)
- ✅ Создавать категории 4 уровня
- ✅ Обрабатывать данные в хуке
**Что НЕ входит:**
- ❌ Обработка изображений (будет в catalog блоке)
- ❌ SEO URL (будет в seo блоке)
- ❌ Вариации товаров (будет в catalog блоке)
## 🌊 КАСКАДНЫЕ ОГРАНИЧЕНИЯ
**L1: CS-Cart Core** — НЕ трогать
**L2: Advanced Import** — использовать как есть
**L3: Хук products.post.php** — МОЖНО изменять
**L4: Библиотека lib/** — МОЖНО создавать
Назначение: Функциональные и нефункциональные требования
# ТРЕБОВАНИЯ
## Функциональные (FR)
### FR-1: [Название]
**Описание:** [Что должно работать]
**Приёмка:**
- [ ] Критерий 1
- [ ] Критерий 2
**Приоритет:** Must have / Should have / Nice to have
---
### FR-2: [Название]
...
## Нефункциональные (NFR)
### NFR-1: Performance
- Импорт 13,347 товаров < 30 минут
- Одновременная работа с другими модулями
### NFR-2: Scalability
- Поддержка до 50,000 товаров
- Поддержка до 10 источников данных
### NFR-3: Maintainability
- Модульная архитектура (lib/)
- Понятные имена функций
- Логирование ошибок
Назначение: API, форматы данных, точки интеграции
# ИНТЕРФЕЙСЫ
## Входные данные
### Источник: BAZON CSV
**URL:** (см. data/MASTER.md)
**Формат:**
```csv
Код товара;Название;Цена;Наличие;Категория;...
20398547;Амортизатор;5000;10;VOLVO/4-FH/Кабина;...
Поля:
- Код товара (OEM) — string, уникальный
- Название — string
- Цена — float
- Наличие — int
- Категория — string (путь через /)
Таблицы:
- cscart_products — товары (штатная)
- cscart_categories — категории (штатная)
- cscart_product_features_values — значения характеристик
Product Features:
- oem — OEM код (20398547)
- cross — Кросс-коды (20-398-547, 20 398 547)
- compatibility — Совместимость (VOLVO 4-FH)
- node — Узел (Кабина)
- aggregate — Агрегат (не заполняется)
Функции (для catalog блока):
- lider_import_get_product_by_oem($oem) — получить товар по OEM
- lider_import_get_categories_tree() — получить дерево категорий
---
## 5. planning/blocks.md — Декомпозиция
**Назначение:** Разбивка на подзадачи с оценкой времени
```markdown
# ДЕКОМПОЗИЦИЯ
## Подблоки
### Блок 1: Setup infrastructure (30 мин)
**Что:** Создать Product Features, корневую категорию, Import Presets
**Deliverables:**
- lider_setup модуль
- 6 Product Features
- Корневая категория "Запчасти"
- 3 Import Presets
---
### Блок 2: Normalize data (45 мин)
**Что:** Нормализация марки, OEM, цены
**Deliverables:**
- lib/normalize.php
- Функция normalize_brand()
- Функция normalize_oem()
- Функция normalize_price()
...
## Общая оценка
**Всего:** 3.5 часа
**Разбивка:**
- Setup: 30 мин
- Normalize: 45 мин
- Node mapping: 30 мин
- Categories: 45 мин
- Products: 30 мин
- Images: 15 мин
- Hook: 15 мин
- Preset: 10 мин
# КРИТЕРИИ ГОТОВНОСТИ
## MVP готов когда:
- ✅ lider_setup установлен
- ✅ lider_import установлен
- ✅ Импорт 100 товаров работает без ошибок
- ✅ Категории 4 уровня создаются
- ✅ Features заполняются (oem, node, compatibility)
- ✅ Изображения загружаются
## Production готов когда:
- ✅ MVP работает
- ✅ Полный импорт 13,347 товаров успешен
- ✅ 3 обмена протестированы (Full, New, Prices)
- ✅ Cron настроен
- ✅ Логирование работает
- ✅ Обработка ошибок есть
## Проверка
**Команды:**
```bash
# Проверить установку
ls -la cscart/app/addons/lider_setup/
ls -la cscart/app/addons/lider_import/
# Запустить тест импорт
php cli_import.php --preset=7 --limit=100
# Проверить результат
mysql -e "SELECT COUNT(*) FROM cscart_products WHERE company_id=1"
---
## 7. dev/INSTRUCTIONS.md — Пошаговые инструкции
```markdown
# ИНСТРУКЦИИ: Импорт товаров
## Шаг 1: Создать lider_setup модуль (30 мин)
### 1.1. Создать структуру
```bash
mkdir -p cscart/app/addons/lider_setup
cd cscart/app/addons/lider_setup
<?xml version="1.0"?>
<addon scheme="4.0">
<id>lider_setup</id>
<name>Lider Setup</name>
...
</addon>
...
...
---
## 8. dev/examples.md — Примеры
```markdown
# ПРИМЕРЫ ИСПОЛЬЗОВАНИЯ
## Пример 1: Импорт одного товара
**Входные данные:**
```csv
20398547;Амортизатор кабины передний;5000;10;VOLVO/4-FH/Кабина;https://image.jpg
Ожидаемый результат:
Товар:
- product_code: 20398547
- product: Амортизатор кабины передний
- price: 5000
- amount: 10
Категория:
- Запчасти → VOLVO → 4-FH → Кабина (4 уровня)
Features:
- oem: 20398547
- cross: 20-398-547, 20 398 547
- compatibility: VOLVO 4-FH
- node: Кабина
Изображение:
- Загружено с https://image.jpg
Входные данные:
20398547;Амортизатор кабины передний;5000;10;...
20398547;Амортизатор кабины передний;5500;5;... ← Дубль (другая цена)
Ожидаемое поведение:
- Найден существующий товар по OEM
- Обновлена цена: 5500
- Обновлён остаток: 5
- Дублирование НЕ создано
---
## Минимальный контекстблок
**Даже если мало информации — создаём минимум:**
block/
├── CLAUDE.md
└── planning/
├── context.md ← ЧТО, ЗАЧЕМ, КОНТЕКСТ
└── constraints.md ← ЗАПРЕТЫ (обязательно!)
**Потом дополняем:**
1. requirements.md
2. interfaces.md
3. blocks.md
4. criteria.md
5. dev/INSTRUCTIONS.md
6. dev/examples.md
---
## Правила работы
### Порядок создания
### Обязательный чеклист перед кодингом
- [ ] planning/context.md создан (ЧТО, ЗАЧЕМ, КОНТЕКСТ)
- [ ] planning/constraints.md создан (**ЗАПРЕТЫ ОБЯЗАТЕЛЬНЫ!**)
- [ ] planning/interfaces.md создан (входы, выходы, API)
- [ ] planning/requirements.md создан (FR, NFR)
- [ ] CACHE.yaml создан (зависимости указаны)
- [ ] dev/INSTRUCTIONS.md создан (пошаговые инструкции)
**Только после этого → кодинг!**
---
## Резюме
### Что обязательно должно быть в контекстблоке
1. ✅ **planning/context.md** — главная информация
2. ✅ **planning/constraints.md** — ЗАПРЕТЫ (обязательно!)
3. ✅ **planning/interfaces.md** — интерфейсы (API, данные)
4. ✅ **planning/requirements.md** — требования
5. ✅ **planning/blocks.md** — декомпозиция
6. ✅ **planning/criteria.md** — критерии готовности
7. ✅ **dev/INSTRUCTIONS.md** — пошаговые инструкции
8. ✅ **dev/examples.md** — примеры использования
9. ✅ **CACHE.yaml** — зависимости
### Почему ЗАПРЕТЫ обязательны?
**Принцип каскадности:**
- Изменение наверху → каскад вниз → всё ломается
- Нужны явные границы что трогать НЕЛЬЗЯ
- Защита от случайных изменений core/платформы
**Без запретов:**
- Разработчик может изменить CS-Cart core
- Может сломать другие модули
- Может создать несовместимость
**С запретами:**
- Явные границы изменений
- Защита каскадности
- Безопасная разработка
---
## КОНТЕКСТБЛОК КАК ПРОМПТ
### Формат передачи кодеру
**Вариант 1: Через Task tool**
```python
Task(
subagent_type="general-purpose",
model="sonnet",
prompt=f"""
Реализуй блок import согласно контекстблоку.
КОНТЕКСТБЛОК: projects/lideravto/dev/import/
ПРОЧИТАЙ В ПОРЯДКЕ:
1. planning/context.md → ЧТО делать
2. planning/constraints.md → Что ЗАПРЕЩЕНО
3. planning/requirements.md → Требования
4. planning/interfaces.md → Входы/выходы
5. dev/INSTRUCTIONS.md → Пошаговые инструкции
6. dev/examples.md → Примеры
РЕАЛИЗУЙ:
- Следуй INSTRUCTIONS.md пошагово
- Соблюдай ВСЕ ограничения из constraints.md
- Проверь по criteria.md когда готово
РЕЗУЛЬТАТ:
- Код в dev/src/
- Отчёт что сделано
"""
)
Вариант 2: Через команду
claude code --block=projects/lideravto/dev/import/
Вариант 3: Прямая команда
Реализуй import блок.
Контекстблок: projects/lideravto/dev/import/
Критерий качества контекстблока:
Кодер прочитал контекстблок
↓
Кодер начал кодить
↓
Кодер НЕ задал НИ ОДНОГО вопроса
↓
✅ Контекстблок ДОСТАТОЧНЫЙ
Если кодер задаёт вопросы:
- "А откуда брать данные?" → НЕТ в interfaces.md
- "А можно изменить эту таблицу?" → НЕТ в constraints.md
- "А как обрабатывать дубли?" → НЕТ в requirements.md или examples.md
- "А что делать дальше?" → НЕТ в INSTRUCTIONS.md
→ Контекстблок НЕДОСТАТОЧНЫЙ → Дополнить!
Стандартный промпт:
# ЗАДАЧА: Реализовать блок {название}
## КОНТЕКСТБЛОК
**Путь:** {projects/org/project/dev/block/}
## ПРОЧИТАЙ В ПОРЯДКЕ
1. **planning/context.md**
- ЧТО делаем
- ЗАЧЕМ делаем
- Что известно, что НЕ известно
2. **planning/constraints.md** ⚠️ ОБЯЗАТЕЛЬНО
- Что ЗАПРЕЩЕНО трогать
- Что ЗАПРЕЩЕНО делать
- Границы изменений
- Каскадные ограничения
3. **planning/requirements.md**
- Функциональные требования (FR-1, FR-2...)
- Нефункциональные требования (NFR)
4. **planning/interfaces.md**
- Входные данные (откуда, формат)
- Выходные данные (куда, формат)
- API для других блоков
- Зависимости
5. **planning/blocks.md**
- Декомпозиция на подблоки
- Оценка времени
6. **planning/criteria.md**
- Критерии готовности MVP
- Критерии готовности Production
- Команды для проверки
7. **dev/INSTRUCTIONS.md**
- Пошаговые инструкции
- Что делать на каждом шаге
8. **dev/examples.md**
- Примеры входных данных
- Примеры ожидаемых результатов
- Примеры граничных случаев
## ЗАДАНИЕ
1. Прочитай ВСЕ файлы выше
2. Реализуй согласно dev/INSTRUCTIONS.md
3. Соблюдай ВСЕ ограничения из constraints.md
4. Напиши код в dev/src/
5. Проверь по criteria.md
## ВАЖНО
- ❌ НЕ задавай вопросов — всё уже в контекстблоке
- ✅ Следуй INSTRUCTIONS.md пошагово
- ⚠️ ОБЯЗАТЕЛЬНО соблюдай constraints.md
- ✅ Проверяй по criteria.md после каждого шага
## РЕЗУЛЬТАТ
Отчёт:
- Что сделано (ссылки на файлы)
- Что работает (команды для проверки)
- Критерии выполнены (чеклист)
Чеклист:
ПЕРЕД передачей кодеру проверь:
□ planning/context.md
□ Есть ЧТО делаем
□ Есть ЗАЧЕМ делаем
□ Указано что известно
□ Указано что НЕ известно
□ planning/constraints.md ⚠️ КРИТИЧНО
□ Указано что ЗАПРЕЩЕНО трогать
□ Указано что ЗАПРЕЩЕНО делать
□ Указаны границы изменений
□ Указаны каскадные уровни
□ planning/requirements.md
□ Есть функциональные требования
□ Есть нефункциональные требования
□ Каждое требование имеет приёмку
□ planning/interfaces.md
□ Описаны входные данные (формат, источник)
□ Описаны выходные данные (формат, назначение)
□ Описан API (если есть)
□ Указаны зависимости
□ planning/blocks.md
□ Есть декомпозиция
□ Есть оценка времени каждого блока
□ planning/criteria.md
□ Указаны критерии MVP
□ Указаны критерии Production
□ Есть команды для проверки
□ dev/INSTRUCTIONS.md
□ Есть пошаговые инструкции
□ Каждый шаг понятен
□ Есть примеры команд/кода
□ dev/examples.md
□ Есть примеры входных данных
□ Есть примеры результатов
□ Есть примеры граничных случаев
□ CACHE.yaml
□ Указаны зависимости
□ Указаны пути к файлам
✅ ВСЁ ГОТОВО → Передаём кодеру
❌ ЧТО-ТО ПРОПУЩЕНО → Дополняем контекстблок
Проблема БЕЗ контекстблока:
Планировщик: "Сделай импорт"
Кодер: "Откуда данные?"
Планировщик: "Из BAZON"
Кодер: "Какой формат?"
Планировщик: "CSV"
Кодер: "Сколько товаров?"
...10 вопросов...
Решение С контекстблоком:
Планировщик: "Реализуй import/ контекстблок"
Кодер: [читает контекстблок]
Кодер: [кодит]
Кодер: "Готово"
Контекстблок = рецепт:
- Любой кодер может взять контекстблок
- Прочитать
- Реализовать
- Получить тот же результат
Можно передать нескольким кодерам:
Кодер 1: import/ контекстблок
Кодер 2: catalog/ контекстблок
Кодер 3: seo/ контекстблок
→ Работают параллельно
→ Не мешают друг другу (constraints.md определяет границы)
Контекстблок в git:
- История изменений требований
- Можно вернуться к старой версии
- Можно сравнить версии
Реализуй блок analytics/dashboard/
Контекстблок: projects/analytics/dev/dashboard/
Следуй INSTRUCTIONS.md.
Соблюдай constraints.md.
Проверяй по criteria.md.
Task(
subagent_type="general-purpose",
model="sonnet",
description="Реализовать import блок",
prompt="""
КОНТЕКСТБЛОК: projects/lideravto/dev/import/
АЛГОРИТМ:
1. Прочитай planning/ полностью
2. Проверь CACHE.yaml (загрузи зависимости)
3. Следуй dev/INSTRUCTIONS.md пошагово
4. После каждого шага проверяй criteria.md
5. Соблюдай ВСЕ ограничения constraints.md
ВАЖНО:
- НЕ задавай вопросов (всё в контекстблоке)
- НЕ пропускай шаги INSTRUCTIONS.md
- НЕ нарушай constraints.md
РЕЗУЛЬТАТ:
- Код в dev/src/
- Проверка по criteria.md
- Отчёт о выполнении
"""
)
Проверь реализацию блока import/
Контекстблок: projects/lideravto/dev/import/
Код: dev/src/
ПРОВЕРЬ:
1. Соответствие requirements.md
2. Соблюдение constraints.md
3. Соответствие interfaces.md
4. Соответствие INSTRUCTIONS.md
5. Выполнение criteria.md
ОТВЕТ:
- ✅ Что соответствует
- ❌ Что НЕ соответствует
- 💡 Рекомендации
Содержит ВСЁ для кодинга:
1. ЧТО делать (context.md)
2. Что ЗАПРЕЩЕНО (constraints.md)
3. Требования (requirements.md)
4. Интерфейсы (interfaces.md)
5. КАК делать (INSTRUCTIONS.md)
6. Примеры (examples.md)
7. Критерии готовности (criteria.md)
Результат:
- Кодер НЕ задаёт вопросов
- Кодер следует промпту
- Кодер получает предсказуемый результат
Формула:
Качественный контекстблок =
Полный промпт +
Все запреты +
Все примеры +
Пошаговые инструкции
Назначение: Инструкции как проверить что блок работает правильно
ОБЯЗАТЕЛЬНЫЙ файл! Контекстблок должен содержать не только КАК СОЗДАТЬ, но и КАК ПРОВЕРИТЬ.
# КАК ПРОВЕРИТЬ: Импорт товаров
## Быстрая проверка (2 минуты)
### 1. Проверить установку модулей
```bash
# Проверить что модули существуют
ls -la cscart/app/addons/lider_setup/
ls -la cscart/app/addons/lider_import/
# Проверить что модули активны
mysql -e "SELECT addon, status FROM cscart_addons WHERE addon LIKE 'lider_%'"
# Ожидаемый результат:
# lider_setup | A
# lider_import | A
mysql -e "SELECT feature_id, description FROM cscart_product_features WHERE description LIKE 'lider_%'"
# Ожидаемый результат (6 features):
# lider_oem
# lider_cross
# lider_compatibility
# lider_condition
# lider_aggregate
# lider_node
mysql -e "SELECT preset_id, preset FROM cscart_import_presets WHERE preset LIKE 'BAZON%'"
# Ожидаемый результат (3 preset):
# 6 | BAZON Full Import
# 7 | BAZON New Products
# 8 | BAZON Prices Update
# Запустить импорт с лимитом
cd cscart/
php admin.php --dispatch=exim.import --preset_id=7 --limit=100
# Ожидаемый результат:
# Imported: 100 products
# Created categories: ~15
# Errors: 0
# Посчитать импортированные товары
mysql -e "SELECT COUNT(*) FROM cscart_products WHERE company_id=1"
# Ожидаемый результат: 100
# Проверить что заполнены характеристики
mysql -e "
SELECT COUNT(DISTINCT product_id)
FROM cscart_product_features_values
WHERE feature_id IN (
SELECT feature_id FROM cscart_product_features
WHERE description LIKE 'lider_%'
)
"
# Ожидаемый результат: 100 (все товары имеют features)
# Проверить структуру категорий
mysql -e "
SELECT category_id, category, level
FROM cscart_categories
WHERE level IN (1,2,3,4)
ORDER BY id_path
LIMIT 20
"
# Ожидаемый результат:
# Запчасти (level 1)
# └─ VOLVO (level 2)
# └─ 4-FH (level 3)
# └─ Кабина (level 4)
# Посчитать товары с изображениями
mysql -e "
SELECT COUNT(DISTINCT object_id)
FROM cscart_images_links
WHERE object_type='product'
"
# Ожидаемый результат: >50 (минимум половина товаров)
# Проверить что файлы существуют
ls -la cscart/images/detailed/ | head -10
cd cscart/app/addons/lider_import/
php -r "
require 'lib/normalize.php';
// Тест normalize_brand
assert(normalize_brand('ВОЛЬВО') === 'VOLVO');
assert(normalize_brand('SCANIA') === 'SCANIA');
// Тест normalize_oem
assert(normalize_oem('20 398 547') === '20398547');
assert(normalize_oem('20-398-547') === '20398547');
echo 'Unit tests passed!';
"
# 1. Очистить существующие данные
mysql -e "TRUNCATE cscart_products"
# 2. Запустить FULL импорт
php admin.php --dispatch=exim.import --preset_id=6
# 3. Проверить количество
mysql -e "SELECT COUNT(*) FROM cscart_products"
# Ожидаемый результат: 13347 товаров
# 1. Запомнить текущую цену товара
PRICE_BEFORE=$(mysql -e "SELECT price FROM cscart_products WHERE product_code='20398547'")
# 2. Изменить цену в BAZON (вручную или мок)
# 3. Запустить PRICES импорт
php admin.php --dispatch=exim.import --preset_id=8
# 4. Проверить что цена обновилась
PRICE_AFTER=$(mysql -e "SELECT price FROM cscart_products WHERE product_code='20398547'")
# Ожидаемый результат: PRICE_AFTER != PRICE_BEFORE
# 1. Импортировать товар первый раз
# 2. Импортировать тот же товар с другими данными
# 3. Проверить что дубликат НЕ создан, товар обновлён
mysql -e "SELECT COUNT(*) FROM cscart_products WHERE product_code='20398547'"
# Ожидаемый результат: 1 (не 2!)
Зайти в админку: https://work.lideravto.ru/admin.php
Открыть сайт: https://work.lideravto.ru
# Засечь время FULL импорта
time php admin.php --dispatch=exim.import --preset_id=6
# Ожидаемый результат: < 30 минут
# Во время импорта проверить нагрузку
mysql -e "SHOW PROCESSLIST"
# Ожидаемый результат:
# - Нет долгих locked запросов
# - Нет table locks
Создать: testing/validate.sh
#!/bin/bash
set -e
echo "=== ПРОВЕРКА БЛОКА IMPORT ==="
# 1. Проверка модулей
echo "[1/10] Проверка модулей..."
test -d cscart/app/addons/lider_setup || exit 1
test -d cscart/app/addons/lider_import || exit 1
# 2. Проверка БД
echo "[2/10] Проверка Product Features..."
COUNT=$(mysql -sN -e "SELECT COUNT(*) FROM cscart_product_features WHERE description LIKE 'lider_%'")
test "$COUNT" -eq 6 || exit 1
# 3. Проверка Import Presets
echo "[3/10] Проверка Import Presets..."
COUNT=$(mysql -sN -e "SELECT COUNT(*) FROM cscart_import_presets WHERE preset LIKE 'BAZON%'")
test "$COUNT" -eq 3 || exit 1
# 4. Тестовый импорт
echo "[4/10] Тестовый импорт 10 товаров..."
php admin.php --dispatch=exim.import --preset_id=7 --limit=10 >/dev/null
# 5. Проверка товаров
echo "[5/10] Проверка импортированных товаров..."
COUNT=$(mysql -sN -e "SELECT COUNT(*) FROM cscart_products WHERE company_id=1")
test "$COUNT" -ge 10 || exit 1
# 6. Проверка категорий
echo "[6/10] Проверка категорий..."
COUNT=$(mysql -sN -e "SELECT COUNT(*) FROM cscart_categories WHERE level=4")
test "$COUNT" -ge 1 || exit 1
# 7. Проверка features
echo "[7/10] Проверка features..."
COUNT=$(mysql -sN -e "SELECT COUNT(DISTINCT product_id) FROM cscart_product_features_values")
test "$COUNT" -ge 10 || exit 1
# 8. Unit тесты
echo "[8/10] Unit тесты..."
# TODO: запустить unit тесты
# 9. Проверка логов
echo "[9/10] Проверка логов на ошибки..."
! grep -i "error\|exception" cscart/var/log/*.log 2>/dev/null || exit 1
# 10. Финальная проверка
echo "[10/10] Финальная проверка критериев..."
# Все критерии из criteria.md
echo "✅ ВСЕ ПРОВЕРКИ ПРОЙДЕНЫ"
Запуск:
bash testing/validate.sh
Блок считается ГОТОВЫМ когда:
Если хотя бы одна проверка НЕ прошла:
- ❌ Блок НЕ готов
- 🔧 Исправить проблему
- 🔄 Повторить проверку
---
## deploy/VALIDATION.md — Проверка деплоя
**Назначение:** Как проверить что блок корректно развёрнут в production
```markdown
# ВАЛИДАЦИЯ ДЕПЛОЯ: Импорт товаров
## Pre-deployment чеклист
**ПЕРЕД деплоем на production:**
- [ ] Все тесты пройдены на staging
- [ ] Бэкап БД создан
- [ ] Бэкап файлов создан
- [ ] Rollback план готов
## Deployment проверка
### 1. Smoke test (сразу после деплоя)
```bash
# Проверить что модули активны
ssh production "cd /path/to/cscart && \
mysql -e 'SELECT addon, status FROM cscart_addons WHERE addon LIKE \"lider_%\"'"
# Ожидаемый результат:
# lider_setup | A
# lider_import | A
# Запустить тестовый импорт 10 товаров
ssh production "cd /path/to/cscart && \
php admin.php --dispatch=exim.import --preset_id=7 --limit=10"
# Ожидаемый результат: Imported: 10, Errors: 0
Проверить в течение 1 часа:
Проверить на сайте:
Через 24 часа после деплоя:
Откатить деплой ЕСЛИ:
Команда отката:
bash ops/deploy/rollback.sh
---
## ПОЛНАЯ СТРУКТУРА с проверками
контекстблок/
├── CLAUDE.md
├── CACHE.yaml
│
├── planning/
│ ├── context.md ← ЧТО делать
│ ├── constraints.md ← Что ЗАПРЕЩЕНО ⚠️
│ ├── requirements.md ← Требования
│ ├── interfaces.md ← Интерфейсы
│ ├── blocks.md ← Декомпозиция
│ └── criteria.md ← ЧТО проверять
│
├── dev/
│ ├── INSTRUCTIONS.md ← КАК создать (пошагово)
│ ├── examples.md ← Примеры
│ └── src/ ← КОД
│
├── testing/ ← КАК проверить ⭐
│ ├── HOW_TO_TEST.md ← Как проверить (ОБЯЗАТЕЛЬНО!)
│ ├── test-plan.md ← План тестирования
│ ├── validate.sh ← Автопроверка
│ └── tests/ ← Автотесты
│ ├── unit/
│ ├── integration/
│ └── e2e/
│
└── deploy/
├── VALIDATION.md ← Проверка деплоя
└── README.md ← Как использовать
---
## ОБНОВЛЁННЫЙ ЧЕКЛИСТ
**Перед передачей кодеру:**
□ planning/context.md ✅
□ planning/constraints.md ✅ ⚠️
□ planning/requirements.md ✅
□ planning/interfaces.md ✅
□ planning/criteria.md ✅
□ dev/INSTRUCTIONS.md ✅
□ dev/examples.md ✅
□ testing/HOW_TO_TEST.md ✅ ⭐ НОВОЕ
□ deploy/VALIDATION.md ✅ ⭐ НОВОЕ
□ CACHE.yaml ✅
✅ ВСЁ ГОТОВО → Полный промпт (создание + проверка)
---
## РЕЗЮМЕ: Создание + Проверка
**КОНТЕКСТБЛОК = ПРОМПТ для:**
### 1. СОЗДАНИЯ блока
dev/INSTRUCTIONS.md:
Шаг 1: Создать X
Шаг 2: Создать Y
Шаг 3: Создать Z
### 2. ПРОВЕРКИ блока
testing/HOW_TO_TEST.md:
Тест 1: Проверить X
Тест 2: Проверить Y
Тест 3: Проверить Z
### 3. ВАЛИДАЦИИ деплоя
deploy/VALIDATION.md:
Pre-deploy: Чеклист
Smoke test: Быстрая проверка
Post-deploy: Мониторинг
Rollback: Критерии отката
**Формула:**
Полный контекстблок =
КАК создать (INSTRUCTIONS.md) +
КАК проверить (HOW_TO_TEST.md) +
КАК валидировать (VALIDATION.md) +
Что ЗАПРЕЩЕНО (constraints.md)
```
СЛЕДУЮЩИЙ ШАГ:
1. Создать для import блока:
- testing/HOW_TO_TEST.md
- testing/validate.sh
- deploy/VALIDATION.md
2. Применить к catalog и seo блокам