CLAUDE.md

Язык документации

CLAUDE.md и вся внутренняя документация ведутся на русском языке. Технические термины, идентификаторы кода, названия инструментов и команд остаются в оригинале. При добавлении новых разделов не смешивать языки — пишем по-русски.

Контекст проекта

LearnFlowAI — образовательная платформа на базе AI. Основной стек: LangGraph-агент, FastAPI backend, React/TypeScript frontend, PostgreSQL.

Проект следует AIDD (AI-Driven Development): разработчик выступает архитектором — определяет контракты и архитектуру; LLM-агент реализует на основе подготовленного документационного контекста. Вся документация живёт в doc/ — читай её, прежде чем делать предположения.

Структура проекта

uv workspace monorepo — у каждого пакета свой pyproject.toml и свои зависимости. Корневой pyproject.toml — это workspace root, а не запускаемый пакет.

Python-команды запускаются из директории пакета (там, где лежит соответствующий pyproject.toml), а не из корня проекта. Цели Makefile делают это автоматически.

Жёсткие правила

Эти правила действуют для каждого изменения кода. Обоснование («почему») каждого правила задокументировано в doc/tech/conventions.md; здесь — краткие формулировки.

• Миграции БД: изменения схемы проходят через alembic revision --autogenerate против запущенной БД. Миграции, написанные вручную, допускаются только для DML/data-миграций или DDL, недоступного autogenerate, — с заголовком # Manual migration: <reason> и одобрением архитектора. «БД не запущена» — не причина писать миграцию руками: запусти БД.
• Импорты: только на верхнем уровне. Локальный импорт внутри функции требует комментария # lazy: <reason> или # circular: <reason>. Правило PLC0415 контролируется ruff.
• Интерфейсы: по умолчанию typing.Protocol. abc.ABC — только когда в базовом классе есть общая реализация.
• Состояние на уровне модуля: никаких module-level синглтонов. Состояние живёт в app.state (FastAPI), в замыканиях (callbacks/processors вне request scope) или в DI для тестов.
• Env vs константы: значения, зависящие от окружения, секреты и операционные настройки — в Settings(BaseSettings). Бизнес-инварианты остаются в коде. Добавление env-переменной означает одновременное обновление Settings, .env.example, .env.local.example и docker-compose.yml.
• Раскладка workspace: packages/ — для общих библиотек (импортируются другими пакетами); services/ (и исторический backend/) — для самостоятельных runtime'ов. Dockerfile лежит рядом с pyproject.toml пакета; build context — корень репозитория.
• Git и lifecycle итерации: перед любой git-операцией, меняющей историю или ветки (commit, push, merge, создание ветки/worktree, смена статуса итерации в tasklist), прочитай doc/tech/conventions.md § Git (включая подраздел «Lifecycle итерации») и действуй по ней — не по памяти. Там единственный источник правды: flow веток и PR, прямой commit в develop, cloud merge-policy, последовательность статусов 📋→🚧→✅ относительно push/merge. Статус ✅ Done ставится только после явного апрува архитектора о завершённости итерации.

Документация

Исследуя кодовую базу под задачу, начинай с архитектурных документов в doc/tech/, а не с исходного кода. Документы описывают интерфейсы, контракты и потоки на правильном уровне абстракции для проектных решений. Код — деталь реализации: используй его, чтобы проверить частности, не покрытые документацией.

Перед правкой кода в нетривиальной задаче открой doc/tech/conventions.md. Жёсткие правила выше — краткая версия; conventions.md — источник истины по остальному (логирование, нейминг, типы, env-workflow, workflow миграций). Прочитай нужный раздел вместо того, чтобы гадать. Доменные конвенции (БД, API, agent runtime, frontend) вынесены в doc/tech/conventions/ и подгружаются при работе в соответствующем домене — указатель в шапке conventions.md.

Документация описывает текущее состояние — без временных метапометок. Никогда не оставляй в архитектурных документах маркеры итераций и истории: «реализовано в feat-XXX», «будет переделано в feat-YYY», «отложено в feat-ZZZ», «(as-is, июнь 2026)». Планы живут в тасклистах, история — в артефактах итераций; в документах такие пометки гниют (номера итераций сдвигаются, даты устаревают) и создают второе место, которое надо синхронизировать. Констатируй факты прямо («структура отступает от FSD: ...»), не обещая будущих работ. Исключение: архитектор явно поручил оставить такую пометку.

Исправляй дрейф на месте. Если, работая над любой задачей, замечаешь рядом некорректность — документ противоречит коду (неверное расположение модуля, отсутствующая таблица, несуществующий файл/класс), неконсистентный нейминг, нарушение стиля диаграмм — исправь её в рамках своего изменения, не проходи мимо. Предусловие: стопроцентная уверенность, что исправляешь на правильное, — сверься с кодом (grep, сабагент для контекста), а когда уверенность недостижима, вынеси вопрос архитектору вместо догадки. Исправления идут тем же коммитом или отдельным, но всегда упоминаются в отчёте.

В облачных сессиях (Claude Code on the web и аналоги) действует отдельная merge-policy: агент доводит фичу до feature-ветки, push + PR в develop, merge — за архитектором локально. См. doc/tech/conventions.md § Cloud sessions.

Агентам в OpenAI Codex Cloud дополнительно подгрузить skill codex-cloud-bootstrap (runtime policy: Python 3.12, docker-less путь, localhost services). Настройка Codex Environment UI для человека: doc/tech/setup/codex-cloud.md.

Обсуждая архитектуру, визуализируй компоненты, слои и потоки данных, чтобы архитектор мог дать качественную обратную связь, видя полную картину. Не жди, пока попросят. В чате — ASCII-диаграммы; в документах — Mermaid. Паттерн диаграмм (слои как полупрозрачные подложки, палитра проекта, верификация связей по коду через grep/сабагента, проверка рендера на тёмной теме) — см. conventions.md § Mermaid Styling.

Начинай с doc/index.md. Ключевые точки входа по темам:

doc/
├── idea.md              # Проблема, ICP, JTBD, границы продукта
├── vision.md            # Архитектура системы, стек, критерии MVP
├── product/             # Use cases, roadmap, scope по версиям
├── tech/
│   ├── backend.md           # Слои, API, персистентность, конфигурация
│   ├── frontend.md          # Экраны, компоненты, state, интеграция с API
│   ├── auth.md              # JWT + refresh-токены, rate limiting, interceptor
│   ├── streaming.md         # Протокол SSE, события, отмена
│   ├── agent-runtime.md     # Граф LangGraph, tools, skills, контекст, MCP
│   ├── knowledge-sphere.md  # Память проекта, хранилище, fuzzy patch, REST API
│   ├── user-memory.md       # Custom instructions, память агента, персонализация
│   ├── prompt-management.md # Langfuse-промпты, dev/prod, seed/sync
│   ├── observability.md     # Langfuse-трейсинг, учёт затрат, feedback loop
│   ├── conventions.md       # Git flow, нейминг, качество кода, документация (ядро)
│   ├── conventions/         # Доменные конвенции: db, api, agent, frontend
│   ├── setup/               # Мануалы настройки dev/cloud-окружений
│   └── adr/                 # Architecture Decision Records
├── research/            # Исследования технологий, deep-dive, анализ подходов
├── reference/           # Справочные материалы: паттерны, доменные справочники
├── security/            # Модель угроз + архитектура защиты (architecture.md)
└── tasks/               # Тасклисты и итерации

Ключевые команды

Используй цели Makefile — не сырые shell-команды.

Конвенции Makefile

Makefile — канонический интерфейс к проекту. Предпочитай make <target> набору сырых команд.

Если цели не хватает или она неудобна — улучшай Makefile, а не гоняй сырые команды раз за разом. Очевидные исправления (опечатки, неверные флаги) можно вносить сразу. Неочевидные изменения (новые цели, модификации workflow) требуют одобрения архитектора.

Разовые команды, которые не будут переиспользоваться, можно запускать напрямую.

Инструменты качества кода

Линтеры и форматтеры — quality gate проекта: работай с ними, а не в обход них.

Когда проверка падает:

• Разберись в первопричине — определи, это реальная проблема в коде или ложное срабатывание инструмента.
• Реальная проблема — исправь в коде.
• Ложное срабатывание или недостающее правило — обсуди с архитектором, нужно ли корректировать конфигурацию правил.
• Никогда не добавляй слепых подавлений (# noqa, # type: ignore) без ясного обоснования. Подавление реальных проблем сводит на нет смысл инструментов.

Изменения правил (включение, отключение, настройка) всегда идут через архитектора.

Актуальность инструментов и библиотек

Не полагайся на training data для быстро развивающихся инструментов. Проверяй по этим источникам (в порядке приоритета):

1. Установленные пакеты — Python inspect, docstrings, сигнатуры
2. Skills — langgraph-patterns, uv-package-manager и т.д.
3. MCP — docs-langchain для актуальной документации LangGraph
4. firecrawl — официальная документация, PyPI, GitHub

Проект использует чистый LangGraph (без LangChain-обёрток). Всегда проверяй API LangGraph через источники выше.

Skills

Используй установленные skills, когда задача попадает в их домен. Skills несут актуальные специализированные знания за пределами training data.

Если не уверен, покрывает ли skill текущую задачу, — проверь доступные skills, прежде чем продолжать.

Политика выбора skills, роли, отклонённые skills и отложенные кандидаты — см. doc/tech/skill-map.md.

Конвенции логирования

Backend: structlog.get_logger(), стиль keyword-args: logger.info("event", key=value). Никогда logging.getLogger(__name__).

Frontend: import { logger } from "@/shared/lib/logger" вместо console.*.

Семантика уровней, стиль, антипаттерны — см. conventions.md.

Sandbox и сеть

Sandbox изолирует сеть для каждой bash-команды (--unshare-net). Команды внутри sandbox не могут подключаться к localhost-сервисам (порты Docker, dev-серверы, базы данных). Это ожидаемое поведение — не проблема Docker или сети.

Для всего, что требует сетевого доступа к локальным сервисам, используй цели Makefile — они выполняются вне sandbox через excludedCommands. Для разовой диагностики (psql, curl) автоматически сработает sandbox escape hatch.

Границы агента

Агент не принимает архитектурные решения самостоятельно. Архитектура, новые компоненты, интерфейсы, выбор технологий — только после явного одобрения архитектора.

Когда решение очевидно следует из существующей документации — действуй. Когда есть хоть какое-то сомнение — сначала спроси. Лишний вопрос стоит дёшево; несанкционированное архитектурное решение — дорого.

Параллельная разработка

Несколько агентов могут одновременно работать над разными фичами в отдельных worktree. Канала связи между собой у них нет.

Размещение worktree и lifecycle итерации — см. doc/tech/conventions.md § Git → «Lifecycle итерации»: worktree создаётся соседней директорией (../learnflow-ai-wt-<feature_name>, никогда внутри репозитория) после отметки 🚧 в develop. Там же — полная последовательность статусов относительно push/merge.

Если наблюдаешь неожиданное поведение — занятый порт, самопроизвольно перезапускающиеся сервисы, файлы, меняющиеся вне твоих правок, — остановись и эскалируй архитектору. Не пытайся разруливать инфраструктурные конфликты самостоятельно. Координацию между агентами ведёт архитектор.

Как объяснять

Когда я что-то расписываю — задачу, план, разбор, ответ — цель в том, чтобы архитектор понял, а не в том, чтобы я выгрузил структуру источника. Документы, из которых я беру материал (tasklist, DoD, спека), уже сложены под хранение; пересказывать их в той же форме — значит перекладывать на читателя работу по извлечению смысла. Поэтому я переписываю материал в объяснение, а не зеркалю его:

• Сначала суть, потом детали. Первая фраза говорит, что это и что мы делаем, — целиком и простыми словами. Пути к файлам, оговорки, частные случаи идут после и только те, что нужны для дела. Читатель получает картинку до того, как тонет в подробностях.
• Глаголы вместо номинализаций. «Ищу скиллы и рисую диаграмму», а не «skill discovery и построение диаграммы». Действие называется глаголом — тогда видно, кто что делает. Отглагольные существительные превращают объяснение в техзадание.
• Проза, когда задача — объяснить. Таблицы и вложенные заголовки хороши для справки и сравнения, а не для первого понимания. Объясняю — пишу абзацами; за структуру берусь, когда данные действительно табличные.

Это не про «короче» — детали важны. Это про порядок и форму: понимание вперёд, структура по необходимости.