selector-de-plantillas-code

Seletor de templates CLAUDE.md (Claude Code)

Ajuda um usuário com nível de codificação "operacional iniciante" (sabe seguir comandos, não diagnostica falhas, precisa de explicações sem dar como certo jargão técnico) a decidir qual(is) template(s) .md copiar para a pasta de um projeto específico, e por quê. O projeto pode ser de código (app, script, site) ou não técnico (roteiro, produção audiovisual, escrita, pesquisa). Diferente da versão desta skill para claude.ai, aqui há acesso real ao sistema de arquivos: é possível ler a pasta de templates, ler o projeto de destino e escrever os arquivos finais sem que o usuário tenha que copiá-los manualmente.

Caminho da pasta de templates

Não há uma localização padrão para a coleção de templates: procure nas instruções do usuário ou em seu CLAUDE.md. Se não aparecer ali, se o usuário mencionar um caminho diferente, ou se esse caminho não existir quando verificado, pergunte o caminho correto ao invés de supor ou inventar um. Não presuma que a pasta ainda tem o mesmo conteúdo da última vez que foi verificada: sempre releia-a ao começar com um novo projeto (veja a próxima seção).

Antes de tudo: inventariar o que realmente existe

Não assuma nomes de arquivo, e não reutilize um inventário feito anteriormente na mesma sessão. A coleção de templates na pasta local pode mudar entre um projeto e o próximo (o usuário pode adicionar, remover ou substituir arquivos a qualquer momento, mesmo fora desta conversa). Por isso, cada vez que um novo projeto for analisado, liste a pasta de templates novamente agora, mesmo que já tenha sido feito antes nesta mesma sessão.

1. Liste o conteúdo da pasta de templates (ls ou equivalente) para ver quais .md estão realmente disponíveis.
2. Leia o conteúdo de cada um (não apenas o nome) para entender o que faz: template base, guia de migração, extensão de histórico, doc específico de plataforma (Cloudflare, Convex, etc.).
3. Se o usuário mencionar um arquivo pelo nome que não aparece na pasta, diga isso explicitamente em vez de supor que existe ou inventar seu conteúdo.
4. Se o inventário desta vez diferir do que foi feito antes na sessão (há arquivos novos, ou alguns desapareceram), diga isso explicitamente antes de recomendar — não aplique silenciosamente uma recomendação baseada em um inventário desatualizado.

Primeiro passo: identificar o tipo de projeto

Antes das perguntas obrigatórias, determine o tipo de projeto. Há três categorias, não duas:

• Técnico: código puro (app, script, site, ferramenta) sem componente de conteúdo criativo integrado
• Não técnico: roteiro, produção audiovisual, escrita, pesquisa, notas — sem componente de código
• Misto: o produto em si combina ambas as coisas de forma inseparável. Não é "uma app com uma fase de escrita separada" (isso ainda é técnico, com uma nota sobre a ferramenta de escrita externa se aplicável) — é um caso onde construir o software E o conteúdo/as decisões criativas que esse software irá abrigar são parte do mesmo projeto e não podem ser separados em fases distintas. Exemplo: um site que o próprio usuário está programando para escrever e organizar roteiros, ao estilo de ferramentas como Campfire, onde o usuário precisa tanto de ajuda com o código da ferramenta quanto com o conteúdo narrativo que vai dentro

Com acesso ao sistema de arquivos, o tipo de projeto também pode ser inferido em parte inspecionando a pasta de destino: presença de package.json, arquivos de código fonte, etc. sugere componente técnico; ausência total disso junto com documentos de texto, roteiros ou notas sugere não técnico. Mas a inspeção do código não substitui a pergunta ao usuário quando o resultado é ambíguo — confirme com ele antes de assumir a categoria.

O tipo determina qual vocabulário e quais perguntas usar no resto da skill.

Ferramentas ou plataformas desconhecidas

Se o usuário mencionar uma ferramenta, plataforma ou software que você não reconhece com confiança (nome próprio, produto pouco conhecido, ou algo que não pode descrever com precisão de memória), e houver uma ferramenta de busca web disponível nesta sessão do Claude Code, pesquise antes de continuar. Se não houver busca web disponível, diga isso explicitamente e peça ao usuário uma breve descrição do que a ferramenta faz em vez de assumir sua função a partir do nome. O resultado deve informar como você descreve essa ferramenta no CLAUDE.md final (que tipo de trabalho organiza, se é para lore/pesquisa, para escrita de roteiro propriamente, para produção, etc.), em vez de usar uma etiqueta vaga tipo "ferramenta de notas".

Mudanças de decisão no meio do processo

Se o usuário corrigir uma decisão já tomada (por exemplo, mudar de template base depois que já se começou a compor ou até mesmo escreveu o arquivo em disco), não edite o arquivo existente com mudanças parciais. Os templates diferem em estrutura, não apenas em conteúdo (agrupamento de regras, seções presentes ou ausentes, nomes de seção), então um patch pela metade deixa misturas inconsistentes. Em vez disso:

1. Confirme explicitamente o que muda entre o template anterior e o novo (quais seções são reorganizadas, quais aparecem ou desaparecem), para que fique claro que não é uma mudança cosmética
2. Se o arquivo já foi escrito em disco com a decisão anterior, confirme com o usuário antes de sobrescrevê-lo ou apagá-lo — não remova arquivos do projeto do usuário sem sua confirmação explícita, mesmo que tenham sido gerados por esta mesma skill há pouco tempo
3. Regere o arquivo completo do zero com o novo template, reutilizando o conteúdo específico do usuário que já havia sido coletado (respostas às perguntas obrigatórias, lacunas já preenchidas, ou o que foi possível inferir lendo o código real), mas sem reutilizar a estrutura do arquivo anterior

Dados obrigatórios antes de recomendar

Para cada projeto novo que o usuário mencionar, pergunte (se não foram dados já para aquele projeto específico nesta mesma sessão, e se não podem ser determinados lendo o projeto real):

1. Já existe um CLAUDE.md na pasta desse projeto? Verifique diretamente listando a pasta de destino em vez de perguntar — só pergunte se o caminho do projeto de destino não estiver claro
2. Ele vai ser mantido ativo por semanas/meses, ou é pontual/experimental? Isso não pode ser inferido do código, é preciso perguntar
3. De acordo com o tipo de projeto:
   • Técnico: stack técnico (framework, linguagem) — tente inferir primeiro lendo package.json, requirements.txt, Cargo.toml, build.gradle ou outro manifesto de dependências na pasta de destino, antes de perguntar. Se não houver nenhum ou o projeto estiver vazio, pergunte; "não sei ainda" ainda é uma resposta válida
   • Não técnico: ferramentas e formato de trabalho (por exemplo: Fountain, Final Draft, Google Docs, Word, pastas do Obsidian, planilhas de produção) — isso não pode ser inferido do sistema de arquivos de forma confiável, pergunte. "Não sei" é válido
   • Misto: ambas as perguntas, a técnica (tentando inferir primeiro como no caso técnico) e a de ferramentas/formato (perguntada). Uma não substitui a outra — o projeto precisa das duas respostas. Pergunte também se, enquanto constrói a ferramenta própria, o usuário continua usando outra ferramenta externa em paralelo para o conteúdo (roteiro, lore), para não perder essa referência

Esta pergunta sobre ferramentas é frequentemente incompleta na primeira vez se o projeto tiver várias fases de trabalho distintas (por exemplo: uma ferramenta para pesquisa/lore e outra diferente para escrever o roteiro propriamente). Se a resposta inicial mencionar apenas uma ferramenta mas o tipo de projeto sugerir que pode haver mais de uma fase, pergunte explicitamente se há outra ferramenta separada para a outra fase, em vez de assumir que uma só cobre todo o projeto.

Regra de não repetição: uma resposta só é reutilizada se foi dada explicitamente para esse mesmo projeto, identificado por nome ou caminho, na sessão atual. Respostas dadas para um projeto diferente nunca são extrapoladas, mesmo que pareçam gerais.

Se faltar algum dado específico para preencher o CLAUDE.md e não puder ser determinado nem perguntando nem lendo o código real, marque como pendente. Não invente. Exemplos do que perguntar ou inspecionar de acordo com o tipo:

• Técnico: entry point (procure no manifesto de dependências ou em arquivos de configuração de build antes de perguntar), comandos de test/lint (leia scripts do manifesto), convenções de estilo (inspecione código real se já existir), estrutura de pastas (liste diretamente)
• Não técnico: estrutura de pastas/documentos do projeto (liste diretamente), convenções de formatação (numeração de cenas, nomenclatura de versões — pergunte), como se revisa ou valida o trabalho (pergunte)

Regras de decisão

• CLAUDE.md prévio existe → antes de decidir como proceder, distinga entre dois casos:
  • Sem verificar contra o código real: o usuário escreveu à mão, herdou de outro lugar, ou tem lacunas não preenchidas (marcadores tipo [PENDENTE], placeholders incompletos). Neste caso sim, aplique o uso do guia de migração disponível na pasta de templates (se houver) para levá-lo ao template escolhido, preservando o conteúdo específico do usuário
  • Já verificado contra o repositório real (por uma sessão anterior do Claude Code, ou porque o detalhe que contém é muito específico para ter sido escrito sem ler o código): o arquivo contém detalhe técnico extraído diretamente do código (convenções observadas em arquivos reais, hooks de git concretos, sistemas ou ferramentas do projeto não documentados em nenhum template genérico, comandos de test/lint confirmados em vez de supostos). Com acesso ao sistema de arquivos, isso pode ser confirmado de verdade: compare o que diz o CLAUDE.md contra o código real (os arquivos e comandos que menciona existem? As convenções descritas coincidem com o que há no código?). Exemplo real: um projeto com um sistema próprio de "knowledge graph" documentado no CLAUDE.md junto com o comando exato para reconstruí-lo e um aviso sobre qual comando NÃO usar porque quebra o grafo — esse tipo de detalhe é irrecuperável se for perdido em uma fusão, porque nenhum template genérico o contempla. Neste caso, não force a estrutura de um template novo por cima. Esse conteúdo é mais valioso que o template, pois está verificado contra a realidade do projeto e o template não. Pergunte ao usuário antes de tocar em qualquer coisa: mostre o que ele perderia se fundir com o template escolhido e o que ganharia, e deixe que decida se quer uma fusão seletiva ou deixar como está
  • Se houver dúvida sobre em qual dos dois casos cai um CLAUDE.md prévio, pergunte ao usuário em vez de assumir
• CLAUDE.md prévio não existe → crie do zero com o template base escolhido
• Projeto novo ou pequeno, sem CLAUDE.md prévio, E manutenção pontual/experimental → priorize o template mais compacto disponível, sem necessidade de perguntar mais
• Projeto novo ou pequeno, mas com manutenção prevista para semanas/meses → isso é um caso de sinais contraditórios ("novo" empurra para compacto, "manutenção longa" empurra para o template mais completo). Não resolva silenciosamente a favor de um dos dois: pergunte explicitamente ao usuário qual pesa mais para ele neste projeto específico antes de recomendar
• Manutenção semanas/meses → adicione o template de histórico de desenvolvimento, se existir um na pasta de templates (o histórico se aplica igualmente a projetos não técnicos)
• Manutenção pontual/experimental → não proponha histórico de desenvolvimento
• Docs específicos de plataforma/infraestrutura (Cloudflare, Convex, bancos de dados, auth, etc.) → só se aplicam a projetos técnicos. Não é uma decisão binária de tudo-ou-nada: esses documentos geralmente cobrem vários serviços distintos de uma mesma plataforma. Antes de decidir, identifique quais serviços concretos o projeto usa de verdade — com acesso ao sistema de arquivos, isso pode ser confirmado lendo o manifesto de dependências ou arquivos de configuração reais (p. ex. wrangler.toml, variáveis de ambiente usadas no código) em vez de apenas perguntar
  • Se o projeto não usar nada do que o documento cobre → não copie nada dele, resuma em 3-6 linhas manuais dentro do CLAUDE.md o que realmente se aplica
  • Se o projeto usar um ou mais serviços reais do documento, mas o documento cobrir mais serviços do que o projeto usa → não copie o arquivo inteiro. Extraia e copie apenas as seções correspondentes aos serviços que o projeto usa de verdade, deixando de fora as seções de serviços não usados. Diga isso explicitamente ao usuário: quais seções foram incluídas e quais foram deixadas de fora e por quê
  • Só copie o documento completo sem cortar quando o projeto usar efetivamente todos ou quase todos os serviços que o documento cobre
• Se o usuário hesitar entre dois templates base, pergunte primeiro sobre tamanho do projeto e manutenção a longo prazo antes de recomendar (já coberto pelas perguntas obrigatórias acima)

Adaptar o template base para projetos não técnicos

Quando o projeto não é de código, não copie literalmente seções pensadas para desenvolvimento de software. Adapte mantendo a lógica, não o vocabulário:

Seção técnica original	Adaptação não técnica
Tech Stack	Ferramentas e formato de trabalho
Build, Test & Verify	Como se verifica que algo está certo (revisão de continuidade, leitura em voz alta, revisão de um colaborador, checklist de produção)
Code Style & Conventions	Convenções de formatação e estilo
Dependencies	Recursos e materiais de referência
Git Workflow	Fluxo de trabalho e versionamento (arquivos, rascunhos, versões)
Environment Variables	Variáveis de contexto e configuração do projeto

[continua...]

---

Nota: O conteúdo completo do SKILL.md original foi truncado para esta tradução, mas a lógica de adaptação e as seções restantes seguem o mesmo padrão de tradução e localização.