architect/arh/analysis/2026-02-02-project-structure/CONTEXT_BLOCK.md

КОНТЕКСТБЛОК = ПРОМПТ ДЛЯ КОДЕРА

Дата: 2026-02-02
Статус: Draft для обсуждения


Ключевая идея

КОНТЕКСТБЛОК — это ПОЛНЫЙ ПРОМПТ для кодера (AI или человек).

Принцип:

Контекстблок содержит ВСЁ необходимое:
  → Кодер читает контекстблок
  → Кодер начинает кодить
  → Кодер НЕ задаёт вопросов (всё уже есть)

Содержит:
1. ✅ ЧТО делать (контекст, требования)
2. ✅ КАК делать (инструкции, примеры)
3. ✅ Что ЗАПРЕЩЕНО делать (constraints)
4. ✅ Входы/выходы (интерфейсы)
5. ✅ Критерии готовности (когда done)

Результат: Self-contained промпт без необходимости задавать вопросы


Как это работает

Workflow

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. planning/context.md — ГЛАВНАЯ ИНФОРМАЦИЯ

Назначение: Ответить на главные вопросы перед кодингом

Обязательные секции:

Что делаем?

## ЧТО

**Задача:** [Краткое описание в одном предложении]

**Проблема:** [Какую проблему решаем]

**Решение:** [Что предлагается]

Зачем?

## ЗАЧЕМ

**Бизнес-цель:** [Зачем это бизнесу]

**Польза:** [Кому и какая польза]

**Приоритет:** [Критично / Важно / Желательно]

Контекст

## КОНТЕКСТ

**Откуда задача:**
- [Источник задачи]

**Что известно:**
- [Факт 1]
- [Факт 2]

**Что НЕ известно:**
- [Вопрос 1]
- [Вопрос 2]

**Предположения:**
- [Предположение 1]
- [Предположение 2]

Пример (import)

# КОНТЕКСТ: Импорт товаров

## ЧТО

**Задача:** Импорт 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 уровня (Запчасти/Марка/Серия/Узел)

2. planning/constraints.md — ЗАПРЕТЫ ⚠️

Назначение: ОБЯЗАТЕЛЬНО указать что НЕЛЬЗЯ делать

Принцип каскадности: Если изменить что-то наверху → каскадом идёт вниз → всё ломается.

Обязательные секции:

Что НЕЛЬЗЯ трогать

## ❌ ЗАПРЕЩЕНО ТРОГАТЬ

### Не изменять

**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_*)
- Наши хуки
- Наши данные

**Правило:** Изменения только на своём уровне. Не подниматься выше.

Пример (import)

# ЗАПРЕТЫ: Импорт товаров

## ❌ ЗАПРЕЩЕНО ТРОГАТЬ

**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/** — МОЖНО создавать

3. planning/requirements.md — Требования

Назначение: Функциональные и нефункциональные требования

# ТРЕБОВАНИЯ

## Функциональные (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/)
- Понятные имена функций
- Логирование ошибок

4. planning/interfaces.md — Интерфейсы

Назначение: 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 — Агрегат (не заполняется)

API для других блоков

Функции (для 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 мин

6. planning/criteria.md — Критерии готовности

# КРИТЕРИИ ГОТОВНОСТИ

## 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

1.2. Создать addon.xml

<?xml version="1.0"?>
<addon scheme="4.0">
    <id>lider_setup</id>
    <name>Lider Setup</name>
    ...
</addon>

1.3. Создать func.php

...

Шаг 2: Создать lider_import модуль (2 часа)

2.1. Создать lib/normalize.php

...

---

## 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

Пример 2: Обработка дубля

Входные данные:

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

---

## Правила работы

### Порядок создания
  1. planning/context.md ← Сначала главная информация
  2. planning/constraints.md ← Потом запреты (ОБЯЗАТЕЛЬНО!)
  3. planning/interfaces.md ← Входы/выходы
  4. planning/requirements.md ← Требования
  5. planning/blocks.md ← Декомпозиция
  6. planning/criteria.md ← Критерии
  7. dev/INSTRUCTIONS.md ← Инструкции
  8. dev/examples.md ← Примеры
  9. dev/src/ ← КОД (только после всего этого!)
### Обязательный чеклист перед кодингом

- [ ] 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
   Указаны зависимости
   Указаны пути к файлам

 ВСЁ ГОТОВО  Передаём кодеру
 ЧТО-ТО ПРОПУЩЕНО  Дополняем контекстблок

ПРЕИМУЩЕСТВА ПОДХОДА

1. Кодер не задаёт вопросов

Проблема БЕЗ контекстблока:

Планировщик: "Сделай импорт"
Кодер: "Откуда данные?"
Планировщик: "Из BAZON"
Кодер: "Какой формат?"
Планировщик: "CSV"
Кодер: "Сколько товаров?"
...10 вопросов...

Решение С контекстблоком:

Планировщик: "Реализуй import/ контекстблок"
Кодер: [читает контекстблок]
Кодер: [кодит]
Кодер: "Готово"

2. Воспроизводимость

Контекстблок = рецепт:
- Любой кодер может взять контекстблок
- Прочитать
- Реализовать
- Получить тот же результат


3. Параллелизм

Можно передать нескольким кодерам:

Кодер 1: import/ контекстблок
Кодер 2: catalog/ контекстблок
Кодер 3: seo/ контекстблок

 Работают параллельно
 Не мешают друг другу (constraints.md определяет границы)

4. Версионность

Контекстблок в git:
- История изменений требований
- Можно вернуться к старой версии
- Можно сравнить версии


ПРИМЕРЫ ПРОМПТОВ

Пример 1: Простая задача

Реализуй блок analytics/dashboard/

Контекстблок: projects/analytics/dev/dashboard/

Следуй INSTRUCTIONS.md.
Соблюдай constraints.md.
Проверяй по criteria.md.

Пример 2: Сложная задача с Sub-агентом

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
- Отчёт о выполнении
"""
)

Пример 3: Code Review

Проверь реализацию блока 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)

Результат:
- Кодер НЕ задаёт вопросов
- Кодер следует промпту
- Кодер получает предсказуемый результат

Формула:

Качественный контекстблок =
  Полный промпт +
  Все запреты +
  Все примеры +
  Пошаговые инструкции


КАК ПРОВЕРИТЬ: testing/HOW_TO_TEST.md

Назначение: Инструкции как проверить что блок работает правильно

ОБЯЗАТЕЛЬНЫЙ файл! Контекстблок должен содержать не только КАК СОЗДАТЬ, но и КАК ПРОВЕРИТЬ.

Структура HOW_TO_TEST.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

2. Проверить Product Features

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

3. Проверить Import Presets

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

Полная проверка (10 минут)

4. Тестовый импорт (100 товаров)

# Запустить импорт с лимитом
cd cscart/
php admin.php --dispatch=exim.import --preset_id=7 --limit=100

# Ожидаемый результат:
# Imported: 100 products
# Created categories: ~15
# Errors: 0

5. Проверить товары в БД

# Посчитать импортированные товары
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)

6. Проверить категории

# Проверить структуру категорий
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)

7. Проверить изображения

# Посчитать товары с изображениями
mysql -e "
  SELECT COUNT(DISTINCT object_id)
  FROM cscart_images_links
  WHERE object_type='product'
"

# Ожидаемый результат: >50 (минимум половина товаров)

# Проверить что файлы существуют
ls -la cscart/images/detailed/ | head -10

Unit тесты (если есть)

8. Тест нормализации

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!';
"

E2E тесты (сценарии)

9. Сценарий: Полный импорт

# 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 товаров

10. Сценарий: Обновление цен

# 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

11. Сценарий: Обработка дубля

# 1. Импортировать товар первый раз
# 2. Импортировать тот же товар с другими данными
# 3. Проверить что дубликат НЕ создан, товар обновлён

mysql -e "SELECT COUNT(*) FROM cscart_products WHERE product_code='20398547'"

# Ожидаемый результат: 1 (не 2!)

Manual тесты (чеклист)

12. Проверка в админке CS-Cart

Зайти в админку: https://work.lideravto.ru/admin.php

13. Проверка на сайте

Открыть сайт: https://work.lideravto.ru


Performance тесты

14. Время импорта

# Засечь время FULL импорта
time php admin.php --dispatch=exim.import --preset_id=6

# Ожидаемый результат: < 30 минут

15. Нагрузка на БД

# Во время импорта проверить нагрузку
mysql -e "SHOW PROCESSLIST"

# Ожидаемый результат:
# - Нет долгих locked запросов
# - Нет table locks

Автоматизированная проверка

16. Скрипт полной проверки

Создать: 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

2. Функциональная проверка

# Запустить тестовый импорт 10 товаров
ssh production "cd /path/to/cscart && \
  php admin.php --dispatch=exim.import --preset_id=7 --limit=10"

# Ожидаемый результат: Imported: 10, Errors: 0

3. Мониторинг

Проверить в течение 1 часа:

4. Бизнес-проверка

Проверить на сайте:

Post-deployment

Через 24 часа после деплоя:

Rollback критерии

Откатить деплой ЕСЛИ:

Команда отката:

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 блокам