Claude Code Projects: coordenador, threads e limitações da versão beta

A Anthropic reformulou recentemente o Projects no Claude Code. Agora é uma única conversa de coordenação que inicia sessões paralelas na cloud — threads — para tarefas e recebe os respetivos relatórios. Vale a pena criar um projeto quando o seu trabalho tem um objetivo que se prolongará para além de uma única sessão e dará origem a novas tarefas — por exemplo, desenvolver um repositório GitHub ao longo de várias semanas. A necessidade de trabalhar em paralelo, por si só, não é suficiente. Se precisar de corrigir rapidamente um ficheiro, ali e naquele momento, basta uma sessão normal.

O trabalho é liderado por um coordenador — uma conversa de longa duração na qual o Claude decide o que transformar, a partir da sua mensagem, numa tarefa para uma thread. As threads escrevem o código: cada uma é uma sessão independente do Claude Code na cloud, na sua própria ramificação do repositório. Podem correr várias threads ao mesmo tempo, cada uma com o seu próprio contexto e ramificação. O coordenador vê o que uma thread comunica quando termina, mas não todos os passos que executa. Comunica-lhe os pull requests concluídos (pedidos para integrar alterações) e, quando lhe der instruções, pede a uma thread que os reveja ou integre. Segue-se uma visão geral baseada na documentação oficial da Anthropic: o que configurar, como o trabalho está organizado e quais são as limitações da versão beta.

A versão beta está a ser disponibilizada gradualmente, começando pelas contas Pro e Max que já utilizaram sessões do Claude Code na cloud e ainda não criaram um projeto no chat normal nem no Cowork. Se ainda não vir a secção Projects, pode inscrever-se na lista de espera.

O que é o Claude Code Projects, em termos simples#

Um projeto é uma única conversa de longa duração com um coordenador, à qual estão associados repositórios, memória e instruções. Escreve ao coordenador, que decide se responde de imediato ou inicia uma thread. Não precisa de abrir manualmente uma nova sessão para cada tarefa.

Uma thread é uma sessão completa do Claude Code na cloud: tem o seu próprio contexto e ramificação do repositório e abre um pull request quando necessário. O coordenador pode manter várias threads abertas ao mesmo tempo — por exemplo, uma corrige um erro, outra escreve testes e uma terceira atualiza a documentação — enquanto responde às suas perguntas na conversa principal.

Para comparar, imagine vários separadores com sessões locais do Claude Code, cada uma na sua própria cópia de trabalho de um repositório. Essa cópia chama-se worktree — uma pasta separada para uma ramificação, para que as sessões locais não interfiram umas com as outras. É você que alterna entre as sessões e decide o que atribuir a cada uma. As threads na cloud não precisam de uma worktree: cada thread clona os repositórios para o seu próprio ambiente isolado na cloud. O Projects trata da coordenação e decide quando criar uma nova thread e quando isso não é necessário.

Um projeto tem memória e instruções partilhadas, que cada nova thread recebe. A secção de configuração explica o que guardar nelas e como são transmitidas às threads.

Diferenças em relação a uma sessão normal e a uma equipa de agentes#

Se já executa subagentes aninhados numa única sessão do Claude Code, convém distingui-los das equipas de agentes e das threads de projetos. Uma equipa de agentes é outra forma de delegar trabalho: uma sessão inicia sessões de colegas para uma tarefa específica. Pode executá-la tanto na sua própria máquina como numa sessão na cloud.

• Equipa de agentes — sessões de colegas para uma tarefa específica, que podem ser iniciadas localmente ou na cloud. Não são threads de projeto independentes.
• Um projeto e as respetivas threads — o trabalho decorre na cloud. Cada thread é uma sessão independente na sua própria ramificação e continua a funcionar mesmo depois de fechar o portátil. Uma sessão local não pode fazer parte de um projeto.
• Vista de agentes — um ecrã para observar várias sessões locais na sua máquina. Não tem coordenador: é você que decide o que atribuir a cada uma.

A documentação oficial da Anthropic salienta separadamente que trabalhar em paralelo, por si só, não é motivo para criar um projeto. Num projeto, o Claude inicia as sessões e recebe os respetivos relatórios, e todas as sessões começam com os mesmos repositórios, instruções e memória. O trabalho decorre na cloud durante toda a tarefa.

Uma abordagem semelhante — um coordenador que distribui tarefas pelos agentes — está implementada noutra ferramenta, abordada no artigo sobre o Cursor Projects. O mecanismo é diferente, mas o coordenador também decide o que atribuir a cada pessoa.

O que configurar antes do primeiro projeto#

Antes de criar um projeto, verifique três aspetos.

1. Conta GitHub e aplicação Claude GitHub App. Se já ligou o GitHub através de /web-setup, esse token dá às suas sessões normais na cloud acesso ao repositório. Isso não é suficiente para as threads de projeto: precisa de uma conta GitHub ligada com acesso de escrita ao repositório e da aplicação Claude GitHub App instalada nesse repositório. Sem ela, uma thread não consegue clonar o repositório nem abrir um pull request.

2. Instruções do projeto. As instruções do projeto são um texto com até 16 000 caracteres, enviado a cada nova thread e ao próprio coordenador. Inclua aqui informações que, de outro modo, teria de explicar novamente em cada sessão: a estrutura do repositório, as convenções de código e as verificações necessárias antes de um pull request.

3. Modelo e nível de esforço. Por predefinição, cada thread de um novo projeto utiliza o modelo Opus com um nível de esforço elevado, e o coordenador utiliza um nível de esforço baixo. A documentação afirma que esta configuração «consome o limite do seu plano mais rapidamente» (tradução; original: draws on your plan fastest). Se as suas tarefas forem simples, pode selecionar um modelo menos dispendioso ou reduzir o nível de esforço em Project settings > General. As definições das threads e do coordenador são alteradas separadamente; a documentação descreve opções mais económicas.

A memória do projeto é guardada em ficheiros normais, com um ficheiro de índice chamado MEMORY.md. Cada nova thread lê-o ao arrancar e acede aos outros ficheiros conforme necessário. As descobertas de uma thread guardadas na memória ficam disponíveis para a seguinte, sem ser necessário repeti-las.

O que fazer se as threads alterarem o mesmo código#

Cada thread trabalha na sua própria ramificação e abre ela própria um pull request quando o trabalho o exige. Porém, o coordenador não garante que as tarefas nunca se sobreponham: se várias threads acabarem por trabalhar na mesma área do código, pode pedir à thread relevante que resolva o conflito através da interface. Junto ao pull request encontra-se um botão Resolve conflicts, que envia uma instrução à thread como se fosse uma mensagem sua.

A documentação oficial sugere que indique nas instruções do projeto as suas preferências quanto ao número de threads: por exemplo, pedir ao coordenador que inicie, no máximo, duas threads ao mesmo tempo ou que reutilize uma thread existente para novas tarefas na mesma área. Trata-se de uma preferência que o coordenador tenta respeitar, e não de um limite rígido. Por si só, não garante que as threads não entrem em conflito no mesmo ficheiro — um conflito existente tem de ser resolvido separadamente. Para tarefas relacionadas na mesma área, pode reutilizar uma thread ativa ou inativa. Se estiver inativa há mais de uma hora, volta a ler todo o histórico quando recebe uma nova mensagem, o que afeta o consumo do limite da subscrição.

Quanto mais claramente as tarefas estiverem divididas por ficheiros ou módulos, mais fácil será trabalhar em paralelo. Há um artigo separado sobre como dividir uma tarefa grande em partes independentes: como delegar programação a milhares de agentes. A escala é diferente, mas o princípio de dividir o trabalho é o mesmo.

Enquanto a cache da conversa estiver ativa (nos planos Pro e Max, durante uma hora, se os limites do seu plano o permitirem), uma thread utiliza menos tokens do limite da subscrição para voltar a processar o histórico. Quando a cache expira, a thread volta a ler todo o histórico ao receber uma nova mensagem, antes de começar a trabalhar. Para uma nova tarefa independente, pode ser mais económico pedir ao coordenador que crie uma thread nova: isso pode consumir menos tokens do mesmo limite da subscrição do que continuar uma sessão antiga com um histórico extenso depois de a respetiva cache ter expirado.

Limitações da versão beta que deve conhecer de antemão#

Antes de criar um projeto para uma tarefa importante, verifique as limitações da versão beta:

• Disponível apenas nos planos Pro e Max. Os planos Team e Enterprise ainda não são suportados.
• Limite de 200 novas threads por dia por conta, no total de todos os projetos.
• Um projeto pertence a um único utilizador. Não pode partilhar o acesso ao projeto nem a uma thread individual com outra pessoa, e a versão beta não tem definições de organização para equipas.
• Acesso apenas através de claude.ai/code, da aplicação para computador e da aplicação móvel. O Projects não funciona no CLI do terminal, através do Amazon Bedrock, do Google Cloud Agent Platform nem do Microsoft Foundry.
• Um projeto não consegue ver ficheiros nem ferramentas locais. As threads trabalham com repositórios GitHub, ficheiros carregados e pastas do Google Drive, mas não com elementos que existam apenas na sua máquina.

Se precisar de acesso ao terminal ou a ferramentas disponíveis apenas na sua máquina, utilize uma sessão local ou uma vista de agentes para várias sessões desse tipo. Se várias pessoas precisarem de trabalhar em conjunto no mesmo espaço de trabalho, a Anthropic tem um produto separado para equipas nos planos Team e Enterprise: Claude Tag. Funciona num canal do Slack; qualquer membro pode atribuir uma tarefa ao Claude, e todos os membros do canal podem ver e orientar o trabalho. Um projeto funciona de forma diferente: pertence apenas a si. Se precisar apenas de determinados ficheiros locais, pode carregá-los para o projeto e, assim, cada thread terá acesso a eles. Isso não dá acesso às ferramentas locais.

O que fazer a seguir#

Antes de transferir o seu fluxo de trabalho para o Projects, experimente criar um projeto de teste num repositório não crítico: ligue a GitHub App, escreva instruções curtas, atribua ao coordenador uma tarefa independente e observe como ele a executa. Esta primeira utilização mostrará se compreende a interface do coordenador e das threads. Não avalia o trabalho em paralelo, os conflitos nem o consumo do limite em várias tarefas — esses aspetos têm de ser testados separadamente.