surfaces/CLAUDE.md

Surfaces team — Lambda Lab 3.0

Telegram и Matrix боты для взаимодействия пользователя с AI-агентом Lambda.

Правило №1: не быть ждуном

Платформа (SDK от Азамата) ещё не готова. Это не блокер.

• Все вызовы платформы — через platform/interface.py (Protocol)
• Реализация сейчас — platform/mock.py (MockPlatformClient)
• При подключении реального SDK — меняем только platform/mock.py
• Архитектурные решения принимаем сами, фиксируем в docs/api-contract.md

---

Архитектура

surfaces-bot/
  core/
    protocol.py      — унифицированные структуры (IncomingMessage, OutgoingUI, ...)
    handler.py       — ядро: IncomingEvent → OutgoingEvent (общее для всех ботов)
    session.py       — управление сессиями и чатами
    auth.py          — AuthFlow
    settings.py      — SettingsAction

  adapter/
    telegram/        — aiogram адаптер
      converter.py   — aiogram Event → IncomingEvent и обратно
      bot.py         — точка входа
      handlers/      — aiogram роутеры
      keyboards/     — инлайн-клавиатуры
      states.py      — FSM состояния
    matrix/          — matrix-nio адаптер
      converter.py   — matrix-nio Event → IncomingEvent и обратно
      bot.py         — точка входа
      handlers/      — обработчики событий

  platform/
    interface.py     — Protocol: PlatformClient (контракт к SDK)
    mock.py          — MockPlatformClient (заглушка)

  docs/              — вся документация
  tests/             — pytest тесты
  .claude/agents/    — конфиги агентов

Подробно об унификации: docs/surface-protocol.md Telegram функционал: docs/telegram-prototype.md Matrix функционал: docs/matrix-prototype.md

---

Агенты

Агент	Когда запускать	Модель	Токены
@researcher	Изучить API, найти примеры	Haiku	~дёшево
@architect	Спроектировать решение	Sonnet	~средне
@tg-developer	Писать код Telegram-адаптера	Sonnet	~средне
@matrix-developer	Писать код Matrix-адаптера	Sonnet	~средне
@core-developer	Писать core/ и platform/	Sonnet	~средне
@reviewer	Проверить код перед PR	Sonnet	~средне

Важно (Pro-лимиты): не запускай больше двух Sonnet-агентов одновременно. Haiku можно запускать параллельно сколько угодно.

---

Стратегия параллельной разработки

Два бота разрабатываются параллельно, но через общее ядро.

Порядок работы

1. core/ — сначала (однократно, все ждут)
   @core-developer пишет protocol.py, handler.py, session.py, auth.py, settings.py

2. platform/ — сразу после core/
   @core-developer пишет interface.py и mock.py

3. adapter/telegram/ и adapter/matrix/ — параллельно
   @tg-developer  →  adapter/telegram/
   @matrix-developer  →  adapter/matrix/
   Не пересекаются по файлам — можно одновременно в разных терминалах.

Что можно делать одновременно (разные терминалы)

# Терминал 1 — Telegram адаптер
claude "Use @tg-developer to implement adapter/telegram/handlers/start.py"

# Терминал 2 — Matrix адаптер (параллельно)
claude "Use @matrix-developer to implement adapter/matrix/handlers/start.py"

Что нельзя делать одновременно

• Два агента в одном файле
• @core-developer параллельно с @tg-developer или @matrix-developer (core/ должен быть готов до адаптеров)
• Больше двух Sonnet-агентов одновременно (Pro-лимит)

---

Git worktree workflow

Каждая фича в отдельном worktree — адаптеры не мешают друг другу:

# Создать worktrees для параллельной работы
git worktree add .worktrees/telegram -b feat/telegram-adapter
git worktree add .worktrees/matrix   -b feat/matrix-adapter

# Работать в каждом независимо
cd .worktrees/telegram && claude "Use @tg-developer to ..."
cd .worktrees/matrix   && claude "Use @matrix-developer to ..."

# Смержить когда готово
git checkout main
git merge feat/telegram-adapter
git merge feat/matrix-adapter

---

Команды запуска

# Установить зависимости
uv sync

# Запустить тесты
pytest tests/ -v

# Запустить только тесты Telegram
pytest tests/adapter/telegram/ -v

# Запустить только тесты Matrix
pytest tests/adapter/matrix/ -v

# Запустить только тесты ядра
pytest tests/core/ -v

# Запустить Telegram бота
python -m adapter.telegram.bot

# Запустить Matrix бота
python -m adapter.matrix.bot

---

Переменные окружения

cp .env.example .env

Никогда не коммить .env.

---

Экономия токенов (Pro-лимиты)

• Исследования → всегда @researcher (Haiku), не Sonnet
• Точечные правки в одном файле → напрямую без агента
• Ревью → только перед PR, не после каждого коммита
• Длинный контекст → дай агенту конкретный файл, не весь проект
• Если агент "завис" в рассуждениях → прерви, переформулируй задачу точнее