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

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

```bash
set -a; . ./.env 2>/dev/null; set +a
```
Переменные: `GITEA_USER` (кто я), `GITEA_TOKEN` (секрет — **в чат не печатать**), `GITEA_URL`, `GITEA_REPO`.

---

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

Хакатон MedITron, кейс SberMed AI «ИИ-помощник пациента». **Сопровождение восстановления между визитами к врачу** при ПТСР и депрессии (фокус — ветераны СВО и их семьи): мониторинг после обращения + управление приёмом лекарств. Общее ядро + модули `veteran` / `depression` / `family`, включаемые скринингом.
ИИ не ставит диагнозы и не лечит: LLM извлекает данные и формулирует реплики, **риск и алерты решают детерминированные правила**, клинические решения — врач.

**Дедлайн: пн 05.10.2026, 13:00 МСК.** Критерии жюри: работоспособность, функциональность, дизайн, клинико-экономика, клиентский путь.

Язык общения — русский. Код, идентификаторы, коммиты — английский. Тексты для пациента — в `config/texts/`, не в коде.

---

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

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

| Файл | О чём |
|---|---|
| [`docs/info/SPEC.md`](docs/info/SPEC.md) | **Исходная спецификация:** право (152-ФЗ, 323-ФЗ), архитектура, модель данных, шкалы, LLM-контракт, FSM |
| [`docs/info/CLINICAL_MODULES.md`](docs/info/CLINICAL_MODULES.md) | Ядро + модули: шкалы, расписания, триггеры, обоснования |
| [`docs/DECISIONS.md`](docs/DECISIONS.md) | ADR — отступления от SPEC. **При конфликте важнее SPEC** |
| [`docs/product/`](docs/product/) | Идеи команды, демо-персона и сценарий, требования хакатона |
| [`docs/source/`](docs/source/) | Кейс SberMed AI, концепция и CJM (pdf + txt) |
| [`docs/dev/WORKFLOW.md`](docs/dev/WORKFLOW.md) | **Регламент:** зоны, жизненный цикл, worktree, ветки, PR |
| [`docs/dev/GITEA_API.md`](docs/dev/GITEA_API.md) | Gitea API: issue, PR, зависимости |
| [`docs/dev/ISSUE_TEMPLATE.md`](docs/dev/ISSUE_TEMPLATE.md) | Шаблон тела issue |

---

## Guardrails

Мнемоника: **обезличь, проверь безопасность, реши правилом, спроси часы, запиши в аудит.**

| # | Правило | Где |
|---|---|---|
| 1 | В LLM — только текст после `scrub()`, только через `app/llm/gateway.py` | `app/core/privacy.py` |
| 2 | Safety-проверка до LLM на каждом входящем; `acute` → фиксированный скрипт, LLM не вызывается | `app/core/safety.py` |
| 3 | Скоринг и алерты детерминированы, «действия агента» — выход правил (ADR-007) | `app/core/rules.py`, `config/rules.yaml` |
| 4 | Время — только `app.core.clock` (демо-часы, ADR-005) | `app/core/clock.py` |
| 5 | identity и clinical — разные БД, связь через HMAC-токен; clinical-код не импортирует identity | `app/db/` |
| 6 | Каждое обращение врача к данным → `audit_log` | `app/db/audit.py` |
| 7 | Пороги, шкалы, тексты, лексикон — в `config/` (ADR-008) | `config/` |
| 8 | Только синтетика; логи без ПДн и без сырого текста; секреты только в `.env` | — |
| 9 | Никаких зарубежных API: LLM = GigaChat или `mock`; офлайн по умолчанию (ADR-004) | `app/llm/` |
| 10 | Одна задача = одна зона; `make lint && make test` перед PR | `docs/dev/WORKFLOW.md` |

---

## TL;DR — командная работа

1. **`.env` — первым делом.**
2. **Задача = Issue в Gitea.** Нет issue — нет кода.
3. **Зоны:** core / bot / backend / dashboard / devops / clinical / pitch / docs. В занятую чужую не лезь.
4. **Задача = свой worktree** (`.claude/worktrees/<issue#>-<slug>`), ветка от `origin/dev` — до первого изменения. PR в `dev`; `main` — только человек.
5. **Завершил → сразу push + PR**, после зелёного CI можно мержить самому (хакатон).
6. **Лог** — в тело issue (`### YYYY-MM-DD`); архитектурные решения — в `docs/DECISIONS.md`.

---

## Запуск

```bash
cp .env.example .env
make up        # docker compose: postgres + app (API, бот) + dashboard; LLM_PROVIDER=mock по умолчанию
make seed      # синтетические пациенты и демо-сюжет
make lint test
```
Дашборд и демо-консоль: http://localhost:8501 · API: http://localhost:8000/docs

> Telegram используется только для прототипа на синтетических данных; прод-канал — MAX / Госуслуги.