Turborepo Skill: organize tarefas e cache sem esconder efeitos

ANÁLISE EDITORIAL

A Skill oficial do Turborepo ajuda um agente a entender como um monorepo organiza tarefas, dependências, filtros, cache, variáveis de ambiente, CI e limites entre pacotes. Em vez de reduzir tudo a um comando rápido, ela orienta o agente a ler a estrutura existente, colocar a lógica nos pacotes corretos e declarar no turbo.json somente o que o orquestrador precisa conhecer.

Esse cuidado importa porque cache incorreto pode restaurar artefatos produzidos com entradas diferentes, e uma tarefa de deploy não deve ser tratada como uma compilação determinística. A Skill reúne padrões úteis, mas não conhece automaticamente os efeitos de cada script do seu repositório. Esta página propõe um primeiro uso em leitura, com plano, execução local controlada e revisão humana antes de alterar configuração, autenticar cache remoto ou acionar CI.

O que esta Skill faz de verdade

O SKILL.md oficial funciona como um mapa de decisão para monorepos JavaScript e TypeScript que usam Turborepo. Ele cobre configuração de tarefas, dependsOn, outputs, filtros, --affected, cache local e remoto, variáveis de ambiente, CI, modo watch, pacotes internos e boundaries.

A regra central é manter a lógica da tarefa no package.json do pacote que a executa. O arquivo raiz deve delegar para turbo run, enquanto o turbo.json descreve relações, entradas, saídas e comportamento de cache. Tarefas de raiz continuam possíveis para casos realmente globais, mas não devem virar um atalho para encadear diretórios manualmente.

A Skill também ensina o agente a escolher a referência certa antes de sugerir uma mudança. Isso reduz respostas improvisadas sobre filtros, cache ou ambiente. Ainda assim, ela não instala Turborepo, não lê seu repositório sozinha e não prova que um script é determinístico. O operador precisa fornecer o projeto e limitar o que pode ser lido, alterado e executado.

Para quem serve

Ela serve a desenvolvedores, equipes de plataforma e mantenedores de monorepos que precisam revisar ou criar pipelines de build, teste, lint, geração de código e desenvolvimento. Também é útil para diagnosticar por que uma tarefa não entra no cache, por que um pacote foi executado fora do esperado ou por que uma variável de ambiente não invalidou o resultado.

Em repositórios grandes, a Skill ajuda a tornar a pergunta específica. Em vez de pedir “otimize o CI”, você pode pedir um inventário das tarefas, suas dependências, saídas, variáveis que afetam o hash e efeitos externos. O resultado deve separar observação, proposta e execução.

Ela não é indicada como substituta de testes, revisão de infraestrutura ou conhecimento do produto. Também não deve receber acesso irrestrito a tokens de CI, produção ou cache remoto. Se a equipe ainda não sabe quais scripts escrevem arquivos, fazem deploy ou publicam pacotes, o primeiro trabalho é mapear esses efeitos.

Compatibilidade e pré-requisitos

A Skill foi publicada no repositório oficial do Turborepo e descreve monorepos JavaScript ou TypeScript. O uso prático exige um workspace reconhecido pelo gerenciador de pacotes do projeto, uma versão local do Turborepo e acesso ao código e aos arquivos de configuração que serão analisados. A referência oficial de configuração deve prevalecer quando houver diferença entre exemplos e a versão instalada.

• Repositório versionado em Git e estado de trabalho conhecido.
• package.json, lockfile e definição de workspaces disponíveis para leitura.
• turbo.json e configurações por pacote, quando existirem.
• Versão local do Turborepo identificada, sem depender cegamente de latest.
• Permissão explícita antes de instalar dependências, executar tarefas ou escrever arquivos.
• Ambiente de teste sem segredos de produção para o primeiro uso.

Recursos como boundaries podem ser experimentais e variar por versão. Filtros e resolução da base do Git também dependem do contexto do repositório e do CI. Consulte a visão oficial de opções antes de fixar flags em scripts.

Instalação recomendada

O repositório oficial sugere a instalação da Skill por um cliente compatível com o ecossistema Agent Skills:

npx skills add vercel/turborepo

Esse comando consulta a rede, baixa e executa o Skills CLI. Revise a origem do pacote, o destino e os arquivos antes de aceitar. Para uma avaliação sem instalador, baixe o pacote documental desta página, confira o SHA-256 e leia o SKILL.md e suas referências.

Instalar a Skill não instala o binário Turborepo e não configura o monorepo. Mantenha a versão do turbo como dependência do repositório e execute por meio do gerenciador já adotado pela equipe. O diretório oficial fixado no commit permite comparar cada documento antes da instalação.

Configuração antes do primeiro uso

Peça ao agente para começar em leitura. Ele deve listar workspaces, scripts por pacote, tarefas registradas no turbo.json, configurações específicas de pacotes, entradas, saídas, variáveis e tarefas com efeitos externos. Nada deve ser executado nessa etapa.

Classifique cada tarefa como somente leitura, geração local, teste, build, publicação, deploy ou outra mutação. A documentação oficial de tarefas explica como dependsOn, outputs, persistência e cache se relacionam. Uma tarefa que publica, envia ou muda estado deve ter cache desativado e autorização própria.

Defina também a política de ambiente. Variáveis que alteram a saída precisam participar do hash por env ou globalEnv. Variáveis liberadas apenas em passThroughEnv ficam disponíveis em runtime, mas não invalidam o cache. A documentação oficial de variáveis de ambiente descreve essa diferença.

Primeiro uso seguro

Escolha uma tarefa local e reversível, como lint ou teste, em uma branch descartável. Peça ao agente para explicar onde o script vive, quais pacotes devem participar, quais arquivos entram no hash e quais saídas são produzidas. Depois compare essa proposta com o repositório real.

npx turbo run lint --dry

Confirme na ajuda da versão instalada se a opção de prévia usada no seu fluxo está disponível e qual formato ela produz. O objetivo é inspecionar o plano sem executar a tarefa. Para selecionar mudanças recentes, a Skill recomenda --affected, mas a base padrão pode ser main ou master. Se o repositório usa outra base, configure TURBO_SCM_BASE conscientemente.

Somente depois da revisão execute a tarefa local. Compare a primeira execução com a segunda, observe hits e misses e verifique se os arquivos restaurados correspondem ao que o script realmente gera. A documentação oficial de cache reforça que a tarefa precisa ser determinística em relação às entradas conhecidas.

Como o fluxo deve funcionar

1. O agente inventaria workspaces, scripts, versões e arquivos de configuração.
2. Ele identifica a tarefa alvo e separa execução local de efeitos externos.
3. Ele consulta a referência oficial correspondente, sem inventar chaves ou flags.
4. Ele propõe uma mudança pequena e mostra o diff de configuração.
5. Uma pessoa revisa entradas, saídas, ambiente, dependências e cache.
6. A tarefa é testada em branch e ambiente sem segredos de produção.
7. CI, cache remoto, publicação e deploy recebem gates independentes.

O fluxo deve registrar a versão do Turborepo, comando, pacotes selecionados, base Git, variáveis consideradas, arquivos gerados e decisão final. Uma melhora de tempo sem explicação não basta, pois pode resultar de um cache indevido.

Resultado esperado

O resultado esperado é uma configuração compreensível: tarefas definidas nos pacotes corretos, relações explícitas, saídas completas, variáveis relevantes no hash e efeitos externos fora do cache. O agente deve conseguir explicar por que cada pacote participa da execução e por que um resultado pode ser reutilizado.

Em diagnóstico, a entrega pode ser um relatório com tarefa, hash esperado, entradas omitidas, saída ausente, diferença de ambiente e correção proposta. Em implementação, deve haver um diff curto, testes locais e evidência do comportamento antes de integrar. Não publique números de velocidade como benchmark sem ambiente, comando, conjunto de mudanças e repetição verificáveis.

Permissões, privacidade e riscos

A Skill é documental, mas os comandos que ela orienta podem executar scripts arbitrários definidos no repositório. Esses scripts podem compilar, testar, gerar código, acessar rede, escrever artefatos, publicar pacotes ou fazer deploy. Leia o script real antes de autorizar turbo run.

Cache remoto exige autenticação e pode enviar artefatos e logs para um serviço compartilhado. A documentação oficial de Remote Caching da Vercel alerta que logs também são artefatos. Não imprima segredos, dados pessoais ou conteúdo proprietário desnecessário. Prefira credenciais curtas por OIDC quando o ambiente oferecer essa opção e não inclua tokens no prompt.

Variáveis como TURBO_TOKEN e a chave de assinatura do cache são segredos. A lista oficial de variáveis do sistema mostra o alcance dessas configurações. Nunca grave valores reais no repositório, no ZIP, em logs ou em exemplos públicos.

Erros comuns

A lógica foi colocada no package.json raiz. Mova o script para o pacote responsável e deixe a raiz delegar com turbo run. Tarefas de raiz devem ser exceções justificadas.

O cache restaura uma saída errada. Confira outputs, entradas, lockfile, arquivos globais e variáveis que alteram o resultado. Desative cache para tarefas com efeitos externos.

A variável existe no CI, mas não chega à tarefa. Revise o modo de ambiente e a diferença entre variáveis que entram no hash e variáveis apenas repassadas. Não resolva com modo permissivo sem entender o impacto.

--affected compara com a base errada. Confirme a base do Git e configure TURBO_SCM_BASE quando o fluxo não usa main ou master.

O watch entra em loop. Verifique tarefas que escrevem arquivos observados e saídas não declaradas. O modo watch não transforma uma tarefa mutável em determinística.

Cache remoto falha ou expõe conteúdo. Valide equipe, escopo, autenticação, retenção, logs e artefatos antes de ligar o repositório. Comece com cache local e dados de teste.

Versão, licença e origem verificadas

A curadoria consultou a origem oficial vercel/turborepo em 01/09/2026. A API pública do GitHub registrava 31.040 estrelas, acima do piso editorial de 1.000. Estrelas indicam adoção, não segurança ou adequação ao seu projeto.

O conteúdo foi fixado no commit 7f854016d33a093a30102c74aeaa318043ac2c99, disponível no registro oficial do commit. O SKILL.md declara a versão 2.10.13-canary.1, enquanto a release estável mais recente consultada era v2.10.12. Essa diferença é informada, não convertida em equivalência.

A licença do repositório é MIT e permite redistribuição com preservação do aviso. O ZIP local contém 27 documentos: SKILL.md, 24 referências Markdown, LICENSE e ORIGEM.md. Não inclui binário, pacote npm, código do produto, exemplos, scripts, executáveis, dependências, cache, artefatos, logs, configurações de CI, tokens, credenciais ou dados. SHA-256: 67fb85379c11f25202b33202f3bef82aa5b9902d6ed12c4851d12a1871c28f16.

Checklist antes de automatizar

• Fixe a versão local do Turborepo, o commit da Skill e a base Git.
• Inventarie scripts, workspaces, configurações e efeitos externos.
• Mantenha tarefas nos pacotes e justifique qualquer tarefa de raiz.
• Declare saídas, entradas e variáveis que realmente alteram o resultado.
• Desative cache em deploy, publicação e outras mutações.
• Faça a primeira prévia e execução em branch sem segredos de produção.
• Proteja tokens, logs e artefatos antes de ativar cache remoto.
• Revise o diff, repita a tarefa e confirme hits e misses esperados.

Fontes primárias

• Repositório oficial do Turborepo.
• SKILL.md oficial fixado no commit auditado.
• Configuração oficial de tarefas.
• Documentação oficial de cache.
• Variáveis de ambiente no Turborepo.
• Remote Caching oficial da Vercel.