Platform v1 - Структура и принципы

Версия: 2.0.0
Дата: 2025-11-18

Основные принципы

1. Минимизм файлов

Правило: Минимум файлов, максимум структуры

Когда объединять:
- Одна тема
- Загружаются вместе
- < 500 строк

Когда разделять:
- > 500 строк
- Разные части загружаются отдельно
- Разная аудитория (люди vs AI)
- Экономия токенов

2. Папка = контекст, файл = назначение

НЕ ДУБЛИРОВАТЬ контекст в имени:

❌ platform/PLATFORM.yaml
✅ platform/standard.yaml

❌ projects/marketplace/PROJECT.md
✅ projects/marketplace/design/spec.md

❌ system/SYSTEM.md
✅ system/README.md

Папка уже показывает контекст!

3. Суффиксы по типу использования

.ai.md - ТОЛЬКО для AI

system/orchestrator.ai.md
system/terminal.ai.md

• Человек НЕ читает
• Инструкции для агентов

.md - Для людей И AI

system/README.md
system/docs/architecture.md

• Документация
• Описания

.yaml - Конфигурация, данные

index.yaml
platform/standard.yaml
config.yaml

• Структурированные данные
• Метаданные

.template.* - Шаблоны

platform/templates/project.template.yaml

.tmp - Временные файлы

4. Разделение документации и кода AI

Документация (для архитектора):

system/docs/          ← Про систему
platform/docs/        ← Про платформу

• Проектирование
• Обоснования
• История решений

Код AI (для агентов):

system/*.ai.md        ← Контексты агентов
platform/standard.yaml ← Стандарты

• Инструкции для работы
• Правила
• Процедуры

5. Индексация везде

Правило: Каждая папка имеет index.yaml

Формат:

files:
  README.md:
    purpose: "Обзор системы"
    topics: ["архитектура", "агенты"]
    size: 1200
    updated: "2025-11-18"

  orchestrator.ai.md:
    purpose: "Контекст оркестратора"
    topics: ["проекты", "инфра", "управление"]
    size: 2500
    updated: "2025-11-18"

Обновление: ВСЕГДА при изменении файлов

РИСК: Самый критичный - может устареть

6. Каскадирование правил

Наследуются вниз:
- Глобальные правила (формат, подтверждения)
- Стандарты платформы (структура, именование)
- Требования к файлам

НЕ наследуются (изолированы):
- Роли агентов
- Специфика проектов
- Управленческие процедуры

Причина каскада: Единообразие, экономия токенов (не дублировать)

Причина изоляции: Специфика не нужна другим уровням

7. Зарезервированные имена

Корневые файлы (ЗАГЛАВНЫЕ):

CLAUDE.md            ← Точка входа Claude Code
README.md            ← Документация для людей

Метаданные инфраструктуры:

INFRA.yaml           ← В корне infra/{name}/

Конфигурации:

config.yaml          ← Настройки инфры/проекта
index.yaml           ← Индекс папки

Внутри папок - lowercase по назначению:

design/spec.md
management/procedures.md

Стандартная структура

Для системы (system/)

system/
├── docs/                     ← Документация
│   ├── architecture.md
│   ├── structure.md
│   └── agents.md
│
├── README.md                 ← Описание
├── claude-code.ai.md         ← Код AI
├── orchestrator.ai.md        ← Код AI
├── terminal.ai.md            ← Код AI
└── integrator.ai.md          ← Код AI

Для платформы (platform/)

platform/
├── docs/                     ← Документация
│   └── rules.md
│
├── standard.yaml             ← Стандарты
├── procedures/               ← Процедуры
├── templates/                ← Шаблоны
└── agents/                   ← Конфиги исполнителей
    ├── project.yaml
    └── infra.yaml

Для проекта (projects/)

projects/{name}/
├── CLAUDE.md                 ← Для project-agent
├── README.md                 ← Для людей
├── index.yaml                ← Индекс файлов
│
├── design/
│   └── spec.md               ← Спецификация
│
├── management/
│   └── procedures.md         ← Процедуры
│
└── solution/
    └── code/                 ← Код проекта

Для инфраструктуры (infra/)

Тип 1: ready (готовая)

infra/{name}/
├── config.yaml               ← ТОЛЬКО настройки
│   usage: ready
└── access.md                 ← Опционально

Тип 2: project (создаваемая)

infra/{name}/
├── config.yaml               ← Метаданные
│   usage: project
├── CLAUDE.md                 ← Для infra-agent
│
├── design/
│   └── plan.md               ← План создания
│
└── solution/
    └── terraform/            ← Код инфры

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

Сегментация загрузки

CORE (всегда):

CLAUDE.md                     200 токенов

STARTUP (при старте):

index.yaml                    100 токенов
terminal.ai.md                300 токенов (опц)
───────────────────────────
ИТОГО                         600 токенов

ON-DEMAND (по требованию):

system/orchestrator.ai.md     500 токенов
system/claude-code.ai.md      400 токенов
platform/standard.yaml       1000 токенов

Оптимизация

Если файл > 3000 строк:
- Разбить на секции
- Загружать по требованию

Пример:

platform/standard.yaml → platform/standards/
├── hierarchy.yaml
├── naming.yaml
├── structure.yaml
└── agents.yaml

Правила работы с файлами

Создание файлов

ВСЕГДА:
- Обновить index.yaml родительской папки
- Использовать правильный суффикс (.ai.md, .yaml)
- Следовать принципу "папка = контекст"

НЕ создавать без причины:
- Предпочитать объединение
- Дробить только для экономии токенов

Именование

Правила:
- Корневые: ЗАГЛАВНЫЕ (CLAUDE.md, README.md)
- Внутри: lowercase (spec.md, procedures.md)
- По назначению, НЕ по контексту
- Суффиксы по типу

Удаление

ВСЕГДА:
- Обновить index.yaml
- Проверить ссылки на файл
- Документировать причину

Типичные ошибки

❌ Дублирование контекста в имени

platform/PLATFORM.yaml

❌ Забыли обновить index.yaml

Создали файл → index устарел

❌ Слишком много файлов

10+ MD файлов с дублированием информации

❌ Неправильный суффикс

orchestrator.md (должно быть .ai.md)

❌ Путаница docs/ vs код AI

Агент читает docs/ вместо *.ai.md

Чеклист создания нового компонента

Новый агент

• [ ] Создать system/{name}.ai.md (контекст)
• [ ] Добавить в system/docs/agents.md (документация)
• [ ] Обновить system/index.yaml
• [ ] Описать в system/README.md

Новый проект

• [ ] Создать projects/{name}/
• [ ] Создать минимум: CLAUDE.md, README.md, index.yaml
• [ ] Создать структуру: design/, management/, solution/
• [ ] Добавить в корневой index.yaml
• [ ] Связать с инфраструктурой (INFRA.yaml)

Новая инфра

• [ ] Определить тип: ready или project
• [ ] Создать infra/{name}/config.yaml с usage
• [ ] Если project: создать CLAUDE.md и структуру
• [ ] Добавить в корневой index.yaml
• [ ] Двунаправленные ссылки с проектами

Версия: 2.0.0
Дата: 2025-11-18
Статус: Актуальный стандарт