Протокол контекста

Обновлено: 2025-12-21
Активный проект: platform
Активная тема: Архитектура завершена

АРХИТЕКТУРА АГЕНТОВ

Иерархия (утверждено)

L0  —        Человек
L1  ПОЧЕМУ   Диспетчер (простой роутер)
L2  ЗАЧЕМ    Ассистенты:
              ├── Личный (personal) — стратег, ценности
              ├── Бизнес (business) — компания, прибыль
              └── Социальный (social) — общество, импакт
L3  ЧТО      Проектор (projector)
L4  КТО      Специалисты (specialists/):
              ├── business — бизнес-процессы
              ├── technical — IT-проекты
              ├── marketing — маркетинг
              ├── data — аналитика
              ├── design — дизайн
              └── infrastructure — инфраструктура
L5  КАК      Исполнители (workers/):
              ├── coder — код
              ├── infra — серверы
              ├── integrator — интеграции
              └── analyst — анализ
L6  ЧЕМ      Стеки (stacks/):
              ├── fastapi
              ├── scrapy
              └── ...

Структура файлов (утверждено)

system/agents/
├── CLAUDE.md           ← Индекс + триггеры
├── dispatcher.ai.md    ← Диспетчер
├── personal.ai.md      ← Личный ассистент
├── business.ai.md      ← Бизнес ассистент
├── social.ai.md        ← Социальный ассистент
├── projector.ai.md     ← Проектор
├── librarian.ai.md     ← Библиотекарь
│
├── specialists/        ← Специалисты
│   ├── business.ai.md
│   ├── technical.ai.md
│   └── ...
│
├── workers/            ← Исполнители
│   ├── coder.ai.md
│   └── ...
│
├── stacks/             ← Стеки
│   └── ...
│
└── templates/          ← Шаблоны документов

Примечание: Каждый агент может иметь одноимённую папку с дополнениями.

МЕХАНИЗМ ПРОТОКОЛИРОВАНИЯ

Когда писать (утверждено)

• Факт ОТЛИЧАЕТСЯ от мастер-данных
• Факт ДОПОЛНЯЕТ мастер-данные
• После обсуждения вопроса → предложить зафиксировать
• Непонятный факт → тикет для Архитектора

Структура записи (утверждено)

Файлы контекста (утверждено)

ФОРМАТ ДИАЛОГА (утверждено)

1. Claude пишет нумерованные пункты в конце сообщения
2. Оператор отвечает цифрами: 1 3 5 = согласен
3. Цифры = подтверждённые факты → записываются
4. Комментарий к цифре → обсуждаем отдельно
5. После обсуждения → возвращаемся с новыми фактами

ФОНОВЫЙ АРХИТЕКТОР (утверждено)

• Разбирает типовые вопросы в фоновом режиме
• Готовит решения/предложения заранее
• Оператор ежедневно открывает "окно архитектора"
• Много параллельных сессий — учитывать!

ИЕРАРХИЯ ПРАВДЫ (принцип, требует уточнения)

Уровень 1: Мастер-данные (главный документ)
Уровень 2: Документы проекта
Уровень 3: Входные данные (от оператора)
Уровень 4: Вычисленные/найденные (сессия)

Редактировать по зависимостям: сначала мастер, потом зависимые.

ТЕРМИНОЛОГИЯ: ПРОБЛЕМА "ПРОЕКТ"

Проблема (зафиксировано)

Слово "проект" — омоним с 6+ значениями:

Фрактальность (зафиксировано)

"Любая папка в иерархии — это проект со своим проектом (документацией)"

папка/           ← "проект" (сущность)
└── CLAUDE.md    ← "проект" (документация)

Решение (принято)

1. Папка = сущность → называем по ТИПУ (business, site, service, initiative)
2. CLAUDE.md = проект → документация сущности (всегда)
3. Тип = указываем явно в CLAUDE.md или index.yaml

Типы сущностей

СЛОВАРЬ ОПАСНЫХ ТЕРМИНОВ

Требуют 100% уточнения контекста перед использованием.

Критические (5+ значений)

Высокий риск (3-4 значения)

Средний риск (2-3 значения)

Дополнительные (найдены 2025-12-21)

IT-сленг (риск непонимания)

ПРАВИЛО: При использовании опасного термина

1. Определить контекст — в каком смысле используется
2. Уточнить явно — "проект (инициатива)", "клиент (приложение)"
3. Записать в протокол — если контекст важен для сессии

Источники

• Automatic Detection of Ambiguous Terminology
• 8 Commonly Confused IT Terms
• IT-словарь терминов

СИСТЕМА ЗАДАЧ (утверждено 2025-12-21)

Терминология

Принцип: Ticket → Task (одна сущность, разные стадии)

Хранение: Платформа + Проекты

/.queue/                            ← Платформа
projects/{name}/.queue/             ← Проект

Воронка

inbox → triaged → assigned → active → blocked → review → done

Приоритет (importance)

Стандарт: architect/standards/processes/TASK_QUEUE.md

ДЕЛЕГИРОВАНИЕ МОДЕЛЯМ (утверждено 2025-12-21)

Принцип

Рутину — дешёвым моделям, думать — самому.

Как делегировать

Task(subagent_type="Explore", model="haiku")   — поиск
Task(prompt="напиши код...", model="sonnet")   — код

Добавлено в: CLAUDE.md v24.7.0

MONITOR (утверждено 2025-12-21)

Назначение

Агент здоровья системы. Запускается по расписанию (Haiku).

Проверки

Выходы

• Алерты → Telegram (оператору)
• Тикеты → .queue/inbox/ (архитектору)
• Отчёты → .monitor/reports/

Расположение: system/monitor/

SCHEDULER (утверждено 2025-12-21)

Принцип

Один cron → scheduler → все задачи платформы.

* * * * * python3 system/scheduler/run.py

Разделение

Расположение: system/scheduler/

TELEGRAM (утверждено 2025-12-21)

Боты

Структура

system/config/telegram.yaml       ← Токены + chat_id
library/connectors/api/telegram/
├── client.py                     ← TelegramClient
└── __init__.py

Использование

from library.connectors.api.telegram import TelegramClient
tg = TelegramClient.from_config("proektor")
tg.send("operator", "Сообщение")

Интеграции

• Monitor → @aiproektor_bot → operator

BACKUP (утверждено 2025-12-21)

Скрипты

infra/scripts/
├── backup.sh      ← Оркестратор (--db, --etc, --check)
├── backup_db.sh   ← PostgreSQL → S3
├── backup_etc.sh  ← /etc → S3
└── cleanup.sh     ← Безопасная очистка диска

Хранение

/mnt/beget-s3/backups/
├── db/      ← Дампы PostgreSQL (7 дней)
└── etc/     ← Конфиги (30 дней)

Cron (/etc/cron.d/claude-platform)

МАСТЕР-ДАННЫЕ ПРОЕКТА (решено 2025-12-21)

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

projects/{name}/
├── CLAUDE.md          ← Точка входа для агента
├── index.yaml         ← Метаданные + URL
├── PROJECT.md         ← Полное описание бизнеса
├── ARCHITECTURE.md    ← Техархитектура (для сложных)
└── data/
    └── MASTER.md      ← Мастер-данные источников

Иерархия

Принцип

Несколько связанных документов. Минимум: CLAUDE.md + index.yaml.

ПРОЕКТОР (решено 2025-12-21)

Решение

Один универсальный Проектор (L3) + доменные Специалисты (L4)

Обоснование

• L3 (ЧТО) — универсален, не зависит от домена
• L4 (КТО) — доменная специализация
• Один проект может требовать несколько доменов

Архитектура

L3: projector.ai.md (универсальный)
    └── Координирует specialists

L4: specialists/*.ai.md (доменные)
    ├── business.ai.md
    ├── technical.ai.md
    ├── marketing.ai.md
    ├── data.ai.md
    └── design.ai.md

ОТКРЫТЫЕ ВОПРОСЫ

RAG ССЫЛКИ

Версия протокола: 1.3.0