tgit/CLAUDE.md

CLAUDE.md — Руководство для Claude Code

⚡ ПЕРВОЕ ДЕЙСТВИЕ В КАЖДОЙ СЕССИИ

set -a; . ./.env 2>/dev/null; set +a

Переменные: GITEA_URL, GITEA_TOKEN, GITEA_USER, GITEA_REPO, SOURCECRAFT_TOKEN (токены — секрет, в чат не печатать).

Где	Что	Remote
Gitea HSE/tgit	основной: код, issues, PR, ревью	origin
SourceCraft rogachevegorushka/tgit	зеркало (push-mirror из Gitea) + CI/CD	sourcecraft (только чтение)

⛔ В SourceCraft ничего не пушим и не мержим — зеркало перезапишет (ADR-010).

---

Что мы строим

Telegram-бот «git в телеграме» для команды (учебный проект НИУ ВШЭ, курс Python). Вход — только по QR-приглашению. Меню: Коммит (навигация по дереву репозитория загрузок, черновик, сообщение, Push → CI/CD в SourceCraft с уведомлениями) · Статус (контейнеры, health, проверки) · Логи (хвост, свой grep, LLM-агент со стражем) · Алерты (всем участникам, список).

ТЗ: docs/SPEC.md · Архитектура: docs/ARCHITECTURE.md

---

Процесс работы

• Перед кодом — подход в 2–3 предложениях при архитектурных развилках.
• Код по модулям; пользователь проверяет после каждого; комментарии — только когда WHY неочевиден.
• Язык общения — русский.

---

Карта документации

Задачи — в Gitea Issues, не в файлах.

Файл	О чём
docs/SPEC.md	ТЗ: требования, сценарии, критерии приёмки
docs/ARCHITECTURE.md	Компоненты, потоки данных, деплой
docs/DECISIONS.md	ADR: архитектурные решения (что и почему)
docs/QUESTIONS_IDEAS.md	Открытые вопросы, бэклог идей
docs/dev/WORKFLOW.md	Регламент: ветки, коммиты, PR, жизненный цикл задачи
docs/dev/ISSUE_TEMPLATE.md	Шаблон тела issue
docs/dev/GITEA_API.md	Gitea API: issue, PR, зависимости, зеркало
docs/dev/SOURCECRAFT_API.md	SourceCraft API: CI-прогоны, логи, секреты
docs/dev/DEPLOY.md	Деплой: сервер, окружения dev/prod, руками, откат

---

Guardrails

Мнемоника: пусти по приглашению, запри чужой код, не дай LLM команд, спрячь секреты, повтори запрос, держи гейт зелёным.

#	Правило	Где живёт правда
1	Доступ — только участникам. Новый роутер/хэндлер не обходит AccessMiddleware (outer, на message и callback_query); без приглашения — ни одного действия	app/bot/middlewares/access.py, ADR-011
2	Чужой код — только в песочнице tgit-runner. Бот не получает docker.sock напрямую: чтение — через read-only proxy, запуск — через runner с forced command	infra/runner/, ADR-005/006
3	LLM не исполняет ничего. Только JSON по схеме (LogQuery, вердикт стража) → валидация → выполнение ботом в Python; grep — не в shell; логи в LLM не передаются	app/agent/, ADR-007/013
4	Провайдер — за протоколом. Вендорский код только в app/llm/<provider>.py, остальные зависят от LLMProvider	app/llm/provider.py, ADR-008
5	Конфиг типизирован. Только app/config.py (pydantic-settings по подсистемам), без os.getenv вразброс; тексты, пороги, промпты — config/*.yaml	app/config.py
6	Секреты — только в .env. Не логируются, не уходят в LLM, не попадают в git и в чат	.env.example
7	Внешние вызовы — с ретраями. SourceCraft API и Gitea рвут соединения: повторы с задержкой, перед повторным POST проверить, не создалось ли	app/sourcecraft/client.py, docs/dev/*_API.md
8	Схема БД — только миграциями. Изменил модель → alembic revision --autogenerate + ручное ревью (импорты, дубли CHECK); тест дрейфа должен быть зелёным	app/db/, tests/db/test_migrations.py
9	Гейт зелёный: make lint && make test перед PR; порог покрытия (fail_under) только растёт	pyproject.toml
10	В SourceCraft не пушим и не мержим — это зеркало Gitea; .sourcecraft/ и .tgit/ в tgit-uploads правим через шаблон infra/uploads-template/	ADR-010, ADR-014

---

TL;DR — работа

1. Задача = Issue в Gitea. Нет issue — нет кода.
2. Ветка от dev: <type>/<issue#>-<slug>. PR в dev (в Gitea); dev → main — только человек.
3. Гейт зелёный: make lint && make test перед PR; guardrails выше — не нарушать.
4. Завершил → push + PR сразу.
5. Лог выполнения — в issue (### YYYY-MM-DD), архитектурные решения — в DECISIONS.md.
6. Секреты (токен бота, deploy-ключ, ключи LLM) — только в .env, в чат и git не попадают.