Onboarding для разработчика

Чек-лист «сел за чужую систему — запусти за час». Что должно стоять локально, какие env-переменные, как разложена файловая система, как запустить первый проект, где смотреть результаты и как реагировать на типичные грабли.

1. Что должно стоять локально

Целевая система: macOS (Intel или Apple Silicon). На Linux — теоретически работает, но не тестировалось.

System deps

Python packages

Глобально или в venv — на твоё усмотрение. Скиллы зовут python3 напрямую, поэтому если venv — нужен в активном shell.

pip install \
  google-genai \              # Gemini SDK (постеры, planning, QA, Veo)
  pillow \                    # image processing
  pyyaml \                    # парсинг brand.yaml / project.yaml / preset.yaml
  mutagen \                   # длительность mp3 для VO-sync
  elevenlabs \                # TTS client
  openai-whisper              # транскрипция

# опционально — Higgsfield backend (NEW — для video-clipgen-higgsfield):
pip install higgsfield-client

# опционально, если на M1/M2 хочется быстрее:
pip install faster-whisper

Node packages

Глобально ничего ставить не нужно. Каждый проект, который использует carousel или explainer, на init создаст свою копию Remotion-приложения и сделает локальный npm install. Это занимает 30-60 секунд один раз на проект.

2. Env vars в shell rc

Добавь в ~/.zshrc (или ~/.bash_profile):

export GOOGLE_API_KEY="AIzaSy..."         # обязательная — все Gemini/Veo вызовы
export ELEVENLABS_API_KEY="sk_..."        # обязательная — TTS для voiceover/explainer
export HF_API_KEY="hf_..."                # опц — Higgsfield (video-clipgen-higgsfield, NEW May 2026)
export HF_API_SECRET="hfs_..."            # опц — обязателен вместе с HF_API_KEY
export FB_GRAPH_ACCESS_TOKEN="EAA..."     # опционально — для creative-orchestrator perf-import

После правки — source ~/.zshrc или перезапусти Terminal / Claude Code session.

3. Структура ~/video-projects/

Это базовая папка проектов. У каждого клиента/бренда — своя поддиректория со всем стейтом:

~/video-projects/
├── director.db                 ← shared SQLite БД (v8 schema), общая для всех проектов
├── <project_slug>/             ← один проект клиента
│   ├── project.yaml            ← business info, конфиги скиллов, final_output_dir
│   ├── brand.yaml              ← брендбук: цвета, шрифты, voice tone, VO voice_id
│   ├── brief.md                ← human-readable бриф (для копирайтера)
│   ├── api_keys.db             ← опц. per-project ключи (если не глобальные)
│   ├── references/             ← фото-референсы (product shots, конкуренты, vibes)
│   ├── clips/                  ← Veo-сгенерированные клипы + analyzer-метаданные
│   ├── voiceovers/             ← mp3 от ElevenLabs + транскрипты
│   ├── music/                  ← фоновые треки для роликов
│   ├── videos/                 ← собранные video ads (директор финальный output)
│   ├── posters/                ← статика (creative-poster + multi-aspect outpaint)
│   ├── carousel/               ← карусели (creative-carousel output)
│   ├── carousel-remotion/      ← per-project Remotion app для carousel (bootstrap)
│   ├── explainer/              ← explainer-видео output
│   ├── explainer-remotion/     ← per-project Remotion app для explainer
│   ├── screencasts/            ← raw recordings + cleaned cuts
│   └── out/                    ← top-N финалов после QA/curate (готово к delivery)
└── ...

Дополнительно у некоторых проектов прописан final_output_dir в project.yaml — например performante-ai-agency сливает финалы в ~/Desktop/prfmnt creo/.

4. Структура ~/.claude/skills/

Скиллы — это атомарные «модули» Claude Code, лежат глобально в дотфайл-папке:

~/.claude/skills/
├── video-project-setup/        ← wizard для нового проекта
├── video-orchestrator/         ← top-level dirigент видео-производства
├── video-copywriter/           ← скрипты для роликов
├── video-voiceover/            ← TTS через ElevenLabs
├── video-director/             ← монтаж через ffmpeg
├── video-clipgen/              ← Veo генерация клипов
├── video-analyzer/             ← анализ + import чужих видео
├── video-remotion/             ← motion graphics через Remotion
├── video-motionfx/             ← Remotion-клипы для data viz / abstract
├── video-captions/             ← Whisper + ASS karaoke-субтитры
├── video-reviewer/             ← AI quality review собранного видео
├── video-screencast/           ← cleanup raw recordings, dedupe takes
├── creative-poster/            ← статика через Gemini Image
├── creative-orchestrator/      ← top-level для статики (зеркало video-orchestrator)
├── creative-carousel/          ← Instagram карусели через Remotion
└── creative-explainer-video/   ← длинные narrated видео через Remotion + ElevenLabs

Внутри каждого скилла:

SKILL.md            ← frontmatter (name/description) + MANDATORY TRIGGERS + docs
scripts/            ← CLI-скрипты, которые делают работу
presets/            ← (если применимо) yaml-рецепты
remotion_template/  ← (для carousel/explainer) шаблон Remotion-app для копий

5. Как запустить первый проект

Сценарий: ты сел за чужой Claude Code, хочешь сделать пилотный проект для нового клиента apparatus (поставщик медтехники).

Шаг 1 — создать проект

В Claude Code:

новый проект apparatus

Должен сработать video-project-setup (триггер «новый проект»). Он зайдёт в wizard: спросит niche, geo, услуги, demographics, brand. Создаст:

• Папку ~/video-projects/apparatus/ со всей структурой
• project.yaml с конфигами скиллов
• brief.md — human-readable бриф
• brand.yaml черновик
• Шаблоны creative-reference
• Регистрацию в ~/video-projects/director.db
• Опционально слинкует существующие voices/music из других проектов

Шаг 2 — положить референсы

Кинь фотки в ~/video-projects/apparatus/references/:

• Product-shots (аппарат, кабинет)
• Lifestyle (клиника, врачи, пациенты)
• Конкурентные креативы (для inspiration / OCR)
• Vibe references (mood)

Шаг 3 — добить brief.md

Открой ~/video-projects/apparatus/brief.md и заполни:

• Что за бизнес / продукт
• Целевая аудитория (B2B / B2C, demographics)
• Главное оффер-сообщение, bullets, profits
• Tone of voice (expert / friendly / urgent)
• Конкретные «pain points» и «desired outcomes»

Шаг 4 — прогон video ads

В Claude Code:

сгенерируй 3 ролика для apparatus

Должен сработать video-orchestrator (триггер «сгенерируй»). Цепочка: copywriter → voiceover → director → captions. На выходе — 3 готовых .mp4 с karaoke-субтитрами в ~/video-projects/apparatus/videos/.

Шаг 5 — прогон статики

сделай 5 постеров для apparatus

Должен сработать creative-orchestrator. Прогон: brief enrichment → variants → multi-aspect → QA loop → delivery. На выходе — top-N постеров в ~/video-projects/apparatus/out/posters/ + preview HTML по каждому.

Шаг 6 — карусель

сделай карусель для apparatus на тему "Запусти УВТ-кабинет за 30 дней"

Должен сработать creative-carousel. ПЕРВЫЙ запуск — около 1-2 минут (npm install), последующие — около минуты. На выходе: PNG-секвенция + ZIP + PDF + preview HTML.

6. Где смотреть результаты

7. Где смотреть БД

# открыть sqlite CLI
sqlite3 ~/video-projects/director.db

# базовая ориентация
.tables                              # список таблиц
.schema clips                        # схема конкретной
.headers on
.mode column
select * from projects;              # все проекты в системе
select count(*) from clips;          # сколько клипов в библиотеке (всех проектов)
select count(*) from clips c
  join project_clips pc on pc.clip_id = c.id
  join projects p on p.id = pc.project_id
  where p.slug = 'apparatus';        # клипов в конкретном проекте

Schema v8 — подробнее в отдельной странице. Если коротко: projects + tables со своим контентом (clips, videos, generated_texts, ...) + junction-таблицы project_X для many-to-many между проектами и контентом.

8. Как добавить новый скилл

1. Создай папку ~/.claude/skills/<name>/
2. Положи SKILL.md с frontmatter:

   ---
   name: <name>
   description: |
     Краткое описание + use cases.
     MANDATORY TRIGGERS: триггер1, триггер2, в русском и английском.
     Use this skill whenever ... — финальное пояснение когда зовут.
   ---
   
   # <Name> — заголовок
   
   Полная документация скилла.

3. Сделай папку scripts/ с CLI-скриптами. По соглашению: каждый скрипт принимает --project-dir или --project <slug>, плюс свои флаги.
4. Если скилл пишет в БД — добавь scripts/db.py с CRUD-функциями по своим таблицам. Используй общий scripts/schema.py (копия одинакова между скиллами).
5. Если работаешь с API — добавь scripts/api_keys.py (общий резолвер: flag → project db → env).
6. Если артефакты для агентского ревью — обязателен scripts/present.py для GR-1 preview, см. GR-1.
7. Перезапусти Claude Code session — скиллы подхватываются на старте.

9. Как откатить миграцию схемы БД

Текущая схема — v8. Иногда нужно откатиться на vN (например после неудачной миграции или при разработке новой версии).

Перед миграцией

# Бэкап ВСЕГДА
cp ~/video-projects/director.db ~/video-projects/director.db.v8.bak.$(date +%Y%m%d-%H%M)

Откатить

В системе есть migration-скрипты в ~/video-projects/migrations/ (или у каждого скилла свой). Откат — выполнить reverse-миграцию через migrate.py:

python ~/video-projects/migrations/migrate.py --target-version 7 --rollback

# Или жёстко: восстановить из бэкапа
cp ~/video-projects/director.db.v8.bak.YYYYMMDD-HHMM ~/video-projects/director.db

Что менять в скиллах при изменении schema

У каждого скилла копия scripts/schema.py с определениями таблиц + CRUD-функции. При смене version — синхронизируй копии (sync-скрипт лежит рядом с migrate.py, либо вручную).

10. Куда подавать issue / fix / improvement

Troubleshooting — типичные грабли

Дополнительные ресурсы

• Обзор системы — что система делает в целом
• Multi-project структура — подробнее про ~/video-projects/
• База данных (schema v8) — таблицы, junction-таблицы, миграции
• 7 пайплайнов — high-level flow от брифа до доставки
• Модели · цены · env — справочник по моделям
• GR-1: preview-страницы — global rule про preview HTML
• 16 aesthetic-пресетов — рецепты дизайна для постеров
• Scene/slide типы — атомарные блоки для карусели и explainer