ElebobaandClaude Opus 5.5
8508405b0f
Refs #21 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
82 lines
6.5 KiB
Markdown
82 lines
6.5 KiB
Markdown
# 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-бот «git в телеграме» для команды (учебный проект НИУ ВШЭ, курс Python). Вход — только по QR-приглашению.
|
||
Меню: **Коммит** (навигация по дереву репозитория загрузок, черновик, сообщение, Push → CI/CD в SourceCraft с уведомлениями) ·
|
||
**Статус** (контейнеры, health, проверки) · **Логи** (хвост, свой grep, 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-прогоны, логи, секреты |
|
||
|
||
---
|
||
|
||
## 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 не попадают.
|