Версия: 2.0.0
Дата: 2025-11-19
Статус: Draft for Review
Принцип: Любая сложная система имеет несколько независимых измерений (срезов). Каждое измерение описывает систему со своей стороны.
Структурное — Иерархия папок и файлов
- Где что лежит
- Какие папки и файлы обязательны
- Связи между папками
Функциональное — Что делает система
- Какие задачи решает
- Какие операции выполняет
- Какие результаты производит
Процессное — Как выполняются операции
- Последовательность действий
- Алгоритмы и процедуры
- Workflow и автоматизация
Ролевое — Кто с чем работает
- Агенты (Orchestrator, Project-agent, Infra-agent)
- Операторы (человек)
- Распределение ответственности
Техническое — Технологии и инструменты
- Языки программирования
- Фреймворки и библиотеки
- Инструменты разработки
Информационное — Данные и их потоки
- Форматы данных (YAML, Markdown, JSON)
- Схемы и модели
- Потоки данных между компонентами
Временное — Жизненный цикл
- Версионирование
- История изменений
- Миграции между версиями
Пространственное — Распределение
- Локальный workspace
- Удаленные серверы (VPS, shared hosting)
- Облачные хранилища
Ключевое правило: Каждый срез имеет свою логику и НЕ смешивается с другими.
Пример применения:
- Структурно: /opt/claude-workspace/projects/marketplace/
- Функционально: "Управление каналами продаж Ozon"
- Процессно: "ONBOARD_NEW_PROJECT.md → создание структуры → git commit"
- Ролево: "Project-agent выполняет, Orchestrator контролирует"
- Технически: "Python + Streamlit + SQLAlchemy"
- Информационно: "YAML конфиги + SQLite БД + Markdown документация"
- Временно: "v1.0.0 → v1.1.0 через migration"
- Пространственно: "@infra-dev-pro (91.218.142.168:8503)"
1. Единая ответственность
- Один файл = одна роль
- Одна папка = один контекст
- Один агент = один тип задач
2. Отсутствие дублирования
- Информация хранится в одном месте
- Другие места ссылаются на источник
- Использование символических ссылок и references
3. Четкие границы
- Папка определяет контекст работы
- Файл определяет назначение
- Агент НЕ выходит за пределы своей области
4. Явные зависимости
- Зависимости через ссылки, не копирование
- Связи документированы в index.yaml
- Инфраструктура указана явно (поле infra)
Анти-паттерны (чего избегать):
- ❌ Дублирование кода в разных проектах → ✅ Использовать components/
- ❌ Смешивание ролей в одном файле → ✅ Разделить по файлам
- ❌ Копирование конфигов → ✅ Ссылки на шаблоны
- ❌ Агент изменяет чужие проекты → ✅ Агент работает только в своей папке
Уровень 1 — Минимальный контекст (80% задач)
- Размер: 1-2K tokens
- Файлы: CLAUDE.md + index.yaml
- Задачи: Простые операции, стандартные процедуры
- Пример: "Проверить статус проекта", "Запустить тесты"
Уровень 2 — Расширенный контекст (15% задач)
- Размер: 5-10K tokens
- Файлы: + design/spec.md + management/procedures.md
- Задачи: Модификации, отладка, анализ
- Пример: "Добавить новую функцию", "Исправить баг"
Уровень 3 — Полный контекст (5% задач)
- Размер: 20-50K tokens
- Файлы: + solution/code/* + все документы
- Задачи: Рефакторинг, миграция, архитектурные изменения
- Пример: "Переписать модуль", "Мигрировать на новую версию"
1. Компоненты (FSD)
- Экономия: 80-90%
- Механизм: Переиспользование кода через components/
- Пример: auth-module используется в 5 проектах → загружается 1 раз
2. Шаблоны
- Экономия: 60%
- Механизм: templates/ вместо повторения структур
- Пример: Создание проекта через template вместо описания структуры
3. Shared Vendor
- Экономия: 78-85%
- Механизм: Общие зависимости (Drupal, Composer)
- Пример: 5 Drupal сайтов → 1 общий vendor/
4. Lazy Loading
- Экономия: зависит от задачи
- Механизм: Загрузка документов по требованию
- Пример: Загружать orchestrator.ai.md только при управлении проектами
5. Символические ссылки
- Экономия: архитектурная
- Механизм: Ссылки вместо копирования
- Пример: @latest → конкретная версия
10 стадий миграции с чекпоинтами:
На каждой стадии:
- ✅ Чекпоинт (сохранение состояния)
- ✅ Возможность отката (rollback)
- ✅ Валидация результата
- ✅ Документирование изменений
ВСЕГДА спрашивать перед:
- Создание/изменение файлов (код, документы, конфиги)
- Удаление файлов/папок
- Изменение настроек/конфигураций
- Выполнение команд с побочными эффектами
БЕЗ подтверждения разрешено:
- Чтение файлов (Read, Glob, Grep)
- Проверка статуса (git status, ls, cat)
- Диагностика (curl, ping, ps)
- Обсуждение и планирование
При наличии нескольких решений:
✅ Рекомендуемое (лучший вариант)
- Описание
- Плюсы / Минусы
- Когда использовать
⚙️ Альтернатива 1
- Описание
- Плюсы / Минусы
- Когда использовать
⚙️ Альтернатива 2
- Описание
- Плюсы / Минусы
- Когда использовать
⚠️ Не рекомендую (но возможно)
- Описание
- Почему не рекомендуется
- Когда можно использовать
Спросить: "Какой вариант выбираете? (1/2/3/обсудить)"
Самодокументирующаяся структура:
- Папка = назначение (projects/, infra/, components/)
- Файл = роль (CLAUDE.md для AI, README.md для людей)
- Имя = содержание (ONBOARD_NEW_PROJECT.md)
Обязательная документация:
- ✅ README.md — для людей (что это, зачем, как использовать)
- ✅ CLAUDE.md — для агентов (роль, задачи, ограничения)
- ✅ index.yaml — для навигации (быстрый поиск)
- ✅ config.yaml — для инфраструктуры (метаданные)
Принцип "через 3 месяца":
- Можно понять назначение без объяснений
- Можно восстановить контекст из файлов
- Можно продолжить работу без автора
1. Версионирование
version: "1.0.0"
updated: "2025-11-19"
2. Миграция через staging
- Создать новую версию рядом со старой
- Протестировать
- Переключиться
- Архивировать старую
3. Сохранение истории
archive/
├── 2025-11-09-marketplace-old/
└── old-projector/проектор/
4. Changelog
- Что изменилось
- Почему изменилось
- Как мигрировать
УРОВЕНЬ 1: Экосистема
└─ /opt/claude-workspace/
УРОВЕНЬ 2: Подсистемы
├─ system/ # Системные агенты
├─ platform/ # Стандарты
├─ projects/ # Приложения
├─ infra/ # Инфраструктура
├─ components/ # Компоненты
├─ library/ # Библиотеки
├─ templates/ # Шаблоны
└─ scripts/ # Скрипты
УРОВЕНЬ 3: Приложения
└─ projects/{name}/
├─ design/ # Проектирование
├─ management/ # Управление
├─ infrastructure/ # Инфра (опц)
└─ solution/ # Решение
УРОВЕНЬ 4: Модули
└─ solution/
├─ code/ # Код
├─ config/ # Конфиги (опц)
└─ data/ # Данные (опц)
УРОВЕНЬ 5: Компоненты
└─ code/
├─ modules/ # Модули приложения
├─ utils/ # Утилиты
└─ tests/ # Тесты
УРОВЕНЬ 6: Функции
└─ modules/products/
├─ crud.py # CRUD операции
└─ queries.py # Запросы
УРОВЕНЬ 7: Элементы
└─ crud.py
├─ create_product()
├─ read_product()
├─ update_product()
└─ delete_product()
Движение ВВЕРХ (к абстрактному):
- Автоматическое
- Без подтверждения
- Для получения контекста
Движение ВНИЗ (к конкретному):
- Требует подтверждения
- Перед любыми изменениями
- Явное переключение контекста
Назначение: Конкретное приложение с кодом
Обязательная структура:
projects/{name}/
├── CLAUDE.md # Для project-agent ✅
├── README.md # Для людей ✅
├── index.yaml # Индекс проекта ✅
│
├── design/ # Проектирование
│ ├── PROJECT.md # Описание проекта
│ └── spec.md # Спецификация (опц)
│
├── management/ # Управление
│ ├── README.md # Процедуры
│ └── changelog.md # История (опц)
│
├── infrastructure/ # Инфра (опционально)
│ ├── deployment.md
│ └── monitoring.md
│
└── solution/ # Решение
└── code/ # Исходный код
└── [application files]
Примеры: marketplace, pim-drupal, pirotehnika-opencart
Назначение: Фреймворк или платформа для создания приложений
Особенности:
- Код может быть в отдельной папке (не в projects/)
- projects/{name}/ содержит только метаданные
- Основной код в специальной локации
Структура метаданных:
projects/{name}/
├── CLAUDE.md # Контекст ✅
├── README.md # Описание ✅
├── index.yaml # Индекс ✅
├── LOCATION.md # Где находится код ✅
│
└── design/
└── PROJECT.md # Описание платформы
Структура основного кода:
/{platform-name}/ # Вне projects/
├── [platform files] # Код платформы
├── docs/ # Документация
│ ├── 01_MASTER.md
│ ├── 02_CORE_CONCEPTS.md
│ └── ...
├── agents/ # Агенты платформы
└── apps/ # Приложения на платформе
Пример: cifra (код в /opt/claude-workspace/cifra/, метаданные в projects/cifra/)
Назначение: Шаблон для создания новых проектов/компонентов
Структура:
templates/{name}/
├── README.md # Описание шаблона
├── structure.yaml # Описание структуры
├── variables.yaml # Переменные шаблона
│
└── template/ # Файлы шаблона
├── CLAUDE.template.md
├── README.template.md
└── [other template files]
structure.yaml:
template:
name: "project-template"
type: "web-app"
version: "1.0.0"
structure:
files:
- "CLAUDE.md"
- "README.md"
- "index.yaml"
folders:
- "design/"
- "management/"
- "solution/"
variables:
- name: "PROJECT_NAME"
description: "Имя проекта"
- name: "PROJECT_TYPE"
description: "Тип проекта"
options: ["web-app", "service", "library"]
Пример: drupal-shop-template
Назначение: Инструмент для разовой задачи
Структура:
projects/{name}/
├── CLAUDE.md # Контекст
├── README.md # Описание
│
├── design/
│ └── PROJECT.md # Цель утилиты
│
└── solution/
└── code/ # Код утилиты
└── [utility scripts]
Особенности:
- Может не иметь infrastructure/
- Может не требовать deployment
- Часто однократное использование
Пример: nomenclature1c (анализ номенклатуры из 1С)
Назначение: Подключение к существующей инфраструктуре
Файл: config.yaml (обязательно)
infrastructure:
name: "DEV-PRO Server"
type: vps # vps | shared-hosting | cloud-storage | web-panel | external-service
usage: ready # ← КЛЮЧЕВОЕ ПОЛЕ
status: active
provider: "Hetzner"
ip: "91.218.142.168"
created: "2025-01-01"
access:
ssh:
host: "91.218.142.168"
user: "root"
key_path: "~/.ssh/id_rsa"
projects:
- name: "marketplace"
path: "/opt/workspace/projects/marketplace/"
type: "web-app"
status: "active"
specifications:
cpu:
cores: 4
ram:
total: "8 GB"
disk:
total: "100 GB"
type: "SSD"
version: "1.0.0"
last_updated: "2025-11-19"
Дополнительные файлы (опционально):
- README.md — Описание инфраструктуры
- access.md — Инструкции по подключению
- monitoring.md — Мониторинг
Примеры:
- infra/@infra-dev-pro/ — VPS Hetzner
- infra/@remote-beget-kondurov/ — Shared hosting
- infra/infra-yandex-disk/ — Cloud storage
Назначение: Проект создания новой инфраструктуры
Обязательная структура:
infra/{name}/
├── config.yaml # Метаданные ✅
│ usage: project
├── CLAUDE.md # Для infra-agent ✅
├── README.md # Описание ✅
├── index.yaml # Индекс ✅
│
├── design/ # Проектирование
│ └── plan.md # План создания
│
└── solution/ # Решение
└── terraform/ # IaC код
└── [terraform files]
config.yaml:
infrastructure:
name: "New Production Server"
type: vps
usage: project # ← КЛЮЧЕВОЕ ПОЛЕ
status: planning # planning | creating | active
target:
provider: "AWS"
region: "us-east-1"
created: "2025-11-19"
lifecycle:
- step: "planning"
description: "Проектирование"
status: "completed"
- step: "creating"
description: "Создание через infra-agent"
status: "in_progress"
- step: "active"
description: "Развёрнуто, usage → ready"
status: "pending"
version: "1.0.0"
last_updated: "2025-11-19"
Жизненный цикл:
1. usage: project + status: planning → Проектирование
2. usage: project + status: creating → Создание (infra-agent)
3. usage: ready + status: active → Готово к использованию
| Папка | README.md | CLAUDE.md | index.yaml | config.yaml | Код AI |
|---|---|---|---|---|---|
| system/ | ✅ | ❌ | ✅ | ❌ | ✅ (*.ai.md) |
| platform/ | ✅ | ❌ | ✅ | ❌ | ✅ (standard.yaml) |
| projects/{name}/ | ✅ | ✅ | ✅ | ❌ | ❌ |
| infra/{name}/ (ready) | ⚙️ | ❌ | ❌ | ✅ | ❌ |
| infra/{name}/ (project) | ✅ | ✅ | ✅ | ✅ | ❌ |
| components/{name}/ | ✅ | ❌ | ❌ | ❌ | ❌ |
| library/{name}/ | ✅ | ❌ | ❌ | ❌ | ❌ |
| templates/{name}/ | ✅ | ❌ | ❌ | ❌ | ❌ |
| scripts/ | ✅ | ❌ | ✅ | ❌ | ❌ |
Легенда:
- ✅ Обязательно
- ⚙️ Опционально, но рекомендуется
- ❌ Не требуется
README.md — Для людей
- Что это
- Зачем нужно
- Как использовать
- Примеры
CLAUDE.md — Для AI агентов
- Роль агента
- Задачи
- Ограничения
- Команды
index.yaml — Для навигации
- Список файлов
- Назначение каждого файла
- Темы (topics)
- Размеры файлов
config.yaml — Для инфраструктуры
- Метаданные инфры
- Тип и статус
- Доступы
- Спецификации
┌─────────────────────────────────────────┐
│ Orchestrator (оркестратор) │
│ system/orchestrator.ai.md │
│ │
│ Роль: Управление проектами и инфрой │
│ Загрузка: По требованию │
│ Контекст: Workspace-уровень │
└────────────┬────────────────────────────┘
│
├─────────────────┬──────────────────┐
▼ ▼ ▼
┌────────────────┐ ┌─────────────┐ ┌──────────────┐
│ Project-agent │ │ Infra-agent │ │ Terminal │
│ projects/{n}/ │ │ infra/{n}/ │ │ terminal.md │
│ CLAUDE.md │ │ CLAUDE.md │ │ │
└────────┬───────┘ └─────────────┘ └──────────────┘
│
├──────────────────────────────────┐
▼ ▼
┌────────────────┐ ┌──────────────────┐
│ Claude Code │ │ Integrator │
│ claude-code │ │ integrator.md │
│ .ai.md │ │ │
└────────────────┘ └──────────────────┘
1. Orchestrator — Управляющий
- Файл: system/orchestrator.ai.md
- Роль: Управление workspace на верхнем уровне
- Задачи:
- Создание проектов
- Управление инфраструктурой
- Запуск специализированных агентов
- Координация между проектами
- Загрузка: По требованию (~500 tokens)
- Не делает: Не изменяет код напрямую
2. Project-agent — Исполнитель проекта
- Файл: projects/{name}/CLAUDE.md
- Роль: Работа внутри конкретного проекта
- Задачи:
- Изменение кода проекта
- Тестирование
- Деплой
- Обновление документации
- Ограничения:
- Работает ТОЛЬКО в своей папке
- НЕ изменяет platform/
- НЕ изменяет другие проекты
3. Infra-agent — Исполнитель инфраструктуры
- Файл: infra/{name}/CLAUDE.md
- Роль: Создание/настройка инфраструктуры
- Задачи:
- Создание terraform конфигурации
- Развёртывание серверов
- Настройка доступов
- Обновление config.yaml
- Применяется: Только для usage: project
4. Claude Code Agent — Инструменталист
- Файл: system/claude-code.ai.md
- Роль: Знание инструментов Claude Code
- Задачи:
- Правильное использование 7 инструментов
- Оптимизация работы с файлами
- Безопасность операций
- Загрузка: На требование (~400 tokens)
5. Terminal — Интерфейс
- Файл: system/terminal.ai.md
- Роль: Интерфейс с оператором
- Задачи:
- Меню навигации
- Восстановление сессий
- Понятный вывод
- Загрузка: При первом запуске (~300 tokens)
6. Integrator — Интеграции
- Файл: system/integrator.ai.md
- Роль: Работа с внешними API
- Задачи:
- Интеграция с Ozon API
- Интеграция с CDEK, Почта России
- MCP серверы
- Загрузка: При работе с API (~300 tokens)
80% задач решается на Уровне 1
15% задач требует Уровня 2
5% задач требует Уровня 3
Загружаемые файлы:
- CLAUDE.md — Контекст агента
- index.yaml — Быстрая навигация
Задачи:
- Проверить статус
- Запустить стандартную команду
- Выполнить типовую процедуру
- Ответить на простой вопрос
Примеры:
# Проверить статус проекта
cat projects/marketplace/CLAUDE.md
cat projects/marketplace/index.yaml
# Запустить тесты
tmux attach -t marketplace
pytest tests/
# Проверить процесс
ps aux | grep streamlit
Дополнительно загружаемые файлы:
- design/spec.md — Спецификация
- management/procedures.md — Процедуры
- README.md — Описание
Задачи:
- Добавить новую функцию
- Исправить баг
- Изменить конфигурацию
- Провести анализ
Примеры:
# Добавить новую функцию
Read: design/spec.md # понять требования
Read: solution/code/modules/products/crud.py # текущий код
Edit: solution/code/modules/products/crud.py # изменить
Bash: pytest tests/test_products.py # проверить
Дополнительно загружаемые файлы:
- solution/code/* — Весь код
- infrastructure/* — Инфра документация
- Документы из platform/ — Стандарты
Задачи:
- Рефакторинг модуля
- Миграция на новую версию
- Архитектурные изменения
- Полный аудит
Примеры:
# Рефакторинг модуля доставки
Read: solution/code/modules/delivery/* # все файлы модуля
Read: platform/standard.yaml # стандарты
Read: design/spec.md # требования
# [анализ и изменения]
1 → 2 (вниз):
- Спросить подтверждение
- Загрузить дополнительные файлы
- Увеличить контекст
2 → 3 (вниз):
- Спросить подтверждение
- Загрузить весь код
- Максимальный контекст
3 → 2 → 1 (вверх):
- Автоматически
- Освободить контекст
- Вернуться к минимуму
Процедура: platform/procedures/ONBOARD_NEW_PROJECT.md
Шаги:
Определить тип проекта
- APPLICATION / PLATFORM / TEMPLATE / UTILITY
- Определить infrastructure needs
Собрать информацию
- Название, описание
- Технологии
- Связь с инфраструктурой
Создать структуру
bash
mkdir -p projects/{name}/{design,management,solution/code}
Создать обязательные файлы
- CLAUDE.md (из template)
- README.md (из template)
- index.yaml (сгенерировать)
- design/PROJECT.md (описание)
Git commit
bash
git add projects/{name}/
git commit -m "feat: add project {name}"
Обновить связанные документы
- /opt/claude-workspace/index.yaml
- infra/{server}/config.yaml (если нужно)
Проверить результат
- Структура создана
- Файлы на месте
- Git commit выполнен
- index.yaml обновлен
Контекст: Project-agent
Шаги:
Загрузить контекст
bash
Read: projects/{name}/CLAUDE.md
Read: projects/{name}/index.yaml
Понять задачу
bash
Read: design/spec.md
# Уточнить у оператора если нужно
Проверить текущее состояние
bash
git status
Bash: pytest tests/
Выполнить изменения
bash
Read: solution/code/{file}
Edit: solution/code/{file}
Проверить работоспособность
bash
Bash: pytest tests/
Bash: curl http://localhost:PORT
Документировать
bash
Edit: management/changelog.md
Commit (если запрошено)
bash
git add .
git commit -m "feat: description"
Контекст: Orchestrator или Project-agent
Шаги:
Найти инфраструктуру
bash
Read: /opt/claude-workspace/index.yaml
# Найти нужную инфру
Загрузить config
bash
Read: infra/{name}/config.yaml
Проверить usage
- usage: ready → можно подключаться
- usage: project → сначала создать
Получить доступы
bash
# Из config.yaml:
# access.ssh.host
# access.ssh.user
# access.ssh.key_path
Подключиться
bash
ssh user@host
Выполнить задачу на сервере
Документировать изменения
bash
Edit: infra/{name}/config.yaml # если изменилась инфра
Контекст: Orchestrator
Процедура: 10-стадийная миграция
Шаги:
Стадия 1: Инвентаризация
# Что есть сейчас
Read: [current version files]
# Создать inventory.md
Стадия 2: Анализ
# Что нужно изменить
# Создать analysis.md
Стадия 3: Планирование
# Как изменить
# Создать migration-plan.md
Стадия 4: Подготовка
# Создать новую структуру
mkdir -p {new-structure}
Стадия 5: Staging
# Скопировать в staging
cp -r current/ staging/
# Применить изменения в staging
Стадия 6: Валидация
# Проверить staging
pytest staging/tests/
Стадия 7: Миграция
# Переключиться на новую версию
mv current/ archive/old/
mv staging/ current/
Стадия 8: Верификация
# Проверить работоспособность
pytest current/tests/
curl http://localhost:PORT
Стадия 9: Архивирование
# Сохранить старую версию
tar -czf archive/version-old.tar.gz archive/old/
Стадия 10: Финализация
# Очистка и документация
rm -rf archive/old/
Edit: CHANGELOG.md
git commit -m "migrate: to version X"
Чекпоинты:
- После каждой стадии — сохранить состояние
- Возможность отката на любом этапе
- Валидация перед продолжением
1. Создание — Create
- Создание проекта (ONBOARD_NEW_PROJECT)
- Создание компонента
- Создание инфраструктуры
2. Чтение — Read
- Навигация по workspace
- Поиск информации
- Анализ структуры
3. Обновление — Update
- Изменение кода
- Обновление документации
- Миграция версий
4. Удаление — Delete
- Архивирование старых версий
- Очистка временных файлов
- Удаление устаревших проектов
Входные данные:
- Название проекта
- Тип проекта (APPLICATION/PLATFORM/TEMPLATE/UTILITY)
- Инфраструктура (опц)
- Технологии (опц)
Алгоритм:
def create_project(name: str, type: str, infra: str = None):
# Этап 1: Валидация
if project_exists(name):
raise Error("Проект уже существует")
validate_name(name)
validate_type(type)
# Этап 2: Создание структуры
create_folders([
f"projects/{name}/design",
f"projects/{name}/management",
f"projects/{name}/solution/code"
])
# Этап 3: Создание файлов из templates
create_from_template(
"templates/project/CLAUDE.template.md",
f"projects/{name}/CLAUDE.md",
variables={
"PROJECT_NAME": name,
"PROJECT_TYPE": type,
"INFRA": infra or "none"
}
)
create_from_template(
"templates/project/README.template.md",
f"projects/{name}/README.md",
variables={"PROJECT_NAME": name}
)
# Этап 4: Генерация index.yaml
generate_index_yaml(f"projects/{name}/index.yaml", {
"name": name,
"type": type,
"created": today()
})
# Этап 5: Создание PROJECT.md
create_project_md(f"projects/{name}/design/PROJECT.md", {
"name": name,
"type": type
})
# Этап 6: Git commit
git_add(f"projects/{name}/")
git_commit(f"feat: add project {name}")
# Этап 7: Обновление workspace index
update_workspace_index(name, type, infra)
# Этап 8: Возврат результата
return {
"status": "success",
"project": name,
"path": f"projects/{name}/"
}
Выходные данные:
- Структура проекта создана
- Файлы на месте
- Git commit выполнен
- index.yaml обновлен
Задача: Преобразовать @latest в конкретную версию
Алгоритм:
def resolve_symbolic_link(link: str) -> str:
# Этап 1: Проверка кэша
if link in cache:
return cache[link]
# Этап 2: Парсинг ссылки
# @latest → поиск максимальной версии
# @stable → поиск стабильной версии
# @{version} → точная версия
link_type = parse_link_type(link)
# Этап 3: Поиск кандидатов
candidates = find_candidates(link_type)
# Этап 4: Выбор оптимальной версии
if link_type == "latest":
version = max(candidates, key=lambda v: v.number)
elif link_type == "stable":
version = max([v for v in candidates if v.stable],
key=lambda v: v.number)
else:
version = find_exact(candidates, link)
# Этап 5: Валидация и кэширование
validate_version(version)
cache[link] = version
return version
Примеры:
- @latest → v2.0.0
- @stable → v1.5.2
- @v1 → v1.9.3 (latest в ветке v1)
Задача: Загрузить минимальный необходимый контекст
Алгоритм:
def load_context(task_complexity: str):
# Базовый контекст (всегда)
context = load_files([
"CLAUDE.md",
"index.yaml"
])
# Уровень 1: Простые задачи (80%)
if task_complexity == "simple":
return context # 1-2K tokens
# Уровень 2: Средние задачи (15%)
if task_complexity == "medium":
context += load_files([
"design/spec.md",
"management/procedures.md",
"README.md"
])
return context # 5-10K tokens
# Уровень 3: Сложные задачи (5%)
if task_complexity == "complex":
context += load_files([
"solution/code/**/*",
"infrastructure/*",
"platform/standard.yaml"
])
return context # 20-50K tokens
raise Error("Unknown complexity level")
planning — Проектирование
- Есть: design/spec.md
- Нет: solution/code/
- Действия: Обсуждение, планирование
development — Разработка
- Есть: solution/code/
- Статус: Активная разработка
- Действия: Изменения кода, тестирование
testing — Тестирование
- Есть: tests/
- Статус: Проверка функционала
- Действия: Запуск тестов, исправление багов
staging — Предпродакшн
- Развёрнуто: На тестовом сервере
- Статус: Финальная проверка
- Действия: UAT, нагрузочное тестирование
production — Продакшн
- Развёрнуто: На продакшн сервере
- Статус: Работает
- Действия: Мониторинг, поддержка
archived — Архив
- Статус: Не используется
- Расположение: archive/
- Действия: Только чтение
planning → development → testing → staging → production
↓ ↓ ↓ ↓ ↓
└──────────┴───────────┴──────────┴───────────→ archived
Правила переходов:
planning → development
- Условие: spec.md готов
- Действие: Создать solution/code/
development → testing
- Условие: Основной функционал реализован
- Действие: Создать tests/, запустить
testing → staging
- Условие: Все тесты проходят
- Действие: Деплой на staging сервер
staging → production
- Условие: UAT пройден, нагрузочное тестирование ОК
- Действие: Деплой на production сервер
* → archived
- Условие: Проект больше не нужен
- Действие: Переместить в archive/, обновить index.yaml
1. Критичные — Останавливают работу
- Файл не найден
- Синтаксическая ошибка в коде
- Недоступен сервер
- Действие: Немедленно остановить, сообщить оператору
2. Важные — Требуют внимания
- Тест провалился
- HTTP 500 ошибка
- Превышен timeout
- Действие: Сообщить, предложить варианты
3. Предупреждения — Информационные
- Устаревшая зависимость
- Низкая производительность
- Дублирование кода
- Действие: Записать в лог, продолжить
Стратегия 1: Rollback (откат)
try:
apply_changes()
except Error:
rollback_to_checkpoint()
raise
Стратегия 2: Retry (повтор)
for attempt in range(3):
try:
execute_command()
break
except TemporaryError:
wait(2 ** attempt)
continue
Стратегия 3: Fallback (запасной вариант)
try:
use_primary_method()
except Error:
use_fallback_method()
Стратегия 4: Graceful degradation (плавная деградация)
try:
load_full_context()
except MemoryError:
load_minimal_context()
Ответственность:
- Постановка задач
- Принятие решений
- Контроль качества
- Стратегическое планирование
Полномочия:
- Может изменить ВСЁ
- Финальное решение
- Одобрение критичных изменений
Ограничения:
- Нет (полный контроль)
Ответственность:
- Управление workspace на верхнем уровне
- Создание проектов и инфраструктуры
- Координация между проектами
- Запуск специализированных агентов
Полномочия:
- Создавать/удалять проекты
- Обновлять workspace index
- Запускать Project-agent, Infra-agent
- Читать ВСЁ в workspace
Ограничения:
- НЕ изменяет код проектов напрямую
- НЕ работает с внешними API напрямую
- Делегирует детальную работу специализированным агентам
Файл: system/orchestrator.ai.md
Ответственность:
- Работа внутри конкретного проекта
- Изменение кода проекта
- Тестирование и деплой
- Обновление документации проекта
Полномочия:
- Изменять файлы в projects/{name}/
- Читать platform/ (стандарты)
- Читать infra/{server}/ (для деплоя)
- Выполнять команды в контексте проекта
Ограничения:
- Работает ТОЛЬКО в projects/{name}/
- НЕ изменяет platform/
- НЕ изменяет другие проекты
- НЕ изменяет workspace index
- Спрашивает подтверждение перед изменениями
Файл: projects/{name}/CLAUDE.md
Ответственность:
- Создание новой инфраструктуры
- Настройка серверов
- Управление доступами
- Обновление config.yaml
Полномочия:
- Изменять файлы в infra/{name}/
- Создавать IaC код (Terraform, Ansible)
- Выполнять команды на серверах
- Обновлять config.yaml
Ограничения:
- Работает ТОЛЬКО в infra/{name}/
- Применяется только для usage: project
- НЕ изменяет проекты
- НЕ изменяет platform/
- Спрашивает подтверждение перед созданием ресурсов
Файл: infra/{name}/CLAUDE.md (только для usage: project)
Ответственность:
- Правильное использование инструментов
- Оптимизация операций с файлами
- Безопасность операций
- Обучение других агентов
Полномочия:
- Знает все 7 инструментов Claude Code
- Может советовать оптимальные подходы
- Проверяет безопасность операций
Ограничения:
- Не принимает решений о задачах
- Только консультирует по инструментам
Файл: system/claude-code.ai.md
Ответственность:
- Интерфейс с оператором
- Меню навигации
- Восстановление сессий
- Понятный вывод
Полномочия:
- Форматировать вывод
- Предлагать варианты действий
- Сохранять/восстанавливать сессии
Ограничения:
- Не выполняет задачи напрямую
- Только интерфейс
Файл: system/terminal.ai.md
Ответственность:
- Работа с внешними API
- Интеграции с маркетплейсами
- MCP серверы
- Обработка внешних данных
Полномочия:
- Выполнять API запросы
- Трансформировать данные
- Управлять MCP серверами
Ограничения:
- Не изменяет код проектов
- Только работа с API и данными
Файл: system/integrator.ai.md
| Действие | Оператор | Orchestrator | Project-agent | Infra-agent | Claude Code | Terminal | Integrator |
|---|---|---|---|---|---|---|---|
| Создать проект | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Изменить код проекта | ✅ | ❌ | ✅ (свой) | ❌ | ❌ | ❌ | ❌ |
| Создать инфраструктуру | ✅ | ✅ (запускает) | ❌ | ✅ (своя) | ❌ | ❌ | ❌ |
| Обновить workspace index | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Изменить platform/ | ✅ | ⚠️ (редко) | ❌ | ❌ | ❌ | ❌ | ❌ |
| Читать любые файлы | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| API запросы | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| Git commit | ✅ | ✅ | ✅ (свой проект) | ✅ (своя инфра) | ❌ | ❌ | ❌ |
| Деплой | ✅ | ❌ | ✅ (свой проект) | ✅ (своя инфра) | ❌ | ❌ | ❌ |
Легенда:
- ✅ Разрешено
- ⚠️ Разрешено с ограничениями
- ❌ Запрещено
Оператор
↓ (задача)
Orchestrator
↓ (детализация)
Project-agent / Infra-agent
↓ (исполнение)
Результат
↑
Orchestrator
↑
Оператор
Orchestrator → Project-agent
- Условие: Задача касается конкретного проекта
- Действие: Загрузить projects/{name}/CLAUDE.md, делегировать
- Контроль: Получить отчёт о выполнении
Orchestrator → Infra-agent
- Условие: Нужно создать инфраструктуру
- Действие: Загрузить infra/{name}/CLAUDE.md, делегировать
- Контроль: Проверить config.yaml обновлён до usage: ready
Project-agent → Integrator
- Условие: Нужна работа с API
- Действие: Запросить через Orchestrator
- Контроль: Получить обработанные данные
Project-agent → Orchestrator
- Условие: Задача выходит за пределы проекта
- Пример: Нужно обновить platform/standard.yaml
- Действие: Сообщить, вернуть контроль
Infra-agent → Orchestrator
- Условие: Инфраструктура готова
- Пример: Сервер создан, config.yaml обновлён
- Действие: Отчёт, возврат контроля
Любой агент → Оператор
- Условие: Критичная ошибка или неопределённость
- Пример: Конфликт требований, невозможность выполнения
- Действие: Остановить работу, запросить решение
Назначение: Контекст для AI агента
Структура:
# Project: {name}
**Тип:** web-app | service | library | framework
**Статус:** planning | development | testing | production
**Инфраструктура:** @infra-name | none
## Роль
Ты project-agent для проекта {name}.
## Задачи
- Задача 1
- Задача 2
- Задача 3
## Ограничения
- Работать ТОЛЬКО в этой папке
- НЕ изменять platform/
- НЕ изменять другие проекты
## Команды
```bash
# Запуск
tmux new -d -s {name} 'command'
# Остановка
tmux kill-session -t {name}
Сервер: @infra-dev-pro
Ссылка: ../../infra/@infra-dev-pro/config.yaml
---
### A.2 index.yaml (навигация)
**Назначение:** Быстрый поиск файлов в папке
**Структура:**
```yaml
version: "1.0.0"
updated: "2025-11-19"
project:
name: "marketplace"
type: "web-app"
status: "production"
description: "MVP маркетплейс - управление каналами продаж"
files:
CLAUDE.md:
purpose: "Контекст для project-agent"
topics: ["роль", "задачи", "ограничения"]
size: 800
updated: "2025-11-18"
design/spec.md:
purpose: "Спецификация проекта"
topics: ["функции", "API", "интерфейс"]
size: 2000
updated: "2025-11-15"
infrastructure:
server: "@infra-dev-pro"
link: "../../infra/@infra-dev-pro/config.yaml"
summary:
total_files: 25
total_code_lines: 5000
last_commit: "2025-11-18"
Назначение: Метаданные инфраструктуры
Структура (ready):
infrastructure:
name: "DEV-PRO Server"
type: vps
usage: ready
status: active
provider: "Hetzner"
ip: "91.218.142.168"
created: "2025-01-01"
access:
ssh:
host: "91.218.142.168"
user: "root"
key_path: "~/.ssh/id_rsa"
projects:
- name: "marketplace"
path: "/opt/workspace/projects/marketplace/"
type: "web-app"
status: "active"
specifications:
cpu:
cores: 4
ram:
total: "8 GB"
disk:
total: "100 GB"
type: "SSD"
version: "1.0.0"
last_updated: "2025-11-19"
Структура (project):
infrastructure:
name: "New Server"
type: vps
usage: project
status: creating
target:
provider: "AWS"
region: "us-east-1"
lifecycle:
- step: "planning"
status: "completed"
- step: "creating"
status: "in_progress"
- step: "active"
status: "pending"
version: "1.0.0"
last_updated: "2025-11-19"
Команда оператора:
"Создать проект marketplace — веб-приложение на Streamlit для управления каналами продаж Ozon. Инфраструктура: @infra-dev-pro."
Действия Orchestrator:
platform/procedures/ONBOARD_NEW_PROJECT.mdbash
mkdir -p projects/marketplace/{design,management,solution/code}bash
git add projects/marketplace/
git commit -m "feat: add marketplace project"/opt/claude-workspace/index.yamlКоманда оператора:
"Добавить в marketplace функцию экспорта заказов в Excel"
Действия Orchestrator:
projects/marketplace/CLAUDE.mdДействия Project-agent:
bash
Read: solution/code/modules/orders/bash
Write: solution/code/modules/excel_export.pybash
Edit: solution/code/pages/03_Orders.pybash
curl http://localhost:8503
# Проверить HTTP 200Orchestrator → Оператор:
"Функция экспорта в Excel добавлена. Файлы:
excel_export.py, обновлён03_Orders.py. Приложение работает корректно (HTTP 200)."
Команда оператора:
"Создать новый VPS сервер на AWS (us-east-1) для production проектов"
Действия Orchestrator:
bash
mkdir -p infra/@infra-prod-aws/{design,solution/terraform}yaml
infrastructure:
name: "Production AWS Server"
type: vps
usage: project
status: planning
target:
provider: "AWS"
region: "us-east-1"Действия Infra-agent:
bash
Write: solution/terraform/main.tf
Write: solution/terraform/variables.tfbash
cd solution/terraform/
terraform init
terraform plan
# Спросить подтверждение
terraform applyyaml
infrastructure:
usage: ready
status: active
ip: "54.123.45.67"Orchestrator → Оператор:
"Сервер создан. IP: 54.123.45.67. Конфигурация:
infra/@infra-prod-aws/config.yaml"
Workspace — Корневая папка /opt/claude-workspace/
Agent — AI контекст для выполнения задач (Orchestrator, Project-agent, etc.)
Cascade — Каскадная система загрузки контекста (80/15/5)
FSD — Feature-Sliced Design, архитектура компонентов
IaC — Infrastructure as Code (Terraform, Ansible)
Lazy Loading — Загрузка по требованию
Migration — Переход между версиями
Orchestrator — Главный агент управления workspace
Project-agent — Агент для работы внутри проекта
Infra-agent — Агент для создания инфраструктуры
Ready — Готовая инфраструктура (usage: ready)
Project — Создаваемая инфраструктура (usage: project)
Rollback — Откат к предыдущему состоянию
Staging — Тестовая среда
Symbolic Link — Символическая ссылка (@latest, @stable)
Template — Шаблон для создания проектов/компонентов
UAT — User Acceptance Testing
Версия: 2.0.0
Дата: 2025-11-19
Статус: Draft for Review
v2.0.0 (2025-11-19)
- Создан полный документ со всеми 5 частями
- Добавлены приложения (справочники, примеры, глоссарий, чеклисты)
- Интеграция концепций из old-projector v3.9.6
- Структурирование по Platform v1 стандартам
v1.0.0 (планируется)
- После ревью и правок от оператора
- Финальная версия для production
Файл: /opt/claude-workspace/system/docs/ARCHITECTURE_v2.md
Назначение: Концепция архитектуры Platform v2
Базируется на:
- Platform v1 стандартах
- Old-projector v3.9.6 концепциях
- ONBOARD_NEW_PROJECT процедурах
- Реальной структуре workspace
Размер: ~50 KB
Разделы:
1. Философия и принципы (8 измерений, чистота, экономия, безопасность, maintenance)
2. Структурная архитектура (7 уровней, типы проектов, типы инфры, обязательные файлы)
3. Функциональная архитектура (система агентов, каскад контекста, workflows)
4. Процессная архитектура (процедуры, алгоритмы, состояния, ошибки)
5. Ролевая архитектура (роли, полномочия, делегирование, эскалация)
6. Приложения (справочники, примеры, глоссарий, чеклисты)
Целевая аудитория:
- AI агенты (для понимания системы)
- Операторы (для работы с системой)
- Разработчики (для расширения системы)
КОНЕЦ ДОКУМЕНТА