surfaces/docs/claude-code-guide.md

Гайд по Claude Code для разработки surfaces-bot

Что такое Claude Code

Claude Code — это CLI-инструмент который запускается в терминале внутри твоего проекта. Он читает файлы, пишет код, запускает команды. Главное отличие от чата — он видит весь проект и действует автономно.

Запускается так:

cd surfaces-bot
claude "твоя задача"

---

Агенты и когда их использовать

В проекте настроены специализированные агенты в .claude/agents/. Claude Code сам выбирает нужного если ты пишешь @имя в запросе.

Агент	Когда	Пример
@researcher	Нужно разобраться как что-то работает	"как работает Forum Topics в aiogram?"
@architect	Нужно принять архитектурное решение	"как хранить маппинг chat_id → room_id?"
@core-developer	Писать core/ и platform/	"реализуй core/protocol.py"
@tg-developer	Писать Telegram-адаптер	"реализуй обработчик /start"
@matrix-developer	Писать Matrix-адаптер	"реализуй создание Space"
@reviewer	Проверить код перед PR	"проверь adapter/telegram/"

---

Базовые команды

Простая задача (без агента)

# Небольшое изменение — быстрее без агента
claude "добавь поле platform_user_id в ChatContext в core/protocol.py"

Задача через агента

# Агент читает нужную документацию сам
claude "Use @tg-developer to implement adapter/telegram/handlers/auth.py
based on docs/telegram-prototype.md auth flow"

Вопрос без изменений

claude "объясни как работает m.space.child в Matrix"
# или просто интерактивно:
claude  # запускает интерактивный режим

---

Параллельная разработка двух ботов

Главная идея: два терминала, два worktree, два агента одновременно.

Шаг 1 — инициализация (один раз)

cd surfaces-bot
git init
git add . && git commit -m "init"

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

Шаг 2 — сначала ядро (в main)

# В основной папке — core/ должен быть готов до адаптеров
claude "Use @core-developer to implement core/protocol.py and platform/interface.py
and platform/mock.py based on docs/surface-protocol.md and docs/api-contract.md"

Дождись — это фундамент. Остальное на нём строится.

Шаг 3 — параллельно адаптеры (два терминала)

Терминал 1:

cd .worktrees/telegram
claude "Use @tg-developer to implement the auth flow from docs/telegram-prototype.md.
Start with adapter/telegram/handlers/auth.py and adapter/telegram/states.py"

Терминал 2 (одновременно):

cd .worktrees/matrix
claude "Use @matrix-developer to implement the auth flow from docs/matrix-prototype.md.
Start with adapter/matrix/handlers/auth.py and adapter/matrix/space.py"

Они работают в разных папках — не мешают друг другу.

Шаг 4 — смёрджить когда готово

cd surfaces-bot  # вернуться в main
git merge feat/telegram-adapter
git merge feat/matrix-adapter

---

Экономия токенов (важно для Pro)

Правило 1: Haiku для исследований

# @researcher использует Haiku — дёшево
claude "Use @researcher to find examples of aiogram Forum Topics creation with code samples.
Save findings to docs/research/telegram-forum-topics.md"

# НЕ делай так (Sonnet на простой вопрос — дорого):
claude "Use @tg-developer to research how Forum Topics work"

Правило 2: точный контекст

# Хорошо — агент читает один конкретный файл
claude "Use @tg-developer to implement adapter/telegram/keyboards/settings.py.
Read docs/telegram-prototype.md section 'Настройки' for the button structure"

# Плохо — агент читает весь проект зря
claude "Use @tg-developer to implement keyboards"
# (агент начнёт читать всё подряд)

Правило 3: не запускай ревью на каждый коммит

# Ревью — только перед merge в main
claude "Use @reviewer to review all changes in adapter/telegram/ before merging"
# НЕ после каждого файла

Правило 4: маленькие задачи без агента

# Просто правка — без агента быстрее и дешевле
claude "в adapter/telegram/keyboards/confirm.py замени текст кнопки с 'Да' на '✅ Подтвердить'"

Правило 5: не больше двух Sonnet одновременно

# Можно (Haiku + Sonnet):
# Терминал 1: claude "Use @researcher ..."   ← Haiku
# Терминал 2: claude "Use @tg-developer ..."  ← Sonnet

# Можно (два Sonnet в разных worktrees):
# Терминал 1: cd .worktrees/telegram && claude "Use @tg-developer ..."
# Терминал 2: cd .worktrees/matrix   && claude "Use @matrix-developer ..."

# Слишком много (три Sonnet):
# Терминал 1: claude "Use @core-developer ..."
# Терминал 2: claude "Use @tg-developer ..."
# Терминал 3: claude "Use @matrix-developer ..."  ← стоп, подожди

---

Типичные сценарии с примерами

Сценарий А: начало с нуля

# 1. Исследование (Haiku, дёшево)
claude "Use @researcher to find matrix-nio examples of Space creation and room management.
Save to docs/research/matrix-spaces.md"

# 2. Уточнение архитектуры (если что-то неясно)
claude "Use @architect to clarify: should ConfirmationRequest timeout be handled in
core/handler.py or in each adapter separately? Update docs/surface-protocol.md"

# 3. Ядро
claude "Use @core-developer to implement core/protocol.py based on docs/surface-protocol.md"
claude "Use @core-developer to implement core/session.py and core/auth.py"
claude "Use @core-developer to implement platform/interface.py and platform/mock.py
based on docs/api-contract.md"

# 4. Адаптеры параллельно (два терминала)
# T1: claude "Use @tg-developer to implement auth flow in adapter/telegram/"
# T2: claude "Use @matrix-developer to implement auth flow in adapter/matrix/"

Сценарий Б: добавить новую фичу в оба бота

Например, команда !status / /status:

# 1. Убедиться что в core есть нужные структуры
claude "Use @architect to check if StatusRequest is needed in core/protocol.py
or can reuse existing structures. Read docs/surface-protocol.md"

# 2. Добавить в core если нужно
claude "Use @core-developer to add status handling in core/handler.py"

# 3. Оба адаптера параллельно
# T1: claude "Use @tg-developer to implement /status command in
#     adapter/telegram/handlers/settings.py"
# T2: claude "Use @matrix-developer to implement !status command in
#     adapter/matrix/handlers/settings.py"

Сценарий В: что-то сломалось

# Диагностика — без агента, просто спроси
claude "pytest tests/adapter/telegram/test_auth.py провалился с ошибкой:
AttributeError: 'NoneType' has no attribute 'session_id'
Посмотри core/session.py и adapter/telegram/handlers/auth.py и скажи в чём причина"

# Починить точечно
claude "в core/session.py метод get_session возвращает None если сессия не найдена,
но в adapter/telegram/handlers/auth.py это не обрабатывается — исправь"

Сценарий Г: ревью перед merge

# Запускать только когда фича готова
cd .worktrees/telegram
claude "Use @reviewer to review all files changed in this worktree (adapter/telegram/).
Check against docs/telegram-prototype.md and docs/surface-protocol.md"

---

Интерактивный режим

Когда нужно работать итеративно — запусти без задачи:

cd surfaces-bot
claude

Откроется REPL. Можно:

> покажи структуру core/protocol.py
> добавь поле metadata в IncomingMessage
> запусти pytest и покажи результат
> что изменилось в последних 3 коммитах?

Полезно когда задача неясная или нужно исследовать.

---

Флаги которые пригодятся

# Работать в конкретном worktree
cd .worktrees/telegram && claude "..."

# Не трогать файлы, только смотреть (безопасно)
claude --no-write "объясни как работает converter.py"

# Продолжить предыдущую сессию
claude --continue

# Запустить с конкретной моделью (если хочешь Haiku без @researcher)
claude --model claude-haiku-4-5-20251001 "быстрый вопрос про aiogram"

---

Частые ошибки

Агент начал читать весь проект → прерви (Ctrl+C), переформулируй точнее:

# Плохо
claude "Use @tg-developer to implement settings"

# Хорошо
claude "Use @tg-developer to implement adapter/telegram/keyboards/settings.py —
кнопки главного меню настроек из docs/telegram-prototype.md раздел 'Главное меню настроек'"

Агент пишет не в ту папку → явно укажи путь:

claude "Use @matrix-developer to create adapter/matrix/space.py with SpaceManager class"

Кончились токены в середине задачи → задача сохраняется частично, продолжи:

claude --continue "продолжи реализацию, остановился на методе create_chat"

Агент предлагает архитектурное решение вместо кода → перенаправь:

claude "Use @architect to decide: [вопрос]. После решения Use @tg-developer to implement it"