CONCEPT.md

Этот документ описывает концепцию платформы — философию, принципы и идеи, лежащие в основе дизайна.

Это НЕ:
- ❌ Архитектура (см. ARCHITECTURE.md)
- ❌ Спецификации (см. specifications/)
- ❌ Примеры реализации
- ❌ Технические детали

Это:
- ✅ Почему платформа устроена так
- ✅ Философия подхода
- ✅ Принципы принятия решений
- ✅ Идеи, которые определяют дизайн

1. ФИЛОСОФИЯ ПЛАТФОРМЫ

1.1 Зачем нужна платформа?

Проблема:
Работа с множеством проектов, инфраструктур, агентов приводит к:
- Хаосу в структуре
- Дублированию информации
- Несогласованности между частями
- Сложности понимания системы
- Огромному расходу токенов

Решение:
Платформа создаёт единую согласованную систему, где:
- Каждый элемент имеет чёткое место
- Информация не дублируется
- Структура самодокументирующаяся
- Расход токенов минимален

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

Один взгляд не может описать всю систему. Нужно видеть систему с разных сторон, но каждый срез должен быть независим и чист.

2. МНОГОМЕРНЫЙ ПОДХОД

2.1 Концепция 8 измерений

Система анализируется через 8 независимых измерений (срезов):

2.2 Почему именно 8?

Эти 8 измерений покрывают все аспекты системы:

Эти 8 измерений — минимальный достаточный набор для полного понимания.

2.3 Принцип независимости срезов

Почему это важно?
- Изменение в одном срезе не ломает другие
- Можно анализировать систему с одной стороны, не загружая всё остальное
- Легче находить проблемы (они всегда в конкретном измерении)
- Экономия токенов (загружаем только нужный срез)

Пример:
- Структурное измерение: "Проект находится в projects/marketplace/"
- Функциональное измерение: "Проект управляет каналами продаж"
- Это разные вопросы, требующие разных ответов, но описывающие один объект.

2.4 Взаимодействие измерений

Измерения независимы, но связаны через объекты:

Объект: "marketplace"

Структурно → projects/marketplace/
Функционально → "Управление Ozon"
Процессно → "Workflow обработки заказов"
Ролево → "Project-agent выполняет"
Технически → "Python + Streamlit"
Информационно → "SQLite БД + YAML конфиги"
Временно → "v1.0.0 → v1.1.0"
Пространственно → "@infra-dev-pro"

Все измерения описывают один объект, но с разных сторон.

3. АРХИТЕКТУРНАЯ ЧИСТОТА

3.1 Принцип единой ответственности

Применение:
- Один файл = одна роль
- Одна папка = один контекст
- Один агент = один тип задач
- Одно измерение = один аспект системы

Антипример:
- ❌ Файл, который содержит и концепцию, и архитектуру, и спецификации
- ❌ Агент, который создаёт проекты и работает с API
- ❌ Документ, который описывает и философию, и конкретные форматы файлов

3.2 Принцип отсутствия дублирования (DRY)

Применение:
- Информация хранится в одном месте
- Другие места ссылаются на источник
- При изменении обновляется только источник

Почему это важно:
- Нет рассогласованности при изменениях
- Экономия токенов (одна информация загружается раз)
- Проще поддерживать (изменение в одном месте)

Механизмы:
- Символические ссылки (@latest → v2.0.0)
- References в YAML (infra: @infra-dev-pro)
- Компоненты и templates

3.3 Принцип чётких границ

Применение:
- Папка определяет контекст работы
- Агент работает ТОЛЬКО в своей области
- Измерение описывает ТОЛЬКО свой аспект

Почему это важно:
- Безопасность (агент не может сломать чужой код)
- Предсказуемость (знаем, где что искать)
- Изоляция ошибок (проблема в одной зоне)

4. ЭКОНОМИКА ТОКЕНОВ

4.1 Проблема расхода токенов

AI агенты работают в рамках ограниченного контекста (tokens).

Наивный подход:
Загрузить весь код и всю документацию → 100K+ tokens

Результат:
- Медленная работа
- Высокая стоимость
- Достижение лимитов

4.2 Каскадная загрузка (80/15/5)

Уровни:
- Уровень 1 (80% задач) — Минимальный контекст (~1-2K tokens)
- Уровень 2 (15% задач) — Расширенный контекст (~5-10K tokens)
- Уровень 3 (5% задач) — Полный контекст (~20-50K tokens)

Почему 80/15/5?
- Эмпирическое наблюдение: большинство задач простые
- Закон Парето (80/20) + детализация остатка
- Оптимизация среднего случая

4.3 Lazy Loading (ленивая загрузка)

Механизмы:
- Загрузка документов по требованию
- Индексы (index.yaml) вместо полных файлов
- Агенты загружаются только при использовании

4.4 Переиспользование

Механизмы:
- Компоненты (FSD) — код, используемый в разных проектах
- Templates — структуры для создания новых элементов
- Shared vendor — общие зависимости

Экономия:
- Компоненты: 80-90%
- Templates: 60%
- Shared vendor: 78-85%

5. БЕЗОПАСНОСТЬ ИЗМЕНЕНИЙ

5.1 Проблема необратимых изменений

Риски:
- Сломать работающий код
- Потерять данные
- Внести несовместимые изменения
- Не иметь возможности отката

5.2 Поэтапный подход

Принципы:
- Чекпоинты (сохранение состояния)
- Валидация (проверка корректности)
- Rollback (откат при проблемах)
- Staging (тестирование перед продакшеном)

5.3 Правило подтверждения

Применение:
- ВСЕГДА спрашивать перед изменением файлов
- ВСЕГДА спрашивать перед удалением
- БЕЗ подтверждения: только чтение и анализ

Почему это важно:
- Оператор контролирует процесс
- Нет неожиданных изменений
- Безопасность критичных операций

5.4 Правило альтернатив

Почему это важно:
- Оператор видит все варианты
- Может выбрать оптимальный для своей ситуации
- Понимает компромиссы (плюсы/минусы каждого варианта)

6. MAINTENANCE-FRIENDLY ДИЗАЙН

6.1 Проблема забывания

Реальность:
Через 3 месяца:
- Забыл, зачем это сделано
- Забыл, как это работает
- Забыл, где что лежит

6.2 Самодокументирование

Механизмы:
- Имя папки = назначение (projects/ очевидно для проектов)
- Имя файла = роль (CLAUDE.md очевидно для агентов)
- Структура = логика (design/ → management/ → solution/ понятна)

6.3 Принцип "через 3 месяца"

Критерии:
- ✅ Понятны названия
- ✅ Понятна структура
- ✅ Есть README.md для людей
- ✅ Есть CLAUDE.md для агентов
- ✅ Есть index.yaml для навигации

6.4 Эволюционируемость

Механизмы:
- Версионирование (v1.0.0 → v1.1.0 → v2.0.0)
- Миграции (плавный переход между версиями)
- Архивирование (сохранение старых версий)
- Обратная совместимость (старое продолжает работать)

7. ГРАНИЦЫ ПРИМЕНИМОСТИ

7.1 Когда использовать эту платформу?

Подходит для:
- ✅ Множество проектов (5+)
- ✅ Работа с AI агентами
- ✅ Требуется согласованность
- ✅ Требуется экономия токенов
- ✅ Долгосрочная поддержка (годы)

НЕ подходит для:
- ❌ Одноразовый скрипт
- ❌ Быстрый прототип (2 часа)
- ❌ Система без AI агентов
- ❌ Нет требований к структуре

7.2 Альтернативные подходы

Альтернатива 1: Монорепозиторий
- Всё в одной папке
- Подходит: маленький проект, один разработчик
- Не подходит: множество проектов, команда

Альтернатива 2: Микросервисная архитектура
- Каждый проект полностью независим
- Подходит: большие команды, разные технологии
- Не подходит: общие компоненты, единая система

Альтернатива 3: Без структуры
- Папки создаются по необходимости
- Подходит: эксперименты, временные проекты
- Не подходит: долгосрочная поддержка

7.3 Почему выбрана эта концепция?

Целевой сценарий:
- Множество проектов (marketplace, pim, platform-v2, ...)
- Работа с AI агентами (Orchestrator, Project-agent, ...)
- Долгосрочная поддержка (годы)
- Экономия токенов критична
- Требуется согласованность

Для этого сценария:
- 8 измерений → полное понимание
- Архитектурная чистота → легко поддерживать
- Экономика токенов → быстро и дёшево
- Безопасность изменений → можно эволюционировать
- Maintenance-friendly → понятно через месяцы/годы

8. ЭВОЛЮЦИЯ КОНЦЕПЦИИ

8.1 История

v0.x — Хаос
- Проекты в разных местах
- Дублирование документации
- Нет согласованности

v1.0 — Platform v1
- Появилась структура
- Определены стандарты
- Создан workspace

v2.0 — Platform v2 (текущая)
- 8 измерений
- Архитектурная чистота
- Экономика токенов
- 4 кластера (система, platform v1, platform v2, проекты)

8.2 Версионирование концепции

Изменения концепции:
- Мажорные (1.x → 2.x) — изменение фундаментальных принципов
- Минорные (2.0 → 2.1) — добавление новых идей
- Патчи (2.1.0 → 2.1.1) — уточнение формулировок

Обратная совместимость:
- Старые проекты продолжают работать (platform v1)
- Новые создаются по новой концепции (platform v2)
- Миграция постепенная, не обязательная

8.3 Будущее

Возможные направления:
- Автоматизация создания структур
- AI-помощники для каждого измерения
- Интеграция с внешними системами
- Расширение на другие языки (PLATFORM-V2 language)

Platform Design Concept

Назначение документа