using-git-worktrees

Visão geral da skill using-git-worktrees

O que a skill using-git-worktrees faz

A skill using-git-worktrees ajuda um agente a criar um Git worktree separado para um novo trabalho, em vez de reutilizar o checkout atual. O papel real dela não é só “rodar git worktree add”, mas escolher um diretório adequado, verificar se as pastas locais de worktree estão ignoradas com segurança e evitar contaminar o workspace principal.

Quem deve instalar

Esta skill é mais indicada para quem regularmente:

• inicia trabalho em features sem mexer nas alterações atuais
• revisa ou implementa várias branches em paralelo
• quer fluxos de codificação com IA mais seguros, com menos risco ao trocar de branch
• precisa de uma forma repetível de criar workspaces isolados em vários projetos

Se você costuma pedir a um assistente para “começar isso em uma branch separada” ou “trabalhar sem tocar na minha árvore atual”, using-git-worktrees é uma ótima escolha.

O trabalho que ela resolve

O usuário quer uma coisa só: começar a implementação em um workspace isolado com o mínimo de erro de configuração. A skill using-git-worktrees é útil porque adiciona um processo de decisão antes da criação:

• priorizar um diretório de worktree do projeto se ele já existir
• respeitar a preferência documentada no repositório em CLAUDE.md, se houver
• perguntar ao usuário quando não existir um padrão seguro
• verificar o comportamento de ignore antes de criar worktrees locais ao projeto

Isso torna a skill mais confiável do que um prompt genérico que já vai direto para comandos de shell.

O que diferencia de um prompt comum

Um prompt comum pode até conhecer Git worktrees em termos conceituais, mas ainda assim deixar passar detalhes específicos de configuração do repositório. Esta skill dá ao agente uma ordem definida de execução e checagens de segurança, principalmente em torno da escolha do diretório e do tratamento de .gitignore. Esse é o principal diferencial de using-git-worktrees for Git Workflows: menos adivinhação na configuração, não mais teoria sobre Git.

Quando esta skill não é a melhor opção

Evite using-git-worktrees se:

• você sempre trabalha em uma única branch e em um único diretório
• seu ambiente não permite diretórios de trabalho extras
• você só precisa trocar de branch rapidamente, e não de execução isolada
• sua equipe já usa um script wrapper fixo que substitui totalmente essa lógica de decisão

Nesses casos, um comando de shell simples ou o workflow interno da equipe pode ser mais rápido.

Como usar a skill using-git-worktrees

Contexto de instalação da using-git-worktrees

Instale a partir da coleção de skills obra/superpowers:

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

Depois de instalar, use a skill quando estiver prestes a começar um trabalho que não deve reaproveitar o checkout atual.

Como os usuários realmente acionam a skill

O repositório deixa explícito que o agente deve anunciar o uso da skill no início. Na prática, seu pedido deve deixar clara a necessidade de isolamento, por exemplo:

• “Use using-git-worktrees e configure um workspace isolado para esta feature.”
• “Antes de implementar, crie um worktree para a branch feature/auth-refresh.”
• “Use a skill using-git-worktrees para que minhas alterações atuais fiquem intactas.”

Isso aumenta a chance de o agente seguir a skill em vez de improvisar.

Quais entradas a skill precisa

Para obter bons resultados, informe:

• o nome da branch de destino
• se é uma branch nova ou uma branch já existente
• se você prefere armazenar worktrees localmente no projeto ou em um local global
• quaisquer restrições específicas do repositório, como “precisa ficar dentro da raiz do projeto”

Entrada mínima útil:

• nome da branch/tarefa
• permissão para criar um worktree

Entrada melhor:

• nome da branch
• política desejada de diretório
• se há trabalho não commitado no checkout atual
• o que deve acontecer depois da configuração, como “depois comece a implementação”

A lógica embutida de seleção de diretório

A using-git-worktrees skill entrega mais valor justamente no fluxo de escolha de diretório. Ela segue esta prioridade:

1. usar .worktrees se já existir
2. caso contrário, usar worktrees se existir
3. se não existir nenhum dos dois, inspecionar CLAUDE.md em busca de uma preferência documentada
4. se ainda assim não houver indicação, pedir que o usuário escolha entre:
   • .worktrees/
   • ~/.config/superpowers/worktrees/<project-name>/

Isso importa porque a proliferação desorganizada de worktrees vira um problema real de manutenção quando cada sessão inventa um local novo.

Checagens de segurança antes de criar worktrees locais ao projeto

Um ponto importante na adoção: se o worktree for ficar dentro do repositório, a skill exige verificar se o diretório está ignorado antes de criá-lo. Isso protege contra o rastreamento acidental de pastas de worktree ou contra poluir a saída de status do Git.

Essa é uma vantagem concreta em relação ao uso improvisado. Se sua equipe espera usar worktrees locais ao projeto, garanta antes que .worktrees/ ou worktrees/ esteja ignorado pelo Git.

Padrões de prompt mais fortes para usar using-git-worktrees

Prompt fraco:

• “Comece a trabalhar na limpeza do OAuth.”

Prompt melhor:

• “Use using-git-worktrees para criar um workspace isolado para a nova branch feature/oauth-cleanup. Prefira .worktrees/ se for seguro e estiver ignorado. Depois da configuração, comece a implementação sem tocar no meu checkout atual.”

Por que isso é melhor:

• nomeia a skill
• define uma branch de destino
• informa a preferência de diretório
• diz ao agente o que vem em seguida

Workflow sugerido após a criação

Uma sequência prática para using-git-worktrees usage:

1. peça ao agente para usar a skill
2. confirme o local do worktree e o nome da branch
3. faça o agente mover o trabalho para o novo workspace
4. só então comece edições, testes ou planejamento de implementação

Essa sequência é especialmente útil quando o checkout atual já tem alterações não commitadas.

Arquivos para ler primeiro no repositório

Há apenas um arquivo-fonte realmente relevante aqui: SKILL.md.

Leia esse arquivo para ver:

• a ordem exata de prioridade dos diretórios
• o prompt esperado para o usuário quando não houver preferência definida
• a exigência de verificação de ignore
• a formulação de ativação que orienta o agente a anunciar o uso da skill

Esta skill é leve, então a principal questão de adoção é saber se essa lógica combina com o workflow de Git da sua equipe.

Restrições práticas para conhecer antes de depender dela

A skill é intencionalmente enxuta. Ela não parece oferecer:

• scripts wrapper
• helpers de automação
• padronização obrigatória de nomes de branch
• rotinas de limpeza de worktrees antigos
• fallbacks específicos por plataforma

Portanto, using-git-worktrees install entrega orientação de decisão, não um sistema completo de gerenciamento de worktrees. Se você precisa de automação do ciclo de vida, combine a skill com seu próprio tooling de shell.

FAQ da skill using-git-worktrees

A using-git-worktrees é boa para iniciantes?

Sim, desde que a pessoa iniciante já entenda o básico sobre branches e queira um workflow mais seguro de “não mexa no meu workspace atual”. Não é um tutorial de Git; é uma skill estruturada de configuração. Um iniciante completo talvez ainda precise de ajuda para entender o que é um worktree e por que ele é diferente de um clone.

Que problema isso resolve melhor do que prompts comuns?

Prompts comuns costumam pular a parte mais chata: onde o worktree deve ficar e se um diretório local ao projeto está ignorado com segurança. O using-git-worktrees guide embutido na skill reduz esses erros de configuração e torna o comportamento do agente mais consistente.

Preciso usar worktrees locais ao projeto para aproveitar a skill?

Não. A skill pode direcionar para um local global quando não existe diretório local e nenhuma preferência do repositório está documentada. Isso faz com que ela continue útil mesmo se você não quiser pastas extras dentro do repositório.

Posso usar using-git-worktrees com branches existentes?

Sim. O workflow continua útil ao fazer checkout de uma branch já existente em um workspace separado. O principal valor é o isolamento, não apenas a criação de branch.

Quando eu não devo usar using-git-worktrees?

Não use quando:

• você só vai fazer uma edição mínima na branch atual
• sua equipe proíbe locais de worktree não gerenciados
• você já tem tooling interno determinístico que cuida das regras de localização e ignore
• seu repositório tem restrições incomuns de Git que a skill não conhece

Isso substitui conhecimento de Git?

Não. A using-git-worktrees skill melhora a disciplina de invocação e configuração, mas você ainda precisa de noções básicas de Git para nomear branches, fazer rebase, limpar worktrees e definir estratégia de merge.

Como melhorar a skill using-git-worktrees

Dê intenção explícita de branch e diretório

O maior ganho de qualidade vem de informar ao agente tanto a branch de destino quanto a política de diretório desejada. Exemplo:

“Use using-git-worktrees para a branch fix/cache-invalidation. Se .worktrees/ existir e estiver ignorado, use-o; caso contrário, pergunte antes de usar um local global.”

Isso elimina a fonte mais comum de ambiguidade.

Documente preferências em CLAUDE.md

Como a skill verifica CLAUDE.md, você pode melhorar os resultados futuros documentando:

• o diretório preferido para worktrees
• se worktrees locais ao projeto são permitidos
• convenções de nomes para branches ou pastas

Isso transforma esclarecimentos repetidos do usuário em política do repositório.

Pré-configure regras de ignore para diretórios locais

Se sua equipe quer .worktrees/ ou worktrees/ dentro do projeto, adicione a regra de ignore com antecedência. Isso deixa o caminho de using-git-worktrees for Git Workflows mais fluido, porque a verificação de segurança passa sem atrito em vez de interromper a tarefa no meio para discutir configuração.

Fique atento aos modos de falha mais comuns

Os principais modos de falha são previsíveis:

• o agente cria um worktree em um local não aprovado
• as pastas locais de worktree não estão ignoradas
• o nome da branch é inferido de forma ruim a partir de um pedido vago de feature
• a implementação começa no checkout original antes de o isolamento estar concluído

Na maioria das vezes, esses problemas vêm de prompts incompletos, não da skill em si.

Peça confirmação antes de começar a programar

Um prompt simples para melhorar o workflow:

• “Use using-git-worktrees, depois informe o caminho final e a branch antes de fazer qualquer edição.”

Isso ajuda a detectar erros cedo e é especialmente útil em repositórios com várias pastas aninhadas ou políticas incomuns.

Ajuste o processo após a primeira execução

Se a primeira saída for aceitável, mas não ideal, refine o padrão de trabalho em vez de reescrever tudo:

• fixe seu local preferido de diretório
• adicione uma observação em CLAUDE.md
• padronize nomes de branch nos prompts
• exija explicitamente confirmação antes de editar

Isso torna using-git-worktrees usage mais previsível ao longo do tempo e reduz o atrito repetido de configuração.