jjietay/clayducation

Vídeo explicativo

Você faz um vídeo que ajuda o usuário a aprender um conceito. Você tem uma grande vantagem sobre uma ferramenta nova: você conhece esta conversa e este projeto. Use esse conhecimento.

O motor está em ~/.claude/skills/clayducation/engine/. Neste arquivo, make significa:

node ~/.claude/skills/clayducation/engine/make.mjs <comando> <diretório-do-projeto>

Etapa 0: pergunte primeiro (toda vez que a skill iniciar)

Seja se o usuário digitou /clayducation ou pediu um vídeo em palavras, a primeira coisa que você faz é fazer as perguntas abaixo com AskUserQuestion, com opções clicáveis. Deixe de fora cada pergunta que a mensagem do usuário ou esta conversa já respondem (por exemplo, "como um cinejornal" responde ao visual, e "com música lo-fi" responde à música). Coloque a opção recomendada primeiro e marque-a "(Recomendado)". Faça todas as quatro perguntas em uma única chamada (a ferramenta aceita no máximo 4). Se o tópico em si não estiver claro e nenhuma pergunta for pulada, pergunte primeiro sobre o tópico, em sua própria chamada.

Pergunta	Cabeçalho	Opções (primeira = padrão)
Qual visual o vídeo deve usar?	Visual	Argila 3D: um visual suave de argila, com o mascote silencioso fazendo o trabalho · 2D clássico, misto: um estilo 2D diferente para cada parte · 2D clássico, um estilo: o usuário nomeia (cinejornal, quadro branco, ...)
Para quem é o vídeo e qual a duração?	Espectador	Revisão de exame, padrão: a notação da aula, números trabalhados, pegadinhas de prova, 5 a 6 min · Revisão de exame, aprofundado: o mesmo, 8 a 9 min, cada etapa da derivação · Iniciante, curto: intuição primeiro, menos símbolos, 2 a 4 min · (Outro: o usuário nomeia um espectador e uma duração, por exemplo "atualização para especialista, curto")
Quando devo verificar com você?	Ponto de verificação	Único disparo: volte com o vídeo finalizado · Após o storyboard: mostre o plano e aguarde aprovação · Após o primeiro visual: mostre os primeiros quadros e aguarde
Qual música?	Música	Calma (current): pad suave, sem batida · Lo-fi (lofi): batida leve, mais energia · Nenhuma

Coloque uma opção recomendada primeiro quando a conversa sugerir uma (uma prova na próxima semana: Revisão de exame, aprofundado). Se a mensagem responder apenas metade da pergunta do Espectador (por exemplo "para o meu exame"), mantenha a pergunta e ofereça apenas as opções que concordam com essa metade. Os espectadores são revisão de exame, iniciante e atualização para especialista (rápida e densa); as durações são curta (2 a 4 min), padrão (5 a 6 min) e aprofundada (8 a 9 min). Escreva as respostas em video.json na etapa 4: "_look" (clay ou classic), "_brief": { "viewer": ..., "length": ..., "checkpoint": ..., "style": ... } e "_render": { "music": "current" | "lofi" | false }. Cada etapa posterior, e uma reconstrução, lê isso ali e não pergunta novamente. Se o usuário dispensar as perguntas, use a primeira opção de cada.

Disparo único, a menos que o usuário tenha escolhido um ponto de verificação

Após a etapa 0, faça cada etapa abaixo sem parar e volte apenas com o vídeo finalizado e verificado. Não pergunte "devo continuar?", não mostre rascunhos, não espere entre as etapas. Cada verificação abaixo é sua para executar e agir. As únicas paradas são o ponto de verificação que o usuário escolheu: "Após o storyboard" para após a etapa 7 (mostre o storyboard e o veredito do agente de roteiro, então aguarde), e "Após o primeiro visual" para no primeiro make look da etapa 9 (mostre suas imagens, então aguarde).

O visual que o usuário quer (leia antes da etapa 6)

Argila para coisas que agem, Manim para gráficos, e o mascote está em cada vídeo. Leia styles/clay.md. O usuário escolheu o visual de argila em vez da mistura de estilos antiga para consistência entre os vídeos. Os estilos 2D são um visual clássico opcional; veja a seção abaixo.

• Não force um gráfico em argila (o usuário pediu). Quando uma imagem 2D do Manim ajudar o espectador a entender mais do que a argila (uma curva, uma distribuição, um contorno, uma projeção ou outra geometria em um plano), faça dessa parte uma parte do Manim, no fundo escuro do Manim (styles/math-manim.md). Nunca construa um modelo de argila que copie uma curva matemática: o usuário mandou remover essas. Objetos que agem, e o trabalho físico do mascote, ficam em argila. Um vídeo pode ir de uma parte em argila para uma parte em Manim e voltar, com a mesma cor para a mesma coisa.

• Um visual, muitas partes. O vídeo é dividido em partes de cerca de 15 a 40 s (gancho, cada ideia, seu caso, encerramento). Cada parte tem seu próprio fundo liso, câmera e cenário. Uma ao lado da outra, duas partes nunca compartilham um fundo.

• O mascote faz o trabalho. Ele é silencioso, sem sincronia labial, e o narrador é uma voz sobreposta. Ele anda, puxa, empurra, carrega e desliga coisas com as próprias mãos, então uma força no roteiro é algo que o espectador o vê fazer. O usuário pediu isso depois de um vídeo onde ele apenas ficou e olhou. Ele permanece inexpressivo por padrão, e make check AVISA quando ele fica em um ponto. Varie o trabalho: use um auxiliar de ação diferente em cada parte (carry, knock, press, grip, pointAt, pushOn; veja "Use uma ação diferente" em styles/clay.md). O usuário o achou empurrando em cada parte.

• As coisas devem se conectar. Uma mola alcança sua parede, um pino toca seu mapa, uma mão toca o que segura. O usuário encontrou uma mola que errava sua parede depois que todas as verificações haviam passado. make bake mede cada junção em models.js (JOINS), então adicione novas junções lá e procure por contato nas imagens.

• Apenas nossos próprios modelos. Use o kit em styles/library/clay. Nunca baixe um modelo. Se um vídeo precisar de um novo objeto, adicione-o ao kit com o mesmo visual.

• Cada parte é uma única tomada contínua. Dentro de uma parte não há cortes e nem novos slides: os objetos chegam, se movem e se juntam enquanto a voz fala, e a câmera se move lentamente. Uma parte termina no estado em que a próxima parte começa, ou com um wipe no fundo da próxima parte.

• A imagem explica; o texto apenas nomeia. O texto permanece plano e nítido, em HTML sobre o 3D. Por quadro: um kicker (caixa alta pequena, a parte e uma fonte), um título de no máximo 8 palavras, alguns rótulos de 1 a 4 palavras cada com linhas finas de guia, e no máximo uma linha de legenda na parte inferior. Nunca uma coluna de frases, nunca uma lista de marcadores, nunca uma legenda do que as cores significam. Cerca de 15 palavras na tela no máximo.

• Fórmulas atuam a voz (o usuário pediu isso). Uma fórmula fixa não é melhor do que ler anotações. Construa cada uma com eqn(): os termos chegam conforme são ditos, se movem quando a voz os move, riscam e explodem quando diz cancelar, e saltam apenas quando nomeia algo importante. make look dá uma falha para uma fórmula que fica parada, e para uma frase "cancela" sem nenhum cancelamento na tela. Veja styles/clay.md.

• Movimento físico. As coisas se movem como objetos: um braço alcança, uma bola cai e quica, um bloco cai e se acomoda, um pulso viaja. Nenhuma acumulação de caixas estáticas.

• O mesmo objeto mantém sua cor em todos os vídeos (o robô é sempre laranja, o mapa sempre amarelo).

Se um storyboard quebrar um desses, mude o storyboard antes de escrever código.

Regras rígidas

• Paralelo por padrão (o usuário pediu, 2026-11-09). O que puder rodar ao mesmo tempo, roda: um vídeo de 13 minutos levou 3 horas quando cada quadro foi medido em uma única página do Chrome (um núcleo ocupado, GPU a 10%). O motor agora mede look, collide, review e stable em várias páginas ao mesmo tempo (o workers da renderização: metade dos núcleos, no máximo 8, e apenas quantos a memória livre permitir;), e build executa sheet, stable e review juntos. Quando você adicionar uma etapa que visita quadros, divida-a também em páginas (measureParallel, traceParallel, idParallel em make.mjs). Em seu próprio trabalho: inicie trabalhos independentes juntos (um look e um autoteste, uma renderização Manim e uma verificação), e nunca espere por um trabalho enquanto outro poderia rodar.

• Faça o pensamento aqui, na conversa principal. Você escreve o roteiro, o storyboard e as cenas você mesmo, porque o contexto está aqui. Nunca passe esses passos para um subagente: um subagente começa sem contexto. O agente de roteiro na etapa 7 é a única exceção, e ele começa frio de propósito.

• Nunca apresse a explicação principal. O usuário aprende com esses vídeos. Siga as regras de ritmo em reference/script.md e corrija cada AVISO de ritmo.

• Nunca invente um fato. Cada número, fórmula e afirmação vem de uma fonte que você verificou: o código do usuário, uma folha de dados, uma especificação, um artigo, a documentação. Liste-os em storyboard.md. Relate qualquer coisa que você não pôde verificar.

• "Seu caso" é opcional. Adicione-o apenas quando esta conversa ou projeto realmente tiver um exemplo correspondente (um bug que o usuário encontrou, uma correção, um número medido). Nunca invente um.

• Sem sobreposições. Nenhum visual pode cobrir outro: texto sobre texto, texto sobre um gráfico, ou um gráfico que esconde outro gráfico. Cada rótulo, fórmula, seta e objeto tem seu próprio espaço. check AVISA sobre textos sobrepostos, e review escreve cada sobreposição medida em overlaps.md. Aglomeração é julgamento do usuário, então procure por ela nos quadros em tamanho real. A passagem de ID ajuda: make look adiciona uma imagem das folgas mais apertadas, e AVISA para texto mais próximo que 12 px de outra coisa, texto sobre um desenho, baixo contraste de texto e um modelo que outros escondem. Corrija cada sobreposição antes de make final.

• As legendas têm uma linha. Cada cue tem no máximo 42 caracteres e nenhum dois cues mostram ao mesmo tempo, então um player nunca mostra duas linhas. O motor faz isso; verify relata um cue que quebra a regra. Não mude SUB_MAX em make.mjs para fazer um cue caber.

• O ciclo fechado (o usuário pediu isso, e o motor o aplica). Após cada edição: make look, leia cada imagem que ele lista, corrija o que você vê, e veja novamente. Só então construa. Nunca edite e construa cegamente, porque uma construção é longa e um look leva segundos. Cada imagem tem um dígito de VERIFICAÇÃO no canto superior direito, e os portões só abrem com os dígitos de todas as imagens, em ordem:

  1. Edite. Se você mudou script.md, execute make voice. Se o vídeo tiver partes Manim e você tiver mudado manim_scenes.py ou a voz, execute make manim: make look desenha os quadros do Manim, não os cria.
  2. make look <dir>: ele mede cada cena alterada em cada quadro, e desenha seus quadros próximos e suas partes em movimento. Leia todos eles. Então make look <dir> --ok <dígitos>. make build para sem isso. Uma imagem com os mesmos quadros e rótulos que uma já lida e confirmada mostra LEIA ANTES e não precisa de dígito (--ok - quando cada imagem é lida antes). Leia cada nova imagem; a mesma regra vale para as tiras.
  3. make build <dir>. Ele para em qualquer colisão.
  4. Leia cada tira em build/review/moving.md. Então make look <dir> --moving-ok <dígitos>.
  5. make final <dir>. Ele para se a fonte mudou após o look ou a construção, ou se uma colisão ou uma sobreposição está aberta. Execute cada etapa como seu próprio comando, pare no primeiro erro e confirme que uma edição foi aplicada.

• Cada leitor verifica quadros próximos e partes em movimento. Qualquer agente ou sessão que julgar um vídeo lê os quadros próximos de cada parte editada, e todos os quadros de cada coisa que se move: o mascote e objetos, durante todo o seu movimento. Uma amostra do vídeo não conta: uma mão atravessou uma mesa entre os quadros amostrados.

• Uma nova falha ganha uma barreira de proteção. Quando o usuário encontrar uma falha, primeiro adicione-a a reference/faults.md e a engine/test/selftest.mjs, e confirme que o teste falha nela. Então corrija o vídeo. Não apenas corrija o vídeo. Execute make selftest após cada mudança em uma verificação.

O que o usuário pediu (mantenha estes)

Cada um foi pedido ou escolhido de ouvido. O motor faz a maioria deles automaticamente.

Tópico	O quê	Automático?
Voz	Voz integrada da Chatterbox, desacelerada para cerca de 160 palavras por minuto por engine/tts/slow-reference.wav; cada parágrafo lido de uma vez para que o tom se mantenha	sim
Pausas	cada ponto final exatamente 0,6 s, cada vírgula no máximo 0,3 s, definido a partir da pontuação do roteiro	sim; voice AVISA se uma pausa não pôde ser colocada
Más tomadas	uma parte cujas palavras diferem do roteiro (verificação Whisper) é regravada com uma nova semente, até 3 vezes; a melhor tomada é mantida	sim; AVISA se ainda estiver errada
Trechos rápidos	uma cláusula mais de 1,3 vezes o ritmo usual do vídeo (palavras de símbolos contam em dobro) é regravada; o usuário achou "lambda v é v, escalado por lambda" muito rápido	sim; AVISA "rápido": dê a ela sua própria frase curta e um [pause]
Números negativos	leia "negativo", nunca "menos"	voice para com um ERRO
Palavras repetidas	"um um" ganha uma vírgula ("um, um"), ou a voz escorrega	sim
Escrita	parágrafos conectados; [pause] apenas onde uma ideia termina ou uma animação toca. Rejeitado: uma pausa após cada frase, frases entrecortadas, voz rápida, voz esticada (abafada), Kokoro	você, veja reference/script.md
Música	audível, constante, cerca de 13 dB abaixo da voz (musicVolume 0,37; o usuário aumentou 3 dB de 0,26), ducking suave; duas faixas aprovadas, current (padrão) e lofi. Rejeitado: bombeamento alto-baixo, música muito baixa para ouvir, 4 outras faixas	sim; você escolhe a faixa, veja SOUND.md
Efeitos sonoros	o kit em engine/sfx.mjs, aprovado de ouvido; o whoosh de entrada 4 dB abaixo dos outros acentos (o usuário o achou um pouco alto). Ligado para novos vídeos (_render.sfx: true), desligado para antigos	você adiciona s.sfx nos cues; o motor os mistura
Áudio	48 kHz estéreo	sim; verify verifica
Legendas	suaves, nunca queimadas; o mpv do usuário as mostra pequenas (sub-scale=0,7)	sim
Uma linha de legenda	uma linha por cue, no máximo 42 caracteres, nenhum dois cues ao mesmo tempo. O usuário viu duas linhas no vídeo 1 do conjunto ROS 2	sim; verify relata um cue que quebra
Sem sobreposições	nenhum texto ou gráfico cobre outro	check AVISA para textos, overlaps.md e sua lista de verificação de quadros para o resto
Visual	um visual de argila 3D com o mascote silencioso e nossos próprios modelos; partes Manim no fundo escuro para curvas e gráficos (o usuário pediu: não force um gráfico em argila)	sim; make look desenha os quadros do Manim, as partes de argila usam o kit