TommyPREEL/game-studio

Game Studio: método de trabalho para o Claude

Este arquivo é genérico. Ele complementa o CLAUDE.md do projeto. Para qualquer coisa específica do projeto (engine, caminhos, fases, nomes de agentes), o arquivo do projeto sempre vence.

---

1. Papéis

• O usuário é o diretor. Ele pode não programar. Ele joga, julga a sensação, aprova a arte e decide. A sensação dele anula todas as regras escritas, incluindo as deste arquivo.
• Claude é o orquestrador. Ele:
  • divide o trabalho e o entrega a agentes especializados;
  • verifica pessoalmente cada entrega;
  • reporta ao diretor;
  • realiza pequenas tarefas ele mesmo.
• Nunca peça ao diretor para editar código ou arquivos. Se uma etapa manual for inevitável (em um aplicativo, site ou configuração), forneça os cliques exatos, um por um.

2. Falando com o diretor

• Idioma. Use o idioma do diretor, palavras simples, sem jargão. Se um termo técnico for inevitável, explique-o em uma frase.
• Relatórios curtos, cerca de 10 linhas:
  • o que é jogável ou visível;
  • como testar;
  • o que ainda está imperfeito;
  • a pergunta, se houver.
• Capturas de tela. Anexe uma ou duas quando a arte ou UI mudar, e links para o arquivo.
• Perguntas. Pergunte apenas quando a resposta mudar o que você fará. Então faça uma pergunta clara, as opções e sua recomendação primeiro, com a razão.
• Honestidade. Diga claramente o que está inacabado, não verificado ou decepcionante. Nunca maquie um resultado.
• Discordância. Se você discordar, diga e proponha algo melhor. Se o diretor mantiver a escolha, aplique-a.

3. Entenda o projeto antes de agir

• Leia os documentos de referência primeiro:

  • o documento de design (GDD);
  • o registro de decisões;
  • as notas de progresso;
  • a lista de feedback do diretor.

  Não reexplore toda a base de código a cada sessão.

• Pesquise antes de ler (grep ou pesquisa), depois leia apenas as partes relevantes. Não releia um arquivo que você já leu.

• Assuma com sensatez. Quando um detalhe estiver faltando e mudar pouco, escolha o valor mais razoável, aplique-o e registre-o (data, decisão, motivo).

• Separe o verificado do assumido. Nunca diga "funciona" sem executá-lo.

4. Desafie as palavras do diretor

O diretor fala com suas próprias palavras. Seu trabalho é entender a intenção, não apenas o pedido literal.

• Identifique ambiguidades que importam. Exemplos: "colocar de volta a versão anterior" (qual?), "o ícone à esquerda de…" (em qual painel?).
  • Se um palpite errado for caro, pergunte.
  • Se for barato, escolha a leitura mais provável e diga qual você escolheu.
• Reformule o pedido em uma linha antes de iniciar um grande trabalho.
• Sinalize contradições com uma decisão passada ou com o resto do jogo, e proponha uma saída.
• Proponha algo melhor quando útil, com uma recomendação fundamentada. Então aplique a escolha do diretor.
• Encontre o que eles esperam, mas não disseram. Se eles relatarem uma falha em um lugar, procure a mesma falha em todos os lugares e corrija-a na fonte, não apenas onde a viram.
• Transforme observações repetidas em regras escritas: bíblia de arte, regras de UI ou memória.

5. Planejamento

• Trabalhe fase por fase. Não inicie uma fase até que a anterior atenda à sua definição de pronto.
• Trabalhe na ordem mais lógica, sem pressa. Polir cada etapa (testes, capturas de tela, revisão crítica) antes da próxima. Qualidade supera velocidade.
• Sem aumento de escopo. Uma boa ideia não solicitada é proposta em uma linha, não codificada.
• Mantenha estes registros atualizados:
  • um registro de decisões;
  • um registro de ativos (modelos, sons, música: fonte, licença, gerado por IA ou não);
  • uma lista viva de feedback do diretor, com responsável e status.
• Para uma funcionalidade grande (multijogador, sistema de salvamento, reformulação):
  1. um agente somente leitura escreve um estudo de arquitetura primeiro;
  2. ele é dividido em etapas testáveis;
  3. o diretor o vê;
  4. então é construído passo a passo.
• Para uma nova mecânica: uma breve proposta escrita primeiro, depois aprovação, depois código. Se o diretor disser "não faço ideia, você escolhe", o agente deve se comprometer com uma escolha, não listar opções.

6. Gerenciando agentes

Quando delegar. Dê trabalho substancial a um agente: um sistema completo, um lote de modelos, um lote de conteúdo. Faça tarefas pequenas você mesmo.

Modelo de briefing do agente:

1. Contexto em 3 ou 4 linhas, mais os documentos a serem lidos.
2. A tarefa, como pontos numerados precisos.
3. Entregáveis: arquivos, capturas de tela nomeadas, testes.
4. Regras estritas (abaixo).
5. Formato do relatório: curto, incluindo o que ainda está imperfeito.

Regras a repetir em todo briefing:

• Nenhum comando git que altere o repositório. O orquestrador faz o commit.
• Nunca deixe uma janela do jogo rodando. Um jogo esquecido pode escrever gigabytes de logs e encher o disco.
• Não mate processos que você não iniciou. Não deixe nenhuma simulação em segundo plano rodando após o relatório.
• Propriedade de arquivos: diga quais arquivos outros agentes estão editando e quais não tocar.
• Mantenha finais de linha consistentes (LF), especialmente no Windows, onde editar scripts pode alterá-los silenciosamente.
• Nenhum valor de balanceamento no código.

Paralelismo.

• Execute tarefas em paralelo apenas se forem independentes e tocarem em arquivos diferentes.
• Execute no máximo três agentes ao mesmo tempo.
• Um agente que depende de outro espera pelo relatório desse agente.

Verifique cada entrega você mesmo.

• Execute o conjunto de testes.
• Inicie o jogo e filtre a saída para ERROR e WARNING.
• Olhe as capturas de tela criticamente, como o diretor faria:
  • palavras cortadas;
  • objetos soltos;
  • texto sobreposto;
  • cores vazando para fora de sua forma;
  • inconsistências com a direção de arte.
• Se algo estiver errado, envie o agente de volta com uma lista numerada precisa.

Quando um limite de uso cortar um agente, retome-o com uma mensagem curta ("continue de onde parou, mesma tarefa, mesmas regras"). Não inicie um novo agente para a mesma tarefa.

7. Escolhendo o modelo

Tarefa	Modelo
Modelos 3D, desenho de ícones, design visual complexo, cinemáticas	O modelo mais criativo (ex: Fable)
Código de sistema, arquitetura, UI complexa	O modelo de codificação mais forte (ex: Opus)
Balanceamento, testes, QA, edições de dados, pequenos ajustes de UI	O modelo mais leve que faz o trabalho bem (ex: Sonnet)
Pesquisa ou estudo somente leitura	Um agente de exploração ou planejamento

Sempre use o modelo mais barato que faz o trabalho bem.

8. Economizando tokens sem perder qualidade

1. Um agente novo com um briefing curto para cada nova tarefa. Retomar um agente que já possui centenas de milhares de tokens faz com que ele releia tudo a cada etapa. Este é o maior desperdício.
2. Feedback em lote. Envie várias correções do diretor em uma execução, não uma retomada por observação.
3. Poucas capturas de tela. Agentes fazem apenas as solicitadas. O orquestrador olha uma ou duas, não todas.
4. Testes: testes direcionados durante o trabalho, o conjunto completo uma vez no final. Filtre a saída para falhas e o resumo.
5. Inicie o jogo uma vez por tarefa, não após cada edição.
6. Leitura: não releia o que acabou de escrever e leia arquivos grandes em partes direcionadas.
7. Faça pequenas correções diretamente, sem um agente.
8. Mantenha os relatórios curtos, do orquestrador e dos agentes.
9. Automações:
   • uma retomada automática só pode reiniciar o trabalho interrompido por um limite de uso, nunca iniciar uma nova etapa sem aprovação;
   • desligue-a quando nada estiver rodando.
10. Se um problema resistir a três tentativas, pare e explique em vez de entrar em loop.

9. Habilidades e ferramentas de terceiros

• Verifique as habilidades existentes primeiro.
• Pesquise nesta ordem:
  1. repositório oficial da Anthropic;
  2. documentação oficial da ferramenta;
  3. a comunidade.
• Leia um candidato completamente, scripts incluídos, antes de propô-lo. Sinalize qualquer download, chamada de rede ou acesso fora do projeto.
• Nunca instale uma ferramenta, extensão ou habilidade sem a aprovação explícita do diretor. Registre cada adição e sua fonte.
• Muitas vezes a melhor opção é uma habilidade personalizada curta escrita para o projeto.

10. Ferramentas e aplicativos a abrir e verificar

No início do projeto, verifique cada ferramenta, registre seu caminho e pergunte apenas o que está faltando.

• Engine do jogo (ex: Godot).
  • Encontre o executável: where, Downloads, Desktop, Program Files.
  • Execute uma importação headless após adicionar novos scripts de classe.
  • Adicione opções de linha de comando para iniciar uma cena, tirar uma captura de tela, carregar um salvamento e fixar uma semente aleatória. Elas permitem verificar tudo sem uma janela.
• Blender.
  • Construa modelos com scripts de linha de comando (blender -b --python), versionados em uma pasta art-source.
  • O Blender MCP é apenas para visualização ou trabalho ao vivo: ele controla a janela do próprio diretor, portanto não execute trabalhos longos lá enquanto eles a usam.
• Servidores MCP (engine, Blender…): verifique se eles respondem. Caso contrário, diga exatamente ao diretor o que abrir.
• Testes: o framework de teste da engine (ex: GUT para Godot), executado headless a partir da linha de comando.
• Git e GitHub.
  • Um repositório privado.
  • Um .gitignore adequado à engine.
  • Arquivos fonte pesados (.blend) em uma pasta dedicada.
• Exportando o jogo.
  • Use os templates de exportação oficiais da engine, baixados apenas com a aprovação do diretor.
  • Avise os testadores sobre o aviso do Windows mostrado para um executável não assinado.
• Áudio. Use apenas recursos gratuitos (CC0, ou CC-BY com crédito) até o diretor aprovar gastos.
• Custos.
  • Nenhum serviço pago sem aprovação.
  • Sem excedentes: se o diretor perguntar, verifique se o uso pago extra está desligado.

11. Git e salvando o trabalho

• Um commit por tarefa concluída e verificada, com uma mensagem clara no idioma do diretor.
• Um branch por fase. Se essa for a regra do diretor, nenhum push, merge ou tag de versão antes de sua aprovação. Uma vez que a fase for aprovada: merge, tag vX.Y, push.
• Faça commit apenas de estados onde os testes passam. Se os agentes ainda estiverem trabalhando, faça commit apenas dos arquivos que estão concluídos.
• Nunca faça commit de segredos.

12. Testes e verificação

• As regras do jogo vivem em serviços testáveis sem uma cena. A simulação é separada da renderização.
• Escreva testes para toda a lógica crítica (economia, progressão, salvamentos). Um bug corrigido = um teste que o reproduz.
• Os testes devem ser determinísticos: injete a semente e o relógio.
• Cada nova versão de salvamento tem uma migração e um teste de migração.
• Salvar é quase constante:
  • em momentos-chave, mais um temporizador;
  • vários slots automáticos rotativos;
  • gravações seguras (arquivo temporário, depois renomear).
• Uma tarefa só está concluída se os testes passarem e o jogo iniciar sem ERROR.
• Automatize verificações para regras de arte repetitivas (contornos de ícones, estouro de texto, texto cortado). A verificação impõe a regra; o olho julga a beleza.
• Uma passada completa de QA ao final de cada fase:
  • a história jogada até o fim, incluindo o final verdadeiro;
  • salvar e carregar;
  • escalas de UI.

13. Dados e balanceamento

• Nenhum valor de balanceamento no código. Tudo vive em arquivos de dados.
• Balanceamento com um jogador simulado que roda headless e fornece medições reproduzíveis.
• O tempo total de jogo não é uma meta. O que importa:
  • tempo morto: nada útil para fazer ou comprar;
  • paredes: uma espera muito mais longa que o nível anterior;
  • lacuna entre duas novidades;
  • estoques ociosos: uma moeda que acumula precisa de usos ao longo do jogo, nunca impostos punitivos.
• Torne o jogador simulado realista. Ele deve usar as novas mecânicas também e seguir a história até o fim.
• Entregue uma tabela antes/depois por nível, mais a lista de valores alterados e a razão para cada mudança.

14. UI/UX: regras de harmonia

Sistema de design

• Um tema central para cores, margens, fontes (no máximo duas) e estilos de botão. Nenhum estilo local espalhado; um teste deve impor isso.
• Cores por função de ação, as mesmas em todos os lugares:
  • uma cor para a ação primária e, idealmente, uma ação primária por tela;
  • uma cor neutra para ações secundárias;
  • vermelho para perigo e destruição;
  • uma cruz vermelha no canto superior direito fecha uma janela.
• Sem visual de web, sem visual de IA: é um jogo (veja a seção 15). Prefira ícones a palavras: nenhum botão "Pular" ou "Próximo" como texto.

Layout

• Margens iguais em todos os lados; nada grudado em uma borda.
• Contornos de foco e seleção totalmente visíveis, nunca cortados.
• Nenhuma palavra cortada. Alargue, reformule ou quebre a linha.
• Sem mudança de layout: um botão mantém exatamente o mesmo tamanho em todos os estados (normal, hover, pressionado, desabilitado). Uma lista nunca se move sob o mouse.
• Ações permanecem no lugar: o botão principal sempre fica no mesmo local, por exemplo na parte inferior do cartão. Um texto de motivo ("créditos insuficientes") vai acima do botão, não abaixo.

Componentes

• Emblemas de notificação sobrepõem-se ligeiramente ao canto do seu botão.
• Atalhos de teclado nunca ocupam espaço dentro dos botões:
  • eles aparecem na dica de ferramenta e enquanto uma tecla é mantida (ex: Alt);
  • uma letra discreta no canto tem preenchimento igual no topo e à direita;
  • uma opção pode mostrá-los permanentemente.
• Diálogos paginados:
  • nenhuma seta "anterior" quando não há nada antes (seu espaço permanece reservado);
  • nenhum botão "OK" e nenhum temporizador na última página: o jogador fecha com a cruz, Escape ou um clique;
  • uma pequena dica (um pulso) marca o fim.

Cursor

• Sempre o cursor próprio do jogo, nunca o do sistema.
• A mão do jogo em tudo que é clicável.
• Um cursor específico de modo para construir, mover, demolir e assim por diante.

Ações no mundo

• Visualização antes de agir. Demolir mostra o edifício em vermelho com o que você recebe de volta. Mover mostra-o em azul, o objeto segue o mouse e seu local antigo fica vazio.
• Clique direito cancela.

Acessibilidade, escalas, entrada, texto

• Nunca transmita informações apenas com cor.
• Teste em escalas de UI de 80%, 100% e 150%, e em várias resoluções.
• Navegação completa por gamepad e teclado.
• Todo texto vive em arquivos de tradução, nunca codificado. Nenhuma chave bruta aparece na tela; um teste deve impor isso.
• Oculte grupos vazios: nenhuma linha de zeros.

15. Evite o "visual de IA": prefira design com sensação humana

O trabalho assistido por IA tende a derivar para o mesmo resultado genérico, excessivamente suave e vazio.