architect/standards/3-process/process-code-prompt.md

type: standard
aspect: process
title: "СТАНДАРТ: CODE-PROMPT"
version: 1.0.0
date: 2026-02-19
status: active

СТАНДАРТ: CODE-PROMPT

Версия: 1.0.0
Дата: 2026-02-03
Статус: Active

КОНЦЕПЦИЯ

CODE-PROMPT = промежуточный слой между проектированием и кодом

Проблема

Проект содержит:
- PROJECT.md (описание)
- data/*.md (источники)
- standards/*.md (правила)
- solutions/*/*.md (решения)

Кодер: Что читать? Где что? Как связано?
→ Много вопросов, ошибки, переделки

Решение

CODE-PROMPT = агрегация всего необходимого в один промпт
- Что делать (из PROJECT.md)
- Данные (из data/)
- Запреты (из standards/)
- API (из других модулей)
→ Готовый промпт для кодера

Процесс

ПРОЕКТИРОВАНИЕ → CACHE → SPEC → CODE-PROMPT → КОДИРОВАНИЕ

СТРУКТУРА

Уровень проекта

project/
├── CACHE.yaml              ← Глобальный кеш проекта
│   - Хеши всех файлов
│   - Агрегированные данные
│   - Граф зависимостей
│
├── PROJECT.md
├── data/
│   └── MASTER.md
├── standards/
│   └── CS-CART.md
│
└── solutions/
    └── website/
        └── src/
            └── module/     ← IT модуль

Уровень модуля

module/
├── SPEC.yaml           ← Конфигурация
│   - Ссылки на CACHE
│   - Локальные данные
│   - Инструкции
│
├── CODE-PROMPT.md      ← Промпт для кодера
│   - Собранный текст
│   - Всё в одном месте
│
├── prompts/            ← Блоки (если большой)
│   ├── 1-block.md
│   └── 2-block.md
│
└── src/                ← Код
    └── lib/

ФАЙЛЫ

1. CACHE.yaml (глобальный)

Назначение: Состояние всего проекта

Структура:

version: 1.0
project: lideravto
updated: 2026-02-03T14:50:00

# Уровень 1: Хеши файлов
files:
  PROJECT.md:
    hash: sha256:abc123...
    size: 2048
    modified: 2026-02-01T10:00:00

  data/MASTER.md:
    hash: sha256:def456...
    size: 1024
    modified: 2026-02-01T09:00:00

  standards/CS-CART.md:
    hash: sha256:ghi789...
    size: 4096
    modified: 2026-01-15T14:00:00

# Уровень 2: Агрегированные данные
extracted:
  project:
    name: "lideravto"
    type: "e-commerce"
    description: "Разборка грузовиков"
    source: "PROJECT.md"

  data:
    bazon_url:
      value: "https://baz-on.ru/..."
      format: "CSV"
      source: "data/MASTER.md"
      section: "#bazon_url"

  standards:
    cs_cart:
      constraints:
        - "Не трогать CS-Cart Core"
        - "Использовать Advanced Import"
      source: "standards/CS-CART.md"
      section: "#constraints"

# Уровень 3: Граф зависимостей
dependencies:
  solutions/website/src/import/CODE-PROMPT.md:
    sources:
      - SPEC.yaml
    depends_on:
      - data/MASTER.md
      - standards/CS-CART.md

reverse_dependencies:
  data/MASTER.md:
    - solutions/website/src/import/CODE-PROMPT.md
    - solutions/website/src/catalog/CODE-PROMPT.md

В git: ✅ Да (история изменений проекта)

2. SPEC.yaml (модуль)

Назначение: Конфигурация модуля

Структура:

# SPEC.yaml - конфигурация модуля

task: "Импорт товаров из BAZON"
estimate: "3.5 часа"

# Ссылки на CACHE
data:
  source: "@CACHE#extracted.data.bazon_url"
  format: "@CACHE#extracted.data.bazon_format"
  count: 13347

# Ссылки на CACHE + локальные
constraints:
  platform: "@CACHE#extracted.standards.cs_cart.constraints"
  module:
    - "Не использовать глобальные переменные"
    - "Не парсить CSV напрямую"

# Ссылки на файлы
dependencies:
  - "@../catalog/API.md#get_category"
  - "@../../../standards/CS-CART.md"

# Инструкции
instructions:
  - "Создать lib/normalize.php"
  - "Создать lib/categories.php"
  - "Создать lib/features.php"

# Проверка
check:
  - "SELECT COUNT(*) FROM cscart_products = 13347"
  - "SELECT COUNT(*) FROM cscart_categories WHERE level=4"

Синтаксис ссылок:
- @CACHE#path.to.data - из глобального CACHE
- @../path/file.md - относительный путь к файлу
- @../path/file.md#section - секция файла

В git: ✅ Да (конфигурация модуля)

3. CODE-PROMPT.md (модуль)

Назначение: Готовый промпт для кодера

Структура:

# CODE-PROMPT: Импорт товаров

**Оценка:** 3.5 часа
**Блоки:** 8

---

## Задача

Импорт 13,347 товаров из BAZON в CS-Cart

**Зачем:**
- Наполнить каталог для запуска магазина
- Автоматическое обновление цен и остатков

---

## Данные

**Источник:**
URL: https://baz-on.ru/export/.../lideravtoplus-bitrix.csv
Формат: Битрикс CSV
Количество: 13,347 товаров

(из data/MASTER.md)

---

## Запреты

**Платформа (из standards/CS-CART.md):**
❌ Не трогать CS-Cart Core
❌ Не изменять схему БД
❌ Использовать Advanced Import

**Модуль:**
❌ Не использовать глобальные переменные
❌ Не парсить CSV напрямую

---

## API других модулей

**Каталог (из ../catalog/API.md):**
```php
lider_catalog_get_category($name)
lider_catalog_create_category($parent_id, $name)

Инструкции

1. Создать lib/normalize.php (45 мин)

Функции нормализации:
- normalize_brand() - ВОЛЬВО → VOLVO
- normalize_oem() - очистка артикула
- normalize_price() - цена в рубли

2. Создать lib/categories.php (45 мин)

4-уровневая категоризация:
- Уровень 1: Запчасти
- Уровень 2: Марка (VOLVO, SCANIA)
- Уровень 3: Серия (4-FH, 5-P)
- Уровень 4: Узел (Кабина, Двигатель)

3. Создать lib/features.php (30 мин)

Product Features:
- lider_oem
- lider_node
- lider_compatibility

Проверка

-- Количество товаров
SELECT COUNT(*) FROM cscart_products;
-- Ожидаемо: 13347

-- Категории 4 уровня
SELECT COUNT(*) FROM cscart_categories WHERE level=4;
-- Ожидаемо: >20

**В git:** ❌ Нет (.gitignore, генерируется)

**Почему не в git:**
- Генерируется автоматически из SPEC.yaml + CACHE
- Обновляется при изменении зависимостей
- Является кешем, не исходным кодом

---

### 4. prompts/ (блоки)

**Когда создавать:** CODE-PROMPT.md > 500 строк

**Структура:**

prompts/
├── 1-normalize.md ← Блок 1
├── 2-categories.md ← Блок 2
└── 3-features.md ← Блок 3

**Главный CODE-PROMPT.md:**
```markdown
# CODE-PROMPT: Импорт товаров

## Блоки

1. [Normalize](prompts/1-normalize.md) - Нормализация данных (45 мин)
2. [Categories](prompts/2-categories.md) - Создание категорий (45 мин)
3. [Features](prompts/3-features.md) - Характеристики (30 мин)

## Общие запреты
❌ Не трогать CS-Cart Core

Блок prompts/1-normalize.md:

# БЛОК 1: Normalize

## Задача
Нормализовать марку, OEM, цену

## Данные
(из главного CODE-PROMPT.md)

## Инструкции
Создать lib/normalize.php:

```php
function normalize_brand($brand) {
    $map = [
        'ВОЛЬВО' => 'VOLVO',
        'СКАНИЯ' => 'SCANIA',
    ];
    return $map[$brand] ?? $brand;
}

Проверка

assert(normalize_brand('ВОЛЬВО') === 'VOLVO');

**В git:** ❌ Нет (генерируются)

---

## ПРОЦЕСС

### 1. Проектирование

**Кто:** Проектор
**Что:** Создать структуру проекта

```bash
# Создать описание
vim PROJECT.md

# Создать источники данных
vim data/MASTER.md

# Определить стандарты
vim standards/CS-CART.md

2. Агрегация проекта

Кто: Проектор
Команда:

claude aggregate-project

Что делает:
1. Сканирует проект (все .md, .yaml файлы)
2. Вычисляет хеши (files)
3. Извлекает структурированные данные (extracted)
4. Строит граф зависимостей (dependencies)
5. Сохраняет CACHE.yaml

Результат:

✓ CACHE.yaml создан
  - 15 файлов отсканировано
  - 8 секций извлечено
  - 5 зависимостей найдено

3. Создание SPEC.yaml

Кто: Проектор
Что: Конфигурация модуля

vim solutions/website/src/import/SPEC.yaml

task: "Импорт товаров"
data:
  source: "@CACHE#extracted.data.bazon_url"
constraints:
  platform: "@CACHE#extracted.standards.cs_cart.constraints"
  module:
    - "Не использовать глобальные"
instructions:
  - "Создать lib/normalize.php"

Правило: Максимум ссылок @CACHE, минимум inline данных

4. Сборка CODE-PROMPT

Кто: Проектор
Команда:

claude build-prompt solutions/website/src/import/

Что делает:
1. Читает SPEC.yaml
2. Резолвит ссылки @CACHE (из памяти)
3. Резолвит ссылки @ к файлам (читает)
4. Собирает CODE-PROMPT.md
5. Обновляет зависимости в CACHE.yaml

Результат:

✓ CODE-PROMPT.md создан (450 строк)
  - 3 секции из CACHE
  - 2 файла прочитано
  - CACHE.yaml обновлён

5. Разбиение на блоки (опционально)

Когда: CODE-PROMPT.md > 500 строк
Команда:

claude split-prompt solutions/website/src/import/

Что делает:
1. Анализирует структуру CODE-PROMPT.md
2. Делит на блоки по секциям ## Инструкции
3. Создаёт prompts/*.md
4. Обновляет главный CODE-PROMPT.md (ссылки на блоки)

Результат:

✓ Создано 3 блока в prompts/
  - 1-normalize.md (150 строк)
  - 2-categories.md (180 строк)
  - 3-features.md (120 строк)
✓ CODE-PROMPT.md обновлён (навигация)

6. Кодирование

Кто: Кодер (AI/человек)
Что: Читает промпт, пишет код

# Читает промпт
cat solutions/website/src/import/CODE-PROMPT.md

# Или блоками
cat solutions/website/src/import/prompts/1-normalize.md
→ Пишет lib/normalize.php

cat solutions/website/src/import/prompts/2-categories.md
→ Пишет lib/categories.php

7. Обновление при изменениях

Триггер: Изменился файл зависимости

# Изменили данные
vim data/MASTER.md  # Новый URL

# Проверка актуальности
claude check-cache
→ ⚠ data/MASTER.md: hash изменился
→ ⚠ solutions/website/src/import/CODE-PROMPT.md: устарел

# Пересборка
claude rebuild-stale
→ Агрегация проекта (обновление CACHE)
→ Пересборка CODE-PROMPT.md
→ ✓ Актуально

Автоматизация (git hook):

# .git/hooks/pre-commit
#!/bin/bash
claude check-cache || claude rebuild-stale

КОМАНДЫ

claude aggregate-project

Назначение: Агрегация проекта в CACHE

Использование:

claude aggregate-project

Когда запускать:
- После создания/изменения PROJECT.md, data/, standards/
- Перед созданием нового модуля
- После изменения структуры проекта

claude build-prompt

Назначение: Сборка CODE-PROMPT из SPEC

Использование:

claude build-prompt solutions/website/src/import/

Что делает:
1. Читает SPEC.yaml
2. Резолвит ссылки из CACHE и файлов
3. Создаёт CODE-PROMPT.md
4. Обновляет CACHE (зависимости)

claude split-prompt

Назначение: Разбить CODE-PROMPT на блоки

Использование:

claude split-prompt solutions/website/src/import/

Когда использовать: CODE-PROMPT.md > 500 строк

claude check-cache

Назначение: Проверка актуальности

Использование:

claude check-cache

Результат:

✓ PROJECT.md (актуально)
✓ data/MASTER.md (актуально)
⚠ standards/CS-CART.md (изменён)
⚠ solutions/website/src/import/CODE-PROMPT.md (устарел)

claude rebuild-stale

Назначение: Пересборка устаревших промптов

Использование:

claude rebuild-stale

Что делает:
1. Находит изменённые файлы (по хешам)
2. Находит зависимые CODE-PROMPT.md (по графу)
3. Пересобирает каждый (aggregate + build-prompt)
4. Обновляет CACHE

ПРАВИЛА

1. Разделение ответственности

Роль Ответственность
Проектор Создать PROJECT, data, standards, SPEC.yaml
Система Агрегировать в CACHE, собрать CODE-PROMPT
Кодер Читать CODE-PROMPT, писать код

2. Именование

Файл Формат Пример
Проект PROJECT.md PROJECT.md
Кеш CACHE.yaml CACHE.yaml
Спецификация SPEC.yaml SPEC.yaml
Промпт CODE-PROMPT.md CODE-PROMPT.md
Блоки N-name.md 1-normalize.md

3. Ссылки

Синтаксис:
- @CACHE#extracted.data.bazon_url - из CACHE
- @../path/file.md - относительный путь
- @../path/file.md#section - секция файла

Резолвинг:
1. @CACHE#... → извлекается из CACHE.yaml (быстро)
2. @путь → читается файл (медленно, но точно)
3. #section → извлекается секция ## section

4. Размер промпта

Размер Действие
<500 строк Один CODE-PROMPT.md
500-1500 строк Разбить на 2-5 блоков
>1500 строк Пересмотреть декомпозицию (под-модули)

5. Git

Файл Git Почему
CACHE.yaml ✅ Да История состояния проекта
SPEC.yaml ✅ Да Конфигурация модуля
CODE-PROMPT.md ❌ Нет Генерируется (.gitignore)
prompts/*.md ❌ Нет Генерируются (.gitignore)

.gitignore:

CODE-PROMPT.md
prompts/

ПРИМЕРЫ

Пример 1: Маленький модуль (hook)

discount_hook/
├── SPEC.yaml           (50 строк)
├── CODE-PROMPT.md      (200 строк)
└── src/
    └── discount.php    (30 строк)

SPEC.yaml:

task: "Скидка 10% для оптовиков"
data:
  user_type: "W"
  discount: 10
constraints:
  - "Не трогать fn.cart.php"
instructions:
  - "Создать hook products.post.php"

Сборка:

claude build-prompt discount_hook/
→ CODE-PROMPT.md (200 строк)

Пример 2: Средний модуль (import)

import/
├── SPEC.yaml           (100 строк)
├── CODE-PROMPT.md      (450 строк)
└── src/
    └── lib/
        ├── normalize.php
        ├── categories.php
        └── features.php

SPEC.yaml:

task: "Импорт 13,347 товаров"
data:
  source: "@CACHE#extracted.data.bazon_url"
constraints:
  platform: "@CACHE#extracted.standards.cs_cart"
instructions:
  - "Создать lib/normalize.php"
  - "Создать lib/categories.php"
  - "Создать lib/features.php"

Сборка:

claude build-prompt import/
→ CODE-PROMPT.md (450 строк)

Пример 3: Большой модуль (catalog)

catalog/
├── SPEC.yaml           (150 строк)
├── CODE-PROMPT.md      (100 строк, навигация)
├── prompts/
│   ├── 1-filters.md    (250 строк)
│   ├── 2-search.md     (200 строк)
│   └── 3-pagination.md (150 строк)
└── src/

SPEC.yaml:

task: "Каталог товаров"
blocks:
  - filters: "Фильтры по параметрам"
  - search: "Поиск по артикулу"
  - pagination: "Умная пагинация"

Сборка:

claude build-prompt catalog/
→ CODE-PROMPT.md (600 строк)

claude split-prompt catalog/
→ prompts/1-filters.md
→ prompts/2-search.md
→ prompts/3-pagination.md
→ CODE-PROMPT.md обновлён (навигация)

ПРЕИМУЩЕСТВА

1. Гарантия актуальности

Проблема: Кодер использует устаревшие данные
Решение: CACHE отслеживает хеши, пересборка при изменениях

2. Единый источник истины

Проблема: Данные дублируются в разных местах
Решение: Данные в data/, CACHE агрегирует, SPEC ссылается

3. Автоматизация

Проблема: Ручная сборка промптов (долго, ошибки)
Решение: Автоматическая сборка из SPEC + CACHE

4. Масштабируемость

Проблема: Большие промпты не влезают в контекст
Решение: Разбиение на блоки (автоматически)

5. Прозрачность

Проблема: Непонятно откуда данные в промпте
Решение: Ссылки на источники в каждой секции

ОГРАНИЧЕНИЯ

1. Требует дисциплины

Проблема: Проектор может забыть обновить SPEC
Решение: Git hooks, автоматическая проверка

2. Начальная настройка

Проблема: Нужно создать CACHE, SPEC
Решение: Шаблоны, автоматическая инициализация

3. Зависимость от CACHE

Проблема: Если CACHE устарел, промпты неактуальны
Решение: check-cache перед кодированием

ЧЕКЛИСТ

Перед началом проекта

□ Создан PROJECT.md
□ Созданы data/*.md (источники)
□ Созданы standards/*.md (правила)
□ Запущен aggregate-project
□ CACHE.yaml создан

Перед созданием модуля

□ Создан module/SPEC.yaml
□ Проверены ссылки @CACHE
□ Добавлены локальные constraints
□ Запущен build-prompt
□ CODE-PROMPT.md создан

Перед кодированием

□ Запущен check-cache
□ Нет устаревших файлов
□ CODE-PROMPT.md актуален
□ Кодер прочитал промпт

После изменений в проекте

□ Запущен check-cache
□ Есть устаревшие файлы?
□ Запущен rebuild-stale
□ Все промпты обновлены

СВЯЗАННЫЕ СТАНДАРТЫ

ИСТОРИЯ

v1.0.0 (2026-02-03):
- Первая версия стандарта
- CACHE + SPEC + CODE-PROMPT
- Команды: aggregate, build-prompt, split-prompt, check-cache, rebuild-stale

Версия: 1.0.0