раздел 05 · шаг 1/7

Шаг 1. Подготовка окружения

Собираем фундамент: пустой репозиторий, структура папок, виртуальное окружение Python, базовые служебные файлы. На этом шаге кода ноль - только инструменты. Зато дальше будет проще.

Что делаем

  • Создаём папку проекта todo-ai
  • Инициализируем git
  • Создаём подпапки backend/ и frontend/
  • Готовим Python venv для бэка
  • Пишем CLAUDE.md, .gitignore, README.md
  • Делаем первый коммит как точку отката

Что должно быть в системе

  • Python 3.11 или новее
  • Node.js 18 или новее
  • pnpm (быстрый менеджер пакетов для фронта)
  • git

Проверка:

python3 --version    # должно быть >= 3.11
node --version       # должно быть >= 18
pnpm --version       # любая 8+ ок
git --version

Если чего-то не хватает - ставьте через homebrew (brew install python@3.12 node pnpm) или официальные инсталляторы.

Создаём структуру

mkdir todo-ai && cd todo-ai
git init

mkdir backend frontend

# Python venv для бэка
python3 -m venv venv
source venv/bin/activate

# Заготовка зависимостей
touch backend/requirements.txt

После этого структура такая:

todo-ai/
├── backend/
│   └── requirements.txt
├── frontend/
└── venv/           # сюда поставятся Python пакеты

.gitignore

Создайте .gitignore в корне:

# Python
venv/
__pycache__/
*.pyc
.pytest_cache/
.coverage
htmlcov/

# Node
node_modules/
dist/
.next/
.turbo/

# Env
.env
.env.local

# OS
.DS_Store
Thumbs.db

# IDE
.vscode/
.idea/

# SQLite база
*.db
*.db-journal

README.md

Минимальный README, чтобы было от чего отталкиваться:

# todo-ai

ToDo с AI-категоризацией задач через Claude API.

## Стек
- Backend: FastAPI + SQLAlchemy 2.0 + SQLite
- Frontend: Vite + React 19 + Tailwind 4
- AI: Anthropic Claude Haiku 4.5
- Docker для деплоя

## Запуск
TODO: будет в следующих шагах

CLAUDE.md

Это ключевой файл для нашего проекта - правила для Claude Code, которые ускорят все следующие шаги. Создайте CLAUDE.md в корне:

# todo-ai

ToDo с AI-категоризацией задач через Claude API.

## Стек
- Backend: FastAPI (async) + SQLAlchemy 2.0 + SQLite
- Frontend: Vite + React 19 + TypeScript + Tailwind 4 + TanStack Query
- AI: Anthropic Claude Haiku 4.5 с prompt caching
- Docker + docker-compose для прод

## Структура
- `backend/app/` - FastAPI код (роуты, модели, сервисы)
- `backend/tests/` - pytest
- `frontend/src/` - React-компоненты
- `infra/` - Dockerfile, docker-compose, nginx-конфиги
- `test/smoke.py` - smoke-тест после деплоя

## Команды
- Backend dev: `cd backend && uvicorn app.main:app --reload`
- Frontend dev: `cd frontend && pnpm dev`
- Tests backend: `cd backend && pytest`
- Tests frontend: `cd frontend && pnpm test`
- Docker: `docker compose up -d --build`

## Конвенции
- Async везде в FastAPI, sync только в utility-функциях
- TS-типы для фронта генерим из `/openapi.json` через openapi-typescript
- Категории задач: work, personal, learning, health, other
- Если Anthropic API недоступен - категория `other`, не падаем
- Pydantic v2 синтаксис: `model_config = ConfigDict(...)`
- В роутерах только парсинг и вызов сервиса, бизнес-логика в `services/`

## Запреты
- Не использовать sync SQLAlchemy
- Не коммитить `.env`, только `.env.example`
- Не использовать deprecated модели Claude (3.x и старее)

Установка базовых Python-зависимостей

В backend/requirements.txt пока пусто. На следующем шаге Claude сам пропишет всё что нужно. Сейчас просто проверьте, что venv активен:

which python3
# должно показать путь внутри venv/bin/python3

Точка сохранения

git add .
git commit -m "step 1: setup project structure and CLAUDE.md"

В случае чего откатиться сюда можно через git reset --hard <hash>. Запишите хеш коммита куда-нибудь, если параноите.

Полезные ссылки