How-to — курс по існуючому проекту

Стан курсу: .practicum/course.md у корені проекту. Один виклик — один крок: створення плану + урок 01, або наступний невідмічений урок. Аргумент (опціонально): фокус-шлях — курс лише по цій підсистемі.

Якщо .practicum/course.md НЕМА — побудуй курс

1. Аналіз проекту

• Зрозумій стек і структуру: точки входу, модулі, залежності між ними.
• З фокус-аргументом аналізуй лише вказану підсистему.
• Порожній проект або нема читних файлів коду → повідом і зупинись.

2. План уроків — еволюція проекту, а не обхід файлів

• Урок = крок розробки: «що б ми написали ЗАРАЗ, якби будували проект з нуля», а не «черговий файл цілком». У зрілому проекті файли великі, бо виросли — курс повторює це зростання, а не друкує результат разом.
• Етапи курсу:
  1. Мінімальне працююче ядро: конфіг ЛИШЕ з полями, потрібними ядру → db → одна модель → схема → main → перший ендпоінт.
  2. Далі кожна підсистема/інтеграція — окремий етап (напр. «інтеграція OpenAI»: нові поля .env/config → клієнт → використання). Порядок етапів — від найбільш центральної підсистеми до периферійних.
• Наскрізні файли (.env, config, models, main) ростуть через КІЛЬКА уроків у різних етапах: у кожному — лише рядки поточного інкременту.
• Код інкременту — РЕАЛЬНІ рядки фінального файла (його підмножина), не вигадані «спрощені проміжні версії». Якщо шматок ядра нечитний без пізнішого коду — розшир інкремент, а не редагуй код.
• Топологія всередині етапу: модуль ПІСЛЯ того, від чого він залежить (.env+settings → db → моделі → схеми → роутери → main).
• Відбір змісту:
  • однотипне (N схожих ендпоінтів/CRUD-ів) → 1–2 представники типу;
  • патерн (generic repository тощо) → сам патерн + приклад використання;
  • моделі та схеми — повністю (основа розуміння проекту), але кожна на своєму етапі;
  • tests/, Dockerfile, CI та інфраструктурні конфіги в курс НЕ входять.
• Кожен урок у межах ліміту з lesson-format.md (2500–4000 символів). Орієнтир курсу: 5–25 уроків.

3. Знахідки

• Погані або застарілі практики у коді: «тут X, сучасно — Y». Чесно, конкретно, з файлами.

4. Підтвердження користувача

• Покажи план + знахідки в чаті. ДОЧЕКАЙСЯ рішення: «вчимо як є» чи «спершу виправити» (виправлення — окрема робота поза цією навичкою; після нього починай аналіз заново).
• Після підтвердження: запиши .practicum/course.md (формат нижче) і одразу згенеруй урок 01 (див. «Генерація уроку»).

Якщо course.md Є — наступний урок

1. Розпарси всі чекбокси (- [ ] / - [x]) у файлі — заголовки секцій можуть бути будь-якою мовою. Жодного чекбокса → повідом, що файл зіпсований, запропонуй видалити його і зупинись.
2. Перший - [ ] — наступний урок. Усі [x] → «курс завершено 🎉»; підкажи: новий курс = видалити .practicum/course.md.
3. Файл редагований руками — вір йому: порядок і склад уроків визначає користувач.

Генерація уроку

1. Прочитай АКТУАЛЬНИЙ код файлів уроку з диска (проект міг змінитись після плану). Файл зник → відміть урок [x] з приміткою (файл зник) і перейди до наступного - [ ].
2. Інкрементний урок бере з файла лише рядки свого інкременту — у file познач частину: «шлях (рядки X–Y)» або «шлях (+OPENAI_*)». Пояснення і нотатки кадруй від етапу: що ми ДОДАЄМО зараз і навіщо воно потрібне саме на цьому кроці розвитку проекту.
3. tree уроку = точні шляхи файлів усіх уроків ВИЩЕ поточного в course.md, без дублів, у порядку уроків. Для уроку 01 — відсутній. treeTotal = кількість унікальних шляхів файлів у ВСІХ рядках уроків course.md (прогрес від усього курсу).
4. Згенеруй урок за ../practicum/lesson-format.md (прочитай його): пояснення, покрокові нотатки, lesson-JSON, перевірка офсетів, збирання HTML.
5. Ім'я файла: course-NN-<slug>.html (NN — номер уроку, slug — латиницею з дефісами).
6. Якщо у «Знахідках» вирішено «вчимо як є» — нотатки уроку чесно згадують кращу практику там, де код її порушує.
7. Відміть урок [x] у course.md.

Формат course.md

# Курс: <назва проекту> — <одне речення, про що він>

Фокус: <шлях або «весь проект»>. Створено: YYYY-MM-DD.

## Знахідки (рішення: вчимо як є)

- ⚠ settings.py: pydantic v1 BaseSettings — сучасно pydantic-settings v2.

## Уроки

### Етап 1 · ядро

- [x] 01 · .env + settings.py (ядро) — ENVIRONMENT і DATABASE_URL
- [ ] 02 · db.py — async engine і фабрика сесій
- [ ] 03 · main.py — FastAPI app + перший ендпоінт

### Етап 2 · інтеграція OpenAI

- [ ] 04 · .env + settings.py (+OPENAI_*) — ключ, модель, таймаут
- [ ] 05 · ai/client.py — клієнт з ретраями

Рядок уроку: - [ ] NN · <файли/тема> — <що вчимо, один рядок>. Підзаголовки етапів опційні; порядок уроків — наскрізний. Рядок уроку МУСИТЬ містити точні шляхи файлів уроку — з них будується дерево проекту (tree) у наступних уроках. Заголовки і тексти course.md — мовою користувача (приклад вище — українською); структура тримається лише на чекбоксах рядків уроків.