architect/arh/standards/structure-old/LAYERS_EXPLAINED.md

LAYERS EXPLAINED — Почему слои не последовательны

Два типа слоёв: прогрессивные и специализированные

Версия: 1.0.0
Дата: 2026-02-07

ПРОБЛЕМА

Я говорил что слои — это прогрессия:

business → design → specs → prompts → code

Но в матрице 10 слоёв:

.biz, .ops, .str, .prj, .arc, .dsg, .spc, .api, .pmt, .tst

Это НЕ последовательность! Почему?

ОТВЕТ: ДВА ТИПА СЛОЁВ

Слои делятся на два типа:

1. ПРОГРЕССИВНЫЕ СЛОИ (эволюция документа)

Эти слои образуют последовательность — эволюция от идеи к коду:

.biz (business)     ← ЗАЧЕМ (идея)
  ↓
.dsg (design)       ← КАК ОБЩЕЕ (решение)
  ↓
.spc (specs)        ← КАК ДЕТАЛЬНО (спецификации)
  ↓
.pmt (prompts)      ← ИНСТРУКЦИИ (для AI)
  ↓
src/ (code)         ← КОД (реализация)

Это прогрессия одного документа!

2. СПЕЦИАЛИЗИРОВАННЫЕ СЛОИ (параллельные документы)

Эти слои НЕ участвуют в прогрессии — это отдельные документы для специфичных задач:

Слой Для чего Когда создавать
.ops Операции, процессы Когда нужно описать процессы (деплой, backup)
.str Структура Когда нужно показать оргструктуру
.prj Проект Когда нужен план/роадмап проекта
.arc Архитектура Когда нужно описать техстек/архитектуру
.api API Когда нужно задокументировать интерфейсы
.tst Тесты Когда нужен тест-план

Это параллельные документы, не эволюция!

ВИЗУАЛИЗАЦИЯ

ПРОГРЕССИВНЫЕ (→ последовательно)          СПЕЦИАЛИЗИРОВАННЫЕ (↕ параллельно)

.biz (зачем)                                .ops (операции)
  ↓                                         .str (структура)
.dsg (как общее)                            .prj (план)
  ↓                                         .arc (архитектура)
.spc (как детально)                         .api (интерфейсы)
  ↓                                         .tst (тесты)
.pmt (инструкции)
  ↓
src/ (код)

Прогрессивные = стрелка вниз (↓) — это цепочка трансформации

Специализированные = параллельно (↕) — это отдельные документы

ПРИМЕР: МОДУЛЬ CATALOG

Прогрессивные слои (эволюция)

catalog/purpose.biz.md
→ "Нужен каталог товаров с фильтрами"
    ↓ конкретизация
catalog/design.dsg.md
→ "Компоненты: Products, Filters, Search"
    ↓ детализация
catalog/catalog-products.spc.md
→ "Функция fn_get_products($params) делает SELECT..."
    ↓ инструкции
catalog/products-create.pmt.md
→ "Создай класс Products в src/Products.php"
    ↓ реализация
catalog/src/Products.php
→ class Products { function getProducts($params) {...} }

Это ОДНА линия эволюции: идея → решение → спека → код

Специализированные слои (параллельно)

catalog/api.api.md              ← отдельный документ (API)
catalog/test.tst.md             ← отдельный документ (тесты)

Это НЕ часть прогрессии! Это дополнительные документы.

ПОЛНАЯ КАРТИНА

catalog/                              ← MODULE
│
├─── ПРОГРЕССИЯ (→)
│    ├── purpose.biz.md               ← зачем
│    ├── design.dsg.md                ← как общее
│    ├── catalog-products.spc.md      ← как детально
│    ├── products-create.pmt.md       ← инструкции
│    └── src/Products.php             ← код
│
└─── СПЕЦИАЛИЗИРОВАННЫЕ (параллельно)
     ├── api.api.md                   ← API документация
     └── test.tst.md                  ← тесты

Прогрессия = вертикальная эволюция (идея → код)

Специализированные = горизонтальные дополнения (API, тесты)

ПОЧЕМУ ТАК?

Прогрессивные слои

Цель: Показать эволюцию мысли от идеи до кода

Используются: Когда создаём что-то новое
- Начинаем с .biz (зачем)
- Проектируем .dsg (как)
- Детализируем .spc (что именно)
- Инструктируем .pmt (AI кодеру)
- Получаем src/ (код)

Пример: Разработка нового модуля catalog

Специализированные слои

Цель: Задокументировать специфичные аспекты

Используются: Когда нужно описать конкретную вещь
- .ops — когда нужны инструкции деплоя
- .arc — когда нужно показать техстек
- .api — когда нужно задокументировать интерфейс
- .tst — когда нужен тест-план

Пример: Документирование API модуля

МАТРИЦА: ДВА ТИПА × УРОВНИ

Прогрессивные слои

Уровень .biz .dsg .spc .pmt src/
organization ✅ — — — ❌
domain ✅ — — — ❌
project ✅ — — — ⚠️
engine — — — — ✅
module ⚠️ ✅ ✅ ✅ ✅
component — — ✅ ✅ ✅

Прогрессия работает в основном на уровне module/component!

Специализированные слои

Уровень .ops .str .prj .arc .api .tst
organization ✅ ✅ — — — —
domain ✅ — — ✅ — —
project ⚠️ — ✅ ✅ — —
engine ⚠️ — — — — —
module — — — — ✅ ✅
component — — — — — ⚠️

Специализированные слои — на разных уровнях для разных целей

ПРИМЕРЫ ПО УРОВНЯМ

ORGANIZATION (компания)

lideravto/
│
├─── ПРОГРЕССИВНЫЕ
│    └── vision.biz.md               ← зачем компания
│
└─── СПЕЦИАЛИЗИРОВАННЫЕ
     ├── processes.ops.md            ← бизнес-процессы
     └── departments.str.md          ← оргструктура

На уровне organization:
- Прогрессия заканчивается на .biz (нет кода)
- Специализированные: .ops (процессы), .str (структура)

DOMAIN (IT)

it/
│
├─── ПРОГРЕССИВНЫЕ
│    └── requirements.biz.md         ← что нужно от IT
│
└─── СПЕЦИАЛИЗИРОВАННЫЕ
     ├── tech-stack.arc.md           ← технологии
     ├── infrastructure.arc.md       ← инфраструктура
     └── deployment.ops.md           ← процессы деплоя

На уровне domain:
- Прогрессия заканчивается на .biz (нет кода)
- Специализированные: .arc (архитектура), .ops (операции)

PROJECT (lideravto-2026)

lideravto-2026/
│
├─── ПРОГРЕССИВНЫЕ
│    └── requirements.biz.md         ← бизнес-требования
│
└─── СПЕЦИАЛИЗИРОВАННЫЕ
     ├── roadmap.prj.md              ← план проекта
     ├── architecture.arc.md         ← архитектура
     └── deployment.ops.md           ← деплой

На уровне project:
- Прогрессия заканчивается на .biz (код в модулях)
- Специализированные: .prj (план), .arc (архитектура), .ops (деплой)

MODULE (catalog)

catalog/
│
├─── ПРОГРЕССИЯ (полная!)
│    ├── purpose.biz.md              ← зачем
│    ├── design.dsg.md               ← как общее
│    ├── catalog-products.spc.md     ← как детально
│    ├── products-create.pmt.md      ← инструкции
│    └── src/Products.php            ← код
│
└─── СПЕЦИАЛИЗИРОВАННЫЕ
     ├── api.api.md                  ← API
     └── test.tst.md                 ← тесты

На уровне module:
- Прогрессия полная: .biz → .dsg → .spc → .pmt → src/
- Специализированные: .api (интерфейс), .tst (тесты)

COMPONENT (Products)

src/Products/
│
├─── ПРОГРЕССИЯ (частичная)
│    ├── spec.spc.md                 ← спека (опционально)
│    ├── prompt.pmt.md               ← промпт (опционально)
│    └── Products.php                ← код
│
└─── СПЕЦИАЛИЗИРОВАННЫЕ
     └── test.tst.md                 ← тесты (опционально)

На уровне component:
- Прогрессия: .spc → .pmt → src/ (обычно только src/)
- Специализированные: .tst (если сложный)

ПРАВИЛА ИСПОЛЬЗОВАНИЯ

Когда использовать ПРОГРЕССИВНЫЕ слои

Всегда последовательно!

1. Начинаешь с .biz    ← зачем (идея)
2. Потом .dsg          ← как общее (решение)
3. Потом .spc          ← как детально (спеки)
4. Потом .pmt          ← инструкции (для AI)
5. Финал src/          ← код

НЕ перепрыгивай этапы!

❌ Неправильно:

.biz → .spc → src/     ← пропустили .dsg

✅ Правильно:

.biz → .dsg → .spc → .pmt → src/

Когда использовать СПЕЦИАЛИЗИРОВАННЫЕ слои

Создавай когда нужно описать конкретную вещь!

Нужно описать Создавай
Бизнес-процессы .ops.md
Оргструктуру .str.md
План проекта .prj.md
Техстек .arc.md
API функций .api.md
Тесты .tst.md

Это не часть прогрессии — это отдельные документы!

ЧАСТЫЕ ВОПРОСЫ

Q: Обязательно все слои в прогрессии?

A: НЕТ. Создавай только нужные:

Минимум (для простого модуля):

catalog/
├── purpose.biz.md     ← зачем
├── catalog.spc.md     ← что делает
└── src/               ← код

Полная прогрессия (для сложного):

catalog/
├── purpose.biz.md
├── design.dsg.md
├── catalog-products.spc.md
├── products-create.pmt.md
└── src/

Q: Можно пропустить .dsg?

A: Да, если модуль простой:

.biz → .spc → src/     ← ОК для простого модуля

Q: Зачем .api если есть .spc?

A: .api = специализированный слой, не часть прогрессии!

Пример:

catalog-products.spc.md    ← КАК работает (SQL, алгоритм)
api.api.md                 ← КАК использовать (примеры кода)

Q: Когда создавать .ops?

A: Когда нужно описать процессы, не функции:

deployment.ops.md          ← процесс деплоя (шаги)
backup.ops.md              ← процесс бэкапа (инструкции)
monitoring.ops.md          ← процесс мониторинга (что смотрим)

НЕ создавай .ops для функций — для этого .spc!

СХЕМА ПРИНЯТИЯ РЕШЕНИЯ

ХОЧУ СОЗДАТЬ ДОКУМЕНТ
    ↓
Вопрос 1: Это эволюция от идеи к коду?
    │
    ├─→ ДА → ПРОГРЕССИВНЫЙ слой
    │         ├── Идея? → .biz
    │         ├── Решение? → .dsg
    │         ├── Детали? → .spc
    │         ├── Инструкции? → .pmt
    │         └── Код? → src/
    │
    └─→ НЕТ → СПЕЦИАЛИЗИРОВАННЫЙ слой
              ├── Процессы? → .ops
              ├── Оргструктура? → .str
              ├── План? → .prj
              ├── Архитектура? → .arc
              ├── API? → .api
              └── Тесты? → .tst

ИСПРАВЛЕНИЕ ДОКУМЕНТАЦИИ

Было неточно

"Слои = последовательность business → design → specs → prompts → code"

Проблема: Это описывает только прогрессивные слои, игнорирует специализированные.

Точная формулировка

Слои бывают двух типов:

  1. ПРОГРЕССИВНЫЕ (эволюция документа):
    - .biz → .dsg → .spc → .pmt → src/
    - Используются для разработки нового функционала
    - Работают в основном на уровне module/component

  2. СПЕЦИАЛИЗИРОВАННЫЕ (параллельные документы):
    - .ops, .str, .prj, .arc, .api, .tst
    - Используются для описания конкретных аспектов
    - Не участвуют в прогрессии
    - На разных уровнях для разных целей

ИТОГ

10 слоёв = 2 группы:

ПРОГРЕССИВНЫЕ (5):              СПЕЦИАЛИЗИРОВАННЫЕ (6):
.biz                            .ops
.dsg                            .str
.spc                            .prj
.pmt                            .arc
src/                            .api
                                .tst

↓ последовательно               ↕ параллельно
(эволюция)                      (дополнения)

Ключевое:
- Прогрессивные = цепочка трансформации (идея → код)
- Специализированные = отдельные документы (API, тесты, процессы)

Оба типа нужны, но для разных целей!

Версия: 1.0.0
Связанные стандарты:
- FOLDERS_FILES_STRUCTURE.md
- LAYERS_GUIDE.md