Dev

.claude/CLAUDE.md

@@ -0,0 +1,129 @@
+# Правила работы над проектом
+
+Эти правила определяют, как Claude сотрудничает с пользователем над форком
+курса `ai-engineering-from-scratch`. Хранятся в git, чтобы синхронизироваться
+между устройствами. Активная ветка — `dev`, все остальные ветки мержатся в неё.
+
+## Язык
+
+- Основной язык диалога — русский.
+
+## Структура урока курса
+
+Каждый урок курса лежит в `phases/<NN-phase>/<NN-lesson>/` и содержит готовые
+папки от автора курса:
+
+- `code/` — эталонный код упражнений (принадлежит upstream-репозиторию курса).
+- `docs/` — `en.md` (оригинал) + `ru.md` (наш русский конспект).
+- `outputs/` — артефакты выполнения (если есть).
+- `quiz.json` — вопросы к уроку.
+
+**Рабочий код, который Pavel пишет руками во время прохождения, кладётся в
+подпапку `my/` в корне урока:** `phases/<phase>/<lesson>/my/`.
+
+**Почему отдельная папка, а не в `code/`:** `code/` принадлежит апстриму курса.
+Если в будущем понадобится подтянуть обновления курса через `git pull` от форка,
+свои файлы в `code/` создадут конфликты по именам. `my/` — независимая
+территория Pavel'а, апстрим её не трогает.
+
+**Применяется к:** урокам курса в `phases/`. Не относится к общей `scratch/` —
+там продолжают жить не-курсовые черновики (refresher-планы, общие эксперименты).
+Старые `scratch/lesson-NN/` (созданные на уроках фазы 0 до 2026-05-23) не
+переносим — это исторический след.
+
+## Выполнение команд
+
+### Правило 1: Все команды и установки выполняет пользователь
+
+Пользователь сам запускает все команды и устанавливает зависимости. Claude
+выдаёт команду и объясняет, что она делает и зачем — но не выполняет её.
+
+**Применяется к:**
+- установке пакетов (`pip install`, `apt install`, `npm install`, `winget install`, и т.п.);
+- настройке окружения (создание venv, переменных окружения, конфигов вне репо);
+- запуску скриптов, тренировок, сервисов, контейнеров;
+- любой команде с побочными эффектами на систему вне репо;
+- git-операциям с удалёнными ветками (push, pull, fetch, force-push).
+
+**Не применяется к:** read-only инспекции состояния репо (чтение файлов,
+`git status`, `git log`, `ls`, `grep`) — Claude делает это сам, чтобы понять контекст.
+
+**Формат выдачи команды:**
+1. Сама команда — в кодовом блоке.
+2. Одна фраза: что она делает.
+3. Где запускать: `PowerShell` / `Cursor bash` / `WSL` / `внутри репо` и т.п.
+4. Если команд несколько — нумерованный список, по одной команде на пункт.
+
+## Окружение и доступ к файлам
+
+Сессия Claude запускается в **Claude Desktop на Windows**. Claude Desktop при
+создании локальной сессии требует выбрать папку, и UNC-путь к WSL в его
+диалоге не работает. Поэтому держим **два клона** одного и того же репо:
+
+- **Windows-клон** — `C:\Users\<USER>\Desktop\ai-engineering-from-scratch`.
+  Точка привязки сессии. Рабочая директория Claude по умолчанию.
+  **Только для чтения и структурной справки**, в нём ничего не править.
+- **WSL-клон** — `/home/<user>/ai-engineering-from-scratch` в WSL Ubuntu.
+  **Канонический клон**. Здесь пользователь реально работает, отсюда идут
+  все коммиты и пуши.
+
+Имя WSL-пользователя и дистрибутива зависят от машины — не хардкодить.
+
+Полная процедура настройки на новой машине: см. [`setup.md`](setup.md).
+
+### Протокол работы с двумя клонами
+
+- **По умолчанию** (общие вопросы, чтение файлов, инспекция структуры) —
+  Windows-клон, обычные `Read`/`Grep`/`Glob` по локальным путям. Быстро,
+  без моста через WSL.
+- **Когда пользователь говорит «в WSL» / «посмотри в WSL» или упоминает
+  Linux-путь** — переключаюсь на WSL-клон.
+- **Когда нужно текущее состояние** (свежий `git status`, последние коммиты,
+  только что отредактированный файл) — иду в WSL-клон, потому что Windows-
+  зеркало может отставать.
+- **Любые правки файлов — только в WSL-клон** через UNC. Никогда не редактирую
+  Windows-клон, чтобы он не становился «второй версией правды».
+- **Команды с побочными эффектами** — по Правилу 1, пользователь сам в
+  WSL-терминале Cursor.
+
+### Как Claude обращается к WSL-клону
+
+| Операция | Способ |
+|---|---|
+| Прочитать / отредактировать / создать файл | UNC-путь `\\wsl$\<DISTRO>\home\<USER>\ai-engineering-from-scratch\…` через `Read` / `Edit` / `Write` |
+| Read-only shell-инспекция (`git status`, `ls`, `grep`, `cat`) | `wsl bash -c "cd ~/ai-engineering-from-scratch && <команда>"` |
+| Команды с побочными эффектами (commit, push, install, скрипты) | По Правилу 1 — выдать команду, не запускать |
+
+### Синхронизация Windows-клона
+
+После пуша из WSL Windows-клон отстаёт от `origin/dev`. Когда расхождение
+заметное (новые файлы, переименования, изменения в `.claude/`), пользователь
+обновляет зеркало:
+
+```
+git -C "$env:USERPROFILE\Desktop\ai-engineering-from-scratch" pull
+```
+- **Где:** PowerShell. (Эквивалент в Cursor bash:
+  `git -C ~/Desktop/ai-engineering-from-scratch pull`.)
+
+### Подводные камни
+
+- `wsl --cd <linux-path> <cmd>` из Git Bash на Windows **не работает**: Git Bash
+  транслирует Linux-путь в Windows-путь, и `wsl` получает мусор. Использовать
+  форму `wsl bash -c "cd ~/<path> && <cmd>"` с `cd` внутри quoted-строки.
+- Имя дистрибутива не всегда `Ubuntu` (бывает `Ubuntu-24.04`, `Debian` и т.п.).
+- При записи через UNC line endings сохраняются как есть. Файлы репо должны
+  оставаться с LF.
+
+### При старте на незнакомой машине
+
+В первой же команде получить параметры WSL:
+
+```
+wsl -l -q                                            # имя дистрибутива (первая строка = default)
+wsl bash -c "whoami"                                 # имя WSL-пользователя
+wsl bash -c "ls -d ~/ai-engineering-from-scratch"    # склонирован ли репо
+```
+
+Из этого собрать UNC `\\wsl$\<DISTRO>\home\<USER>\ai-engineering-from-scratch\…`
+и работать. Если репо не склонирован — идти в [`setup.md`](setup.md).

.claude/setup.md

@@ -0,0 +1,181 @@
+# Памятка: настройка проекта на новой Windows-машине
+
+Эти шаги мы прошли один раз вместе. Этот документ — чтобы быстро повторить
+их на любой Windows-машине, с которой будем работать. Делается всё тобой
+в терминале и GUI; Claude только подсказывает и проверяет.
+
+## Prerequisites (должно быть на машине)
+
+- Windows 10 build 19041+ или Windows 11 (для WSL2).
+- **Cursor** (Windows GUI) — где живёт редактор.
+- **Claude Desktop** (Windows GUI) — где запускается Claude.
+- **Git for Windows** (Git Bash) — нужен на старте, до настройки WSL.
+
+## Шаги
+
+### 1. WSL2 + Ubuntu
+
+Проверить, что есть:
+
+```powershell
+wsl --status
+```
+- **Где:** PowerShell.
+
+Если WSL не установлен или нет дистрибутива:
+
+```powershell
+wsl --install -d Ubuntu-24.04
+```
+- **Где:** PowerShell **от администратора**.
+- После установки потребуется ребут.
+- На первом запуске Ubuntu попросит создать UNIX-пользователя и пароль
+  (строчные латинские буквы, без пробелов).
+
+### 2. Базовая проверка Ubuntu
+
+```bash
+whoami && pwd && uname -a && ls -la ~
+```
+- **Где:** Ubuntu shell.
+- В выводе `uname -a` должно быть `microsoft-standard-WSL2`.
+- Запомнить имя пользователя — оно понадобится для UNC-путей.
+
+### 3. Git identity в WSL
+
+Проверить:
+
+```bash
+cat ~/.gitconfig
+```
+
+Если пусто или нужна правка — настроить:
+
+```bash
+git config --global user.name "PavelEgorov-ru"
+git config --global user.email "<твой email на GitHub>"
+git config --global init.defaultBranch main
+git config --global pull.rebase false
+```
+- **Где:** Ubuntu shell.
+
+### 4. SSH-ключ для GitHub
+
+Проверить, есть ли уже:
+
+```bash
+ls -la ~/.ssh/
+```
+- Ищем `id_ed25519` (или `id_rsa`) и одноимённый `.pub`.
+
+Если ключа нет — сгенерировать:
+
+```bash
+ssh-keygen -t ed25519 -C "<твой email>"
+```
+- **Где:** Ubuntu shell.
+- На все вопросы — Enter (без passphrase) или задать passphrase по желанию.
+
+Показать публичный ключ:
+
+```bash
+cat ~/.ssh/id_ed25519.pub
+```
+- Скопировать вывод и добавить на https://github.com/settings/ssh/new
+  (вручную через браузер; Claude в этом не помогает).
+
+Проверить, что GitHub принимает:
+
+```bash
+ssh -T git@github.com
+```
+- На вопрос про fingerprint при первом подключении ответить `yes`.
+- **Успех:** `Hi PavelEgorov-ru! You've successfully authenticated...`.
+
+### 5. Склонировать форк и переключиться на `dev`
+
+```bash
+cd ~ && git clone git@github.com:PavelEgorov-ru/ai-engineering-from-scratch.git
+```
+- **Где:** Ubuntu shell. Клон ляжет в `~/ai-engineering-from-scratch`
+  (Linux-FS, не `/mnt/c/...`).
+
+```bash
+cd ~/ai-engineering-from-scratch && git checkout dev
+```
+- Создаст локальную ветку `dev`, отслеживающую `origin/dev`.
+- На `dev` лежат правила (`.claude/CLAUDE.md`) и эта памятка.
+
+### 6. Cursor + WSL
+
+В Cursor (Windows GUI):
+
+1. **Поставить расширение WSL.** `Ctrl+Shift+X` → искать `WSL` → ставить
+   расширение от **Anysphere** с описанием «Open any folder in the
+   Windows Subsystem for Linux».
+2. **Открыть пустое окно.** `Ctrl+Shift+N` (`File → New Window`) — чтобы
+   не цеплять текущий workspace.
+3. **Подключиться к WSL.** В новом окне: `Ctrl+Shift+P` →
+   `WSL: Connect to WSL` → Enter. В левом нижнем углу должно появиться
+   `WSL: Ubuntu`.
+4. **Открыть папку.** `File → Open Folder` → ввести
+   `/home/<твой WSL-юзер>/ai-engineering-from-scratch` → Enter →
+   `Yes, I trust the authors`.
+
+### 7. Финальная проверка WSL-клона
+
+В терминале нового Cursor-окна (он откроется в репо):
+
+```bash
+pwd && git status && git log --oneline -2
+```
+- Ожидаем: путь `/home/<user>/ai-engineering-from-scratch`, ветка `dev`,
+  `nothing to commit, working tree clean`, верхний коммит —
+  `chore(claude): add project working rules` (или новее).
+
+### 8. Параллельный Windows-клон (anchor для Claude Desktop)
+
+Claude Desktop при создании локальной сессии требует выбрать папку и
+не работает с UNC-путями к WSL в этом диалоге. Поэтому держим **второй
+клон того же репо в Windows** — только как точку привязки сессии.
+
+В PowerShell (Windows):
+
+```powershell
+cd $env:USERPROFILE\Desktop
+git clone git@github.com:PavelEgorov-ru/ai-engineering-from-scratch.git
+cd ai-engineering-from-scratch
+git checkout dev
+```
+- **Где:** PowerShell или Cursor bash на Windows.
+- Использует SSH-ключ Windows (или HTTPS). Если ключ Windows ещё не привязан
+  к GitHub — добавить аналогично шагу 4, но на стороне Windows.
+
+В этом клоне **не работаем**. Все правки идут в WSL-клон. После пушей из
+WSL — синхронизация:
+
+```powershell
+git -C "$env:USERPROFILE\Desktop\ai-engineering-from-scratch" pull
+```
+- **Где:** PowerShell.
+
+## Что после этого делает Claude
+
+- В Claude Desktop при создании сессии указывается **Windows-клон**
+  (`C:\Users\<USER>\Desktop\ai-engineering-from-scratch`) — UNC-путь к WSL
+  в диалоге выбрать нельзя.
+- Claude по умолчанию работает с Windows-клоном для чтения и инспекции
+  структуры.
+- Когда нужны актуальное состояние или правки, Claude переключается на
+  **WSL-клон**:
+  - имя дистрибутива и пользователя получает через
+    ```
+    wsl -l -q
+    wsl bash -c "whoami"
+    ```
+  - читает/правит файлы по UNC `\\wsl$\<DISTRO>\home\<USER>\ai-engineering-from-scratch\…`;
+  - shell-команды — `wsl bash -c "cd ~/ai-engineering-from-scratch && …"`.
+- Команды с побочными эффектами Claude выдаёт пользователю — тот запускает
+  их в WSL-терминале Cursor.
+
+Подробности — в `.claude/CLAUDE.md`, раздел «Окружение и доступ к файлам».

.gitignore

@@ -38,9 +38,11 @@ Thumbs.db
 *.swo
 *~
 .idea/
-.vscode/
 *.log
 
+.vscode/.history/
+.vscode/*.code-workspace
+
 data/
 models/
 checkpoints/

.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.fixAll.ruff": "explicit",
+      "source.organizeImports.ruff": "explicit"
+    }
+  },
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+  "ruff.nativeServer": "on"
+}