architect/_archive/2025-11-26-cleanup/system-docs/architecture/2-functional.md

Функциональное измерение

Версия: 1.0.0
Дата: 2025-11-19

Что описывает это измерение

Вопрос: Что делает система?

Ответ:
- Функции системы
- Система агентов
- Каскадная загрузка
- Workflows

НЕ описывает:
- Где находятся файлы (структурное)
- Как выполняются операции (процессное)
- Кто за что отвечает (ролевое)

Основные функции системы

1. Навигация

Что делает: Поиск и перемещение по workspace

Функции:
- Найти проект по имени
- Найти файл по назначению
- Понять структуру папки
- Получить метаданные

Инструменты:
- index.yaml — быстрая навигация
- Glob — поиск файлов по паттерну
- Grep — поиск по содержимому

2. Создание

Что делает: Создание новых элементов

Функции:
- Создать проект
- Создать компонент
- Создать инфраструктуру
- Создать документ

Инструменты:
- Templates — шаблоны структур
- Procedures — процедуры создания
- Write — запись файлов

3. Модификация

Что делает: Изменение существующего

Функции:
- Изменить код
- Обновить документацию
- Исправить баг
- Добавить функцию

Инструменты:
- Read — чтение текущего состояния
- Edit — точечные изменения
- Git — версионирование изменений

4. Анализ

Что делает: Понимание системы

Функции:
- Проанализировать структуру
- Понять зависимости
- Найти проблемы
- Оценить качество

Инструменты:
- Read — чтение файлов
- Grep — поиск паттернов
- Bash — выполнение команд анализа

5. Интеграция

Что делает: Работа с внешними системами

Функции:
- Подключение к API
- Обработка данных
- Синхронизация
- Деплой на сервер

Инструменты:
- Integrator agent — работа с API
- Bash — команды ssh, scp, rsync
- MCP servers — интеграции

Система агентов

Иерархия

┌─────────────────────────────┐
│      Operator (Человек)     │
└──────────────┬──────────────┘
               │
       ┌───────┴───────┐
       ▼               ▼
┌──────────────┐  ┌──────────┐
│ Orchestrator │  │ Terminal │
└──────┬───────┘  └──────────┘
       │
   ┌───┴────┬─────────┬──────────┐
   ▼        ▼         ▼          ▼
┌────────┐ ┌───────┐ ┌─────────┐ ┌────────────┐
│Project │ │ Infra │ │ Claude  │ │ Integrator │
│ agent  │ │ agent │ │  Code   │ └────────────┘
└────────┘ └───────┘ └─────────┘

Функции агентов

Operator
- Постановка задач
- Принятие решений
- Контроль качества

Orchestrator
- Управление workspace
- Создание проектов
- Запуск агентов
- Координация

Project-agent
- Изменение кода проекта
- Тестирование
- Деплой
- Документирование

Infra-agent
- Создание инфраструктуры
- Настройка серверов
- Управление доступами

Terminal
- Интерфейс с оператором
- Меню навигации
- Форматирование вывода

Claude Code
- Знание инструментов
- Оптимизация операций
- Безопасность

Integrator
- Работа с API
- Обработка данных
- MCP серверы

Каскадная загрузка контекста

Концепция

Идея: 80% задач решается с минимальным контекстом

Уровни:
- Уровень 1: 1-2K tokens (80% задач)
- Уровень 2: 5-10K tokens (15% задач)
- Уровень 3: 20-50K tokens (5% задач)

Уровень 1: Минимальный

Загружаемые файлы:

CLAUDE.md         # Контекст агента
index.yaml        # Навигация

Задачи:
- Проверить статус
- Запустить команду
- Выполнить процедуру
- Ответить на простой вопрос

Пример:

Вопрос: "Какой статус проекта marketplace?"
Загрузка: CLAUDE.md + index.yaml
Ответ: "Status: production"

Уровень 2: Расширенный

Дополнительно загружаемые файлы:

design/spec.md          # Спецификация
management/README.md    # Процедуры
README.md               # Описание

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

Пример:

Задача: "Добавить экспорт заказов в Excel"
Загрузка: Уровень 1 + design/spec.md + solution/code/modules/orders/
Действие: Создать модуль excel_export.py

Уровень 3: Полный

Дополнительно загружаемые файлы:

solution/code/**/*      # Весь код
infrastructure/*        # Инфра
platform/standard.yaml  # Стандарты

Задачи:
- Рефакторинг
- Миграция версий
- Архитектурные изменения
- Полный аудит

Пример:

Задача: "Рефакторинг модуля доставки"
Загрузка: Весь код модуля + зависимости + стандарты
Действие: Полная переработка архитектуры модуля

Основные workflows

Workflow: Создание проекта

Функции:
1. Определить тип проекта
2. Собрать информацию
3. Создать структуру папок
4. Создать обязательные файлы
5. Git commit
6. Обновить индексы

Агенты: Orchestrator

Workflow: Работа над задачей

Функции:
1. Загрузить контекст (уровень 1-3)
2. Понять задачу
3. Проверить текущее состояние
4. Выполнить изменения
5. Проверить работоспособность
6. Документировать
7. Commit (если запрошено)

Агенты: Project-agent

Workflow: Подключение к инфраструктуре

Функции:
1. Найти инфраструктуру
2. Загрузить config.yaml
3. Проверить usage (ready/project)
4. Получить доступы
5. Подключиться

Агенты: Orchestrator, Infra-agent

Workflow: Миграция версий

Функции:
1. Инвентаризация
2. Анализ
3. Планирование
4. Staging
5. Валидация
6. Миграция
7. Верификация
8. Архивирование

Агенты: Orchestrator

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

Components (FSD)

Функция: Переиспользуемый код между проектами

Механизм:

components/auth-module/
└── src/
    └── auth.py

projects/marketplace/solution/code/
└── from components.auth import Auth

projects/pim-drupal/solution/code/
└── from components.auth import Auth

Экономия: 80-90% (один раз написать, много раз использовать)

Templates

Функция: Быстрое создание новых элементов

Механизм:

templates/project/
└── template/
    ├── CLAUDE.template.md
    └── README.template.md

→ Заменить {{PROJECT_NAME}} → Готовый проект

Экономия: 60% (структура создаётся автоматически)

Shared Vendor

Функция: Общие зависимости

Механизм:

/vendor/drupal/      # Общий Drupal

projects/site1/ → symlink → /vendor/drupal/
projects/site2/ → symlink → /vendor/drupal/
projects/site3/ → symlink → /vendor/drupal/

Экономия: 78-85% (место на диске + токены)

Lazy Loading

Концепция

Идея: Загружать только то, что нужно, когда нужно

Примеры

Агенты:

Базовая задача → Без дополнительных агентов
Работа с проектом → Загрузить orchestrator.ai.md
Работа с API → Загрузить integrator.ai.md

Документация:

Вопрос о структуре → Загрузить architecture/1-structural.md
Вопрос о процессах → Загрузить architecture/3-process.md

Код:

Простая задача → Только CLAUDE.md + index.yaml
Сложная задача → + design/spec.md + код модуля
Рефакторинг → Весь код проекта

Функциональные блоки

Блок: Управление проектами

Функции:
- Создать проект
- Удалить проект (архивировать)
- Обновить метаданные
- Мигрировать версию

Файлы:
- platform/procedures/ONBOARD_NEW_PROJECT.md
- templates/project/

Блок: Управление инфраструктурой

Функции:
- Зарегистрировать инфраструктуру (ready)
- Создать инфраструктуру (project)
- Подключиться к инфре
- Обновить конфигурацию

Файлы:
- infra/*/config.yaml
- templates/infra/

Блок: Работа с кодом

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

Инструменты:
- Read, Edit, Write
- Git (commit, diff)

Блок: Работа с документацией

Функции:
- Прочитать документ
- Обновить документ
- Создать документ
- Поиск по документам

Форматы:
- Markdown (основной)
- YAML (метаданные)

Блок: Интеграция

Функции:
- API запросы
- Обработка данных
- Синхронизация
- MCP серверы

Агент: Integrator

Следующее измерение

Следующее: 3-process.md — как выполняются операции

Назад: 1-structural.md — структурное измерение