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

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

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

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

| Где | Что | Remote |
|---|---|---|
| [Gitea `HSE/tgit`](https://gitea.24studbank.ru/HSE/tgit) | **основной:** код, issues, PR, ревью | `origin` |
| [SourceCraft `rogachevegorushka/tgit`](https://sourcecraft.dev/rogachevegorushka/tgit) | зеркало (push-mirror из Gitea) + CI/CD | `sourcecraft` (только чтение) |

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

---

## Что мы строим

Telegram-бот (учебный проект НИУ ВШЭ, курс Python): принимает `.py`-файлы, коммитит их в отдельный
репозиторий на SourceCraft, где автоматически запускается CI/CD. Бот сообщает статус CI, присылает
алерты о падениях/перегрузке, отдаёт логи и умеет отвечать на вопросы по логам через LLM.

**ТЗ:** [`docs/SPEC.md`](docs/SPEC.md) · **Архитектура:** [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)

---

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

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

---

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

> Задачи — в [Gitea Issues](https://gitea.24studbank.ru/HSE/tgit/issues), не в файлах.

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

---

## TL;DR — работа

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