Clipe 'O que há de novo'
Um clipe 'O que há de novo' mostra às pessoas o que uma versão mudou no tempo que leva para passar por ele: um cartão de abertura que faz a mesma pergunta a cada versão e mostra a versão, uma cena por mudança filmada na build real da versão com sua legenda, e um cartão de encerramento que diz onde obtê-lo. As palavras vêm primeiro e são do próprio aprovador. Você filma a partir de um estado semeado e repetível, renderiza com um comando e observa stills da sua própria renderização antes que qualquer pessoa o veja. A especificação permanece no repositório, para que a próxima versão comece a partir desta, e não de uma sessão de edição em branco.
Os fatos do projeto estão em docs/agents/whats-new-clip.md no repositório do usuário: onde estão as notas de versão, como construir e semear a build de lançamento, como capturar esta superfície, o visual, os formatos, onde os clipes são mantidos e quem aprova. Se esse arquivo estiver faltando, siga primeiro o SETUP.md.
A ferramenta é scripts/clip.py. Execute-a como uv run <pasta desta habilidade>/scripts/clip.py <comando>; --help em qualquer comando lista suas flags. Ela precisa de ffmpeg e ffprobe no PATH; uv traz o Pillow. Sem uv, crie um ambiente virtual fora do repositório (python3 -m venv <dir> && <dir>/bin/pip install pillow) e execute a ferramenta com <dir>/bin/python. O formato da especificação e todas as regras que check aplica estão em SPEC.md.
1. Encontrar o que as pessoas notarão
Leia as notas da versão onde o arquivo do projeto indica. Liste cada mudança que uma pessoa verá, ouvirá ou sentirá, cada uma vinculada à sua linha nas notas. Deixe de fora correções que ninguém nota e trabalhos nos bastidores.
Se nada na lista for algo que os usuários notarão, pergunte ao aprovador se esta versão terá um clipe e pare, a menos que ele diga sim.
Feito quando: cada item da lista aponta para uma linha nas notas de versão, ou o aprovador disse que não há clipe para esta versão.
2. Acordar as palavras
Proponha uma legenda por mudança, na ordem em que serão mostradas, a mais forte primeiro. Uma mudança por cena. Uma legenda é um benefício para a pessoa em palavras simples, curta o suficiente para ser lida duas vezes enquanto sua cena é reproduzida (cerca de seis palavras). Onde o aprovador já deu palavras para uma mudança (nas notas, uma mensagem, o 'O que há de novo' no aplicativo), use-as literalmente: a grafia, gramática e capitalização deles.
Pergunte ao aprovador uma vez, com a lista completa e sua recomendação para cada linha, para que uma resposta de uma palavra funcione. Não filme nada antes das palavras serem acordadas: uma legenda reformulada geralmente precisa de uma tomada diferente.
Quando o aprovador reformular uma legenda que o produto também mostra (uma folha 'O que há de novo' no aplicativo, notas de versão da loja), pergunte se esse texto também muda, para que a versão fale com uma só voz.
Feito quando: o aprovador concordou com todas as legendas e você tem cada uma exatamente como acordado.
3. Escrever a especificação
Se a configuração já escreveu a especificação desta versão, preencha esse arquivo. Caso contrário, comece a partir da especificação da última versão, para que o visual, a linha de abertura e o cartão de encerramento sejam mantidos:
clip.py init <versão> --out <pasta da especificação> --from <pasta da especificação>/<última versão>.json
Para um primeiro clipe, use --product "<nome>" em vez de --from. Preencha o caption de cada cena (literalmente da etapa 2), words_by (quem deu as palavras) e um in e out planejados que sejam longos o suficiente para ler sua legenda. Uma mudança sem nada para assistir recebe a cena mais curta que sua legenda permite. Em seguida, execute clip.py check <spec> --words.
Feito quando: check --words imprime check: ok.
4. Filmar cada cena
Filme cada cena de acordo com as regras em FILMING.md, com os comandos de build, seed e captura do arquivo do projeto. Mostre apenas o que esta versão contém: nada atrás de um recurso que ela não entrega, nada da próxima versão.
Se a entrada real através da interface do próprio produto não puder alcançar uma mudança, pare e informe ao usuário: isso é um bug, e um clipe filmado contornando isso prometeria o que as pessoas não podem fazer.
Uma mudança que a captura do projeto não pode filmar (uma visualização de câmera, um segundo dispositivo) é mostrada a partir de um filme mantido: veja "O que a captura não pode filmar" em FILMING.md.
Coloque os filmes na pasta de clipes desta versão, fora do repositório. Defina o source, in e out de cada cena a partir do tempo em que cada etapa foi registrada enquanto era executada, e olhe antes de confiar em uma marcação:
clip.py peek <filme> --from <segundo> --to <segundo> --out <uma pasta temporária nova> --sheet <pasta temporária>/peek.png
Isso mostra o filme entre dois de seus segundos como render o lerá. Nunca extraia esse still com uma busca própria: uma gravação de tela mantém um quadro apenas onde a imagem mudou, então uma busca pousa na próxima mudança, que pode estar segundos depois.
Em seguida, execute clip.py check <spec> --media <pasta de filmes>.
Feito quando: check imprime check: ok com --media apontando para os filmes.
5. Renderizar
clip.py render <spec> --media <pasta de filmes> --out <pasta de clipes>/<produto-em-kebab-case>-<versão>-9x16.mp4
Renderize cada formato adicional que o arquivo do projeto nomeia com --size, como --size 1920x1080. Quando render disser que uma tela é muito pequena para ser lida nesse tamanho (uma tela de telefone em um quadro largo), esse formato precisa de sua própria especificação: veja "Outro formato" em SPEC.md. O som é opcional e nunca carrega a mensagem: a maioria das pessoas assiste sem áudio, então as legendas sozinhas devem contar a história.
Feito quando: render imprimiu Wrote ... para cada formato que o arquivo do projeto nomeia.
6. Passagem do revisor
Extraia stills para uma pasta nova: clip.py stills <clipe> --spec <spec> --every 1 --safe --out <pasta temporária> --sheet <pasta temporária>/sheet.png. Ele escreve um still do meio de cada cartão e cena, um por segundo, e uma folha com todos eles, com as bordas que um feed cobre tingidas. Examine cada um contra REVIEW.md, para cada formato.
Se sua infraestrutura puder iniciar um subagente, entregue esta passagem a um iniciado com um contexto novo, contendo apenas REVIEW.md, a especificação, os stills e a folha: ele vê o que está na tela, não o que você pretendia filmar.
Corrija cada descoberta conforme a tabela de REVIEW.md, depois renderize e extraia os stills novamente. Nunca explique uma imagem errada na entrega.
Feito quando: cada still passa em todos os itens de REVIEW.md e nenhuma correção está pendente.
7. Entregar
Envie ao aprovador o que REVIEW.md em "A entrega" lista, da forma que o arquivo do projeto diz, e peça um OK ou o que mudar. O clipe não é postado e não é anexado a uma versão até que ele diga OK. A postagem é de quem o arquivo do projeto nomeia.
Em um Não OK, leve as alterações deles de volta para a etapa 2 (palavras) ou etapa 4 (imagens) e filme novamente apenas as cenas que mudam. Um Não OK sem motivo: pergunte uma vez o que eles não gostaram antes de cortar as mesmas tomadas novamente.
Feito quando: o aprovador disse OK, ou as alterações deles estão de volta na etapa 2 ou 4.
8. Manter para a próxima versão
A especificação permanece no repositório com as outras alterações da versão. Mantenha os filmes ao lado dos clipes aprovados na pasta de clipes. Adicione cada lição que este clipe ensinou como uma linha abaixo de Lições no arquivo do projeto.
Feito quando: a especificação está no repositório, os filmes estão ao lado dos clipes aprovados e cada nova lição é uma linha em docs/agents/whats-new-clip.md.