Estruturar o projeto de vídeo para o Claude Code operar sem improvisar

#!/usr/bin/env bash
# Completa o projeto video-ia da aula 02 com regras e configuração sem segredos.
# Rode na raiz video-ia. Nada que já existe é sobrescrito.
set -euo pipefail

# O catálogo da aula 01 prova que você está na pasta certa.
test -f config/catalogo.json || {
  printf 'Entre na pasta video-ia antes de continuar.\n' >&2
  exit 1
}

# As pastas de produção vêm da aula 02; aqui entram só as do agente.
mkdir -p .claude/hooks .claude/agents .claude/skills .claude/commands

# Mídia pesada e segredos ficam fora do git: acrescenta só o que faltar.
touch .gitignore
for regra in '.env' '.env.*' '!.env.example' 'midia/' 'audio/' 'renders/' \
  'qa/frames/' 'logs/' 'node_modules/' '.venv/'; do
  grep -Fqx "$regra" .gitignore || printf '%s\n' "$regra" >> .gitignore
done

# Modelo por papel e nomes de variáveis, sem nenhuma chave preenchida.
touch .env.example
for linha in 'MODEL_DIRECTOR=claude-opus-5-5' 'MODEL_COMPOSER=claude-sonnet-5-5' \
  'MODEL_FRAME_REVIEWER=claude-haiku-5-5' 'ELEVENLABS_API_KEY='; do
  grep -q "^${linha%%=*}=" .env.example || printf '%s\n' "$linha" >> .env.example
done

if [ -e CLAUDE.md ]; then
  printf 'CLAUDE.md já existe: compare com o modelo da aula e mescle à mão.\n'
else
cat > CLAUDE.md <<'EOF'
# Projeto de vídeo: Cozinha da Rafa

## O que este projeto entrega
- Receitas em vídeo: um longo 16:9 (1920x1080) e cortes 9:16 (1080x1920), sempre a 30 fps.
- Texto na tela, legendas e relatórios em português do Brasil com acentuação completa.

## Onde ler e onde escrever
Todos os comandos rodam na raiz video-ia; scripts ficam em scripts/.
- briefing/: briefing de cada receita. Leia antes de propor qualquer mudança.
- roteiro/: roteiro aprovado. Só leitura.
- storyboard/: cenas e quadros-chave aprovados.
- midia/raw/: brutos da câmera. Imutáveis: nunca editar, mover, renomear nem sobrescrever.
- audio/: narração, trilha e efeitos gerados por API.
- transcricoes/: transcrições do Scribe em JSON.
- legendas/: arquivos SRT ou VTT.
- composicoes/<receita>/: projetos HyperFrames ou Remotion. Seu código mora aqui.
- qa/frames/<video>/: imagens extraídas com ffmpeg para revisão visual.
- renders/: MP4 de revisão e de entrega. Fora do git.
- logs/: saída de comandos longos, relatórios e logs/<receita>-render.json com versões, comandos e caminhos de cada entrega.
- custos/: custo real de cada chamada paga.

## Ciclo de produção
1. Ler roteiro/ e logs/<receita>-render.json.
2. Compor em composicoes/<receita>/ e rodar o CLI do HyperFrames dentro dessa pasta.
3. Rodar npx hyperframes lint e npx hyperframes check --snapshots.
4. Rodar npx hyperframes preview --background, mostrar o endereço e PARAR até um "aprovado" explícito.
5. Render de revisão: npx hyperframes render --quality draft --output ../../renders/<receita>-draft.mp4
6. Conferir duração, dimensões e fps com ffprobe e extrair quadros para qa/frames/<receita>/.
7. Render de entrega só depois de um segundo "aprovado".
Passar no check não é aprovação estética.

## Modelos
- Direção e roteiro: opus (claude-opus-5-5, padrão do Claude Code).
- Composição em volume: sonnet (claude-sonnet-5-5).
- Triagem de quadros e revisão: haiku (claude-haiku-5-5).
- Fable 5.1 só com pedido explícito (/model fable).

## Serviços pagos
- Antes de qualquer API paga (ElevenLabs, fal, Replicate, Gemini), informe fornecedor, ID exato do modelo, parâmetros, unidade de cobrança e custo estimado, e espere o sim.
- Se preço ou limite não estiver disponível, escreva [conferir] e pare.
- Registre o custo real em custos/.

## Limites do Claude em vídeo
- O Claude não gera nem recebe vídeo. Para revisar, extraia quadros JPEG ou PNG com ffmpeg.
- Não use Sora nem /v1/videos da OpenAI: desligados em 24/09/2026.
- Não adote Veo 3.1 preview do Gemini API como padrão: pode ser desligado a partir de 22/10/2026.

## Segurança e falhas
- Chaves só no ambiente ou em .env. Nunca peça chave no chat nem leia o .env.
- Não execute git add, git commit nem git push: o versionamento é do usuário.
- Ao falhar, informe comando, código de saída e trecho do erro, sem segredos. Não adivinhe a causa.
EOF
fi

# Slash command /render-final: só você dispara; o agente nunca o chama sozinho.
if [ ! -e .claude/commands/render-final.md ]; then
cat > .claude/commands/render-final.md <<'EOF'
---
description: Renderiza a entrega de uma receita depois do check e do "aprovado" do usuário no preview.
argument-hint: [nome-da-receita]
allowed-tools: Bash(npx hyperframes *), Bash(ffprobe *)
disable-model-invocation: true
---
Receita: $ARGUMENTS. Composição em composicoes/$ARGUMENTS/; rode o CLI dentro dessa pasta.
1. Rode npx hyperframes lint e npx hyperframes check --snapshots. Com erro, mostre os achados e pare.
2. Rode npx hyperframes preview --background, mostre o endereço e PARE até um "aprovado" explícito.
3. Render de revisão: npx hyperframes render --quality draft --output ../../renders/$ARGUMENTS-draft.mp4
4. Confira com ffprobe -v error -show_entries stream=width,height,r_frame_rate:format=duration -of json.
5. Peça um segundo "aprovado" e só então: npx hyperframes render --output ../../renders/$ARGUMENTS.mp4
6. Registre versão, comandos e duração em logs/$ARGUMENTS-render.json. Não rode git.
EOF
fi

printf 'Projeto completado em: %s\n' "$PWD"

{
  "permissions": {
    "allow": [
      "Bash(ffprobe *)",
      "Bash(npx hyperframes lint*)",
      "Bash(npx hyperframes check*)",
      "Bash(npx hyperframes preview*)"
    ],
    "ask": [
      "Bash(npx hyperframes render*)",
      "Bash(ffmpeg *)",
      "Bash(python3 *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Edit(./midia/raw/**)",
      "Bash(git push*)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Edit|Write|MultiEdit|NotebookEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/guarda.py\"",
            "timeout": 10,
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

"""Hook PreToolUse do projeto de vídeo. Salve em .claude/hooks/guarda.py.

O Claude Code envia pela entrada padrão um JSON com tool_name e tool_input.
Saída 0 libera a ferramenta. Saída 2 bloqueia, e a mensagem em stderr volta ao
agente como motivo. Saída 1 NÃO bloqueia: por isso todo erro aqui vira 2.
É uma segunda camada, depois das permissões; não é fronteira de segurança.
Se este arquivo sumir ou estourar o tempo, quem bloqueia é o onFailure: block do settings.json.
"""
import json
import os
import re
import sys
from pathlib import Path


def bloquear(motivo: str) -> None:
    print(motivo, file=sys.stderr)
    sys.exit(2)


try:
    dados = json.load(sys.stdin)
except (ValueError, TypeError):
    bloquear("Entrada do hook inválida; operação bloqueada por precaução.")

ferramenta = dados.get("tool_name", "")
entrada = dados.get("tool_input") or {}
raiz = Path(os.environ.get("CLAUDE_PROJECT_DIR", ".")).resolve()
brutos = raiz / "midia" / "raw"

if ferramenta == "Bash":
    comando = entrada.get("command", "")
    # Versionamento é do usuário: staging, commit e push ficam fora do agente.
    if re.search(r"\bgit\s+(add|commit|push)\b", comando):
        bloquear("Versionamento reservado ao usuário. Liste os arquivos alterados e pare.")
    # Apagar, mover ou redirecionar saída para dentro dos brutos.
    if re.search(r"\b(rm|mv|truncate)\b[^;&|]*midia/raw", comando) or re.search(
        r">\s*\S*midia/raw", comando
    ):
        bloquear("midia/raw/ é imutável. Trabalhe numa cópia em composicoes/ ou qa/frames/.")

if ferramenta in {"Edit", "Write", "MultiEdit", "NotebookEdit"}:
    alvo = entrada.get("file_path") or entrada.get("notebook_path") or ""
    caminho = (raiz / alvo).resolve()  # caminho absoluto continua absoluto
    if caminho == brutos or brutos in caminho.parents:
        bloquear(f"Escrita negada em {caminho}: os brutos não mudam.")

sys.exit(0)

#!/usr/bin/env bash
# Simula o que o Claude Code envia ao hook. Nenhum git roda e nenhum bruto é tocado.
set -euo pipefail
# Rode na raiz video-ia; o catálogo da aula 01 prova que é a pasta certa.
test -f config/catalogo.json || { echo "Entre na pasta video-ia antes de continuar." >&2; exit 1; }
export CLAUDE_PROJECT_DIR="$PWD"
motivo="$(mktemp)"

testa() {  # $1 = JSON de entrada, $2 = código esperado, $3 = nome do caso
  set +e
  printf '%s' "$1" | python3 .claude/hooks/guarda.py 2>"$motivo"
  obtido=$?
  set -e
  printf '%-28s saída %s (esperada %s)\n' "$3" "$obtido" "$2"
  [ "$obtido" -eq "$2" ] || { echo "Falhou. Mensagem: $(cat "$motivo")"; exit 1; }
}

testa '{"tool_name":"Bash","tool_input":{"command":"git add ."}}' 2 "git add"
testa '{"tool_name":"Bash","tool_input":{"command":"git commit -m entrega"}}' 2 "git commit"
testa '{"tool_name":"Write","tool_input":{"file_path":"midia/raw/bolo.mov"}}' 2 "escrita no bruto"
testa '{"tool_name":"Bash","tool_input":{"command":"rm midia/raw/bolo.mov"}}' 2 "rm no bruto"
testa '{"tool_name":"Bash","tool_input":{"command":"ffprobe -v error midia/raw/bolo.mov"}}' 0 "ffprobe lendo o bruto"
testa '{"tool_name":"Write","tool_input":{"file_path":"composicoes/intro/index.html"}}' 0 "escrita em composicoes"
testa 'isto não é JSON' 2 "entrada inválida"
rm -f "$motivo"
echo "Os sete casos passaram."