O Claude Code é uma ferramenta de codificação agêntica que lê seu código-fonte, edita arquivos, executa comandos e trabalha diretamente com o git. Para um único desenvolvedor em um único terminal, ele não exige gerenciamento algum: você descreve o trabalho, acompanha sua execução e revisa o diff. Esse ciclo é rápido, e nada neste guia pede que você abra mão dele.
A lacuna aparece quando um time passa a depender dele. Cinco desenvolvedores rodando sessões do Claude Code produzem resultados reais, mas o trabalho fica em terminais privados. Ninguém consegue responder às perguntas que sustentam um time: quem pediu essa mudança, quem está executando agora, o que a execução realmente fez e quem aprovou o resultado antes do merge. A execução é excelente; o registro do trabalho não existe.
O gerenciamento de projetos no Claude Code é a prática de conduzir esse trabalho como trabalho de projeto rastreável e revisável: uma issue se transforma em uma Task com escopo definido, a Task é atribuída a um Agent que executa por meio do Claude Code, a execução acontece em um worktree isolado em uma máquina sob seu controle, e o resultado volta para uma pessoa revisar. Este guia percorre esse caminho usando o Sharkly, que não é um substituto do Claude Code. Ele adiciona a camada compartilhada de tarefas, contexto, controle e revisão em torno da ferramenta que seu time já usa.
TL;DR
Para gerenciar o trabalho do Claude Code como trabalho de projeto, escreva a issue como uma Task com escopo definido, contendo objetivo, limites e critérios de aceite; atribua-a a um Agent cujo Runtime seja o Claude Code; deixe a execução rodar em um Computer conectado, em um worktree git isolado, com o progresso chegando em tempo real; depois revise as evidências na Task e aceite, solicite alterações ou reatribua. O Claude Code realiza a execução. O Sharkly gerencia atribuição, contexto, progresso, bloqueios, resultados e revisão humana ao redor dela, para que execuções paralelas permaneçam visíveis para todo o time em vez de desaparecerem em terminais privados. Sessões solo no terminal continuam sendo a ferramenta certa para trabalhos rápidos, locais e de baixo risco.
O que uma Task gerenciada acrescenta a uma sessão simples do Claude Code
Uma sessão simples e uma Task gerenciada executam o mesmo Claude Code por baixo. A diferença está em tudo o que envolve a execução, e isso se resume a quatro capacidades que um terminal não oferece.
Visibilidade compartilhada. Uma Task mantém requisitos, estado da tarefa, discussão, registros de execução e revisão em um só lugar, em vez de dividi-los entre prompts e sessões privados. Um colega de time pode abrir a SH-214 e ver o que foi pedido, o que está em execução e o que voltou.
Responsabilidade. Uma Task separa a responsabilidade humana da execução pelo Agent. Uma pessoa é responsável pelo resultado; um Agent ou Crew é o responsável pela execução. Ambos ficam registrados, então “quem é o dono disso” sempre tem resposta.
Evidências para a revisão. Toda execução gera um trace de execução: quando começou, quais ferramentas chamou, por que entrou na fila e como terminou. O relatório do Agent é persistido como um comentário vinculado a esse trace. A revisão deixa de ser “confie em quem assistiu ao terminal” e passa a ser “leia o registro”.
Execuções paralelas sem colisões. Cada Task recebe um diretório isolado, e trabalhos baseados em repositório podem usar um worktree git separado por execução, de modo que várias Tasks modifiquem o mesmo código ao mesmo tempo. A mecânica de paralelismo tem seu próprio guia: como executar vários agentes do Claude Code em paralelo.
Um limite honesto antes do passo a passo. Nem toda sessão do Claude Code precisa disso. Use um Agent Chat independente, ou uma sessão comum de terminal, para explorar uma questão, moldar um plano ou fazer uma alteração local rápida. Use uma Task quando o trabalho precisar de responsabilidade, status, histórico de execução ou revisão.
Passo 1: Transforme a issue em uma Task que um Agent consiga executar
Esse caminho começa antes de qualquer agente rodar. O Claude Code planeja uma abordagem a partir do que você fornece, então uma Task vaga produz uma execução confiante na direção errada.
Um título de Task útil nomeia o resultado, não o assunto. A descrição deve conter o que uma pessoa nova, ou um Agent, precisaria para prosseguir: por que o trabalho importa; o que está dentro e fora do escopo; arquivos, links ou comportamentos observados relevantes; restrições e decisões já tomadas; e como a conclusão será revisada.
Esse último item é justamente o que os fluxos solo deixam de lado. Escrever “concluído significa que a lógica de retry tem um teste que falha com o comportamento antigo” na descrição dá ao revisor uma lista de verificação e ao Agent um alvo. Mantenha o objetivo, o escopo e os critérios de aceite estáveis na descrição; use os comentários para discutir.
A categoria de status também importa aqui: uma Task em Backlog fica parada, e atribuir um Agent a ela não inicia a execução. E isso é uma vantagem. Você pode modelar um lote de Tasks, atribuir todas elas e liberar cada uma de forma deliberada, tirando-a do Backlog quando estiver pronta.
Se suas issues já vivem em outro lugar, você não precisa reconstruir seu processo. As integrações do Sharkly incluem Jira, Slack e GitHub, então os rastreadores existentes permanecem no lugar enquanto a execução se torna atribuível e rastreável. A disciplina de escrever trabalho que agentes consigam executar faz parte de uma mudança maior, que abordamos em o que é codificação agêntica.
Passo 2: Atribua a Task a um Agent cujo Runtime seja o Claude Code
No Sharkly, você não atribui trabalho diretamente ao Claude Code. Você o atribui a um Agent, e o Runtime desse Agent é o Claude Code. A distinção se justifica.
Um Agent é uma configuração de trabalho salva, e não um prompt avulso: suas instruções, Runtime, Skills, repositórios, variáveis de ambiente e configurações de execução definem como ele lida com o trabalho. Uma pessoa configura um Agent “Backend Fixer” uma única vez, compartilha-o no Space, e todo o time atribui trabalho a essa mesma configuração já testada, em vez de cada desenvolvedor improvisar prompts. Detalhamos o conceito em Agents no Sharkly, explicados.
O Runtime é a ferramenta de agente concreta disponível em um Computer. Quando você conecta uma máquina, um pequeno serviço local detecta as ferramentas de agente compatíveis instaladas ali e reporta cada uma como um Runtime; uma instalação do Claude Code aparece como um Runtime disponível no momento em que o serviço consegue detectá-la.
Três fatos sobre esse arranjo mantêm as expectativas alinhadas:
- O Agent segue o modelo padrão do Runtime. O Sharkly não exibe nem promete um nome de modelo, e não há seletor de modelo nem controle de profundidade de raciocínio no Agent. Para trocar de modelo, altere a configuração no próprio Claude Code.
- O uso do modelo é por sua conta. As execuções consomem a assinatura do Claude ou a chave de API já configurada no Claude Code naquele Computer. A cota do modelo depende das ferramentas de codificação com IA, dos planos e das contas de API que seu time conectar.
- A atribuição é explícita. Você abre o controle de Assignee da Task e escolhe o Agent, como faria ao atribuir um ticket a um colega. A pessoa responsável permanece registrada em separado.
Para trabalhos pequenos e bem definidos, atribua a Task diretamente a um Agent. Use um Crew, um grupo reutilizável de Pessoas e Agents coordenado por um Agent líder, apenas quando o líder realmente precisar interpretar o objetivo e trazer os resultados dos outros membros de volta para uma única Task. A versão passo a passo de uma primeira atribuição está em como atribuir sua primeira tarefa a um agente de IA.
Passo 3: Execução em um Computer, em um worktree isolado
Quando a Task sai do Backlog e o Agent está pronto, o Sharkly enfileira a execução e a despacha para o Computer selecionado: seu notebook, um servidor remoto ou um contêiner. O serviço local dessa máquina recebe a execução, prepara o diretório da tarefa, inicia o Claude Code e transmite o progresso de volta. Seu código, suas credenciais e sua instalação do Claude Code nunca saem do hardware que você controla.
Vale enunciar claramente a separação de responsabilidades: o Agent define como o trabalho deve ser conduzido; o Computer fornece o host e os recursos locais; o Runtime realiza a sessão de agente propriamente dita; a Task permanece como o registro compartilhado.
Para trabalhos em repositório, o modo de diretório de trabalho recomendado é o Temporary: cada Task recebe um diretório isolado, e o serviço local pode preparar um novo worktree git por execução a partir de dados de repositório em cache. Duas Tasks que mexem no mesmo repositório gravam em dois diretórios diferentes no disco, e é por isso que execuções paralelas não se sobrescrevem. Esse recurso é abordado em como usar git worktrees com agentes de codificação com IA. O modo Specified — um diretório local configurado que as execuções reutilizam — existe para as exceções legítimas: um repositório muito grande, caches locais caros ou ferramentas vinculadas a um único caminho.
Enquanto o Claude Code trabalha, a execução passa por estados visíveis: enfileirada, despachada, em execução e, por fim, concluída, com falha ou cancelada. O estado da execução é separado do status da Task, e essa separação é útil: uma Task pode permanecer In Progress enquanto seu Agent está trabalhando, aguardando uma resposta humana ou reportando um erro, e ninguém precisa ficar consultando o terminal para saber qual é o caso.
Passo 4: Progresso e bloqueios voltam para a Task
Tudo o que o time precisa ver volta para um único lugar. O relatório do Agent é armazenado como um comentário vinculado ao seu trace de execução. O Activity mostra comentários e alterações da tarefa em uma única linha do tempo. O Executions guarda o histórico de execuções: origem do gatilho, horários de início e fim, chamadas de ferramentas e detalhes de falhas.
Os bloqueios vêm à tona em vez de travar silenciosamente. Um Agent pode deixar uma Task aguardando uma resposta ou uma revisão humana, e o trabalho bloqueado alimenta o Inbox, a fila pessoal que separa as Tasks que precisam da sua atenção das atualizações de menor prioridade. A diferença é estrutural: uma sessão travada espera até que você acabe verificando a aba, enquanto uma Task bloqueada avisa a pessoa responsável de que está bloqueada.
Continuar o trabalho é um comentário, não uma nova sessão. Um comentário qualificado em uma Task ainda atribuída ao Agent inicia uma execução de acompanhamento com o contexto acumulado da Task, e comentários rápidos são agrupados para que você não gere execuções pendentes duplicadas.
Passo 5: Revisão humana e aceite
Esse caminho termina onde deveria: com uma pessoa. Os agentes pesquisam, executam, testam e relatam. As pessoas definem a direção, concedem autoridade e aceitam o resultado.
Revisar uma Task gerenciada é ler evidências, não reassistir a uma sessão. O revisor confere o relatório do Agent com os critérios de aceite escritos no Passo 1: manteve-se dentro do escopo, executou as verificações relevantes, apresentou evidências para suas conclusões, registrou incertezas em vez de chutar. O trace de execução está lá para quando o resumo não for suficiente.
O aceite, então, segue um de três caminhos honestos. Aceitar o trabalho e mover a Task para um status de concluída. Solicitar alterações com um comentário focado, o que inicia uma execução de acompanhamento carregando todo o contexto. Ou decidir que a execução deu errado: cancelá-la, ler o log de execução e tentar de novo ou atribuir o trabalho a outro Agent.
Nada disso substitui sua revisão no git. O Claude Code cria branches, grava commits e abre pull requests pelo seu host de git habitual, e sua revisão de merge continua onde está. A Task acrescenta o que a página do PR não consegue mostrar: a solicitação original, as evidências de execução e o aceite registrado.
Sessão solo vs. Task gerenciada
| Pergunta | Sessão solo do Claude Code | Task gerenciada no Sharkly |
|---|---|---|
| Quem pediu isso? | Sua memória | Descrição da Task, com escopo e critérios de aceite |
| Quem está trabalhando nisso? | Quem estiver com o terminal | Pessoa responsável mais um Agent como responsável pela execução |
| O que está acontecendo agora? | Assista ao terminal | Estado da execução na Task, nos boards e no Inbox |
| O que a execução fez? | O histórico do terminal, até a aba fechar | Trace de execução e comentários persistidos |
| Duas execuções podem compartilhar um repositório? | Só se você configurar worktrees manualmente | Worktree isolado por Task, por padrão |
| Quem aprovou o resultado? | Ninguém registra | Revisão e aceite na Task |
| O time pode reutilizar a configuração? | Os prompts ficam com uma única pessoa | Agents e Skills compartilhados no Space |
A coluna da esquerda não é a coluna errada. É a ferramenta certa para exploração e correções rápidas. A coluna da direita se justifica quando o trabalho precisa ser visível, revisável e paralelo.
De uma Task a um projeto gerenciado
Tudo o que foi dito acima escala de uma única Task para um plano sem mudar de forma. As Tasks se agrupam em Projects quando várias servem a um mesmo resultado, e em Sprints quando a pergunta é o que será entregue nesta janela de tempo. As Views salvam as perguntas que um time faz repetidamente, como Tasks aguardando revisão.
Essa é toda a tese deste fluxo de trabalho. A alavancagem do time não vem de abrir mais conversas com IA; vem de compartilhar papéis, regras, contexto e fluxos de trabalho. Onde essa disciplina se encaixa no cenário mais amplo é o tema do nosso guia principal, o que é gerenciamento de projetos com agentes de IA.
Comece menor do que parece necessário. Conecte um Computer, confirme que o Claude Code aparece como um Runtime disponível, crie um Agent com um papel bem delimitado e atribua a ele uma Task de baixo risco com critérios de aceite reais. Revise o resultado como você revisaria o primeiro pull request de um novo colega de time. A documentação do Sharkly aborda cada conceito com mais profundidade.
Perguntas frequentes
O Sharkly substitui o Claude Code?
Não. O Sharkly não é um substituto do Claude Code, do Codex ou de outras ferramentas de execução. O Claude Code realiza a execução: lê o código, edita arquivos, executa comandos e trabalha com o git. O Sharkly adiciona a camada de nível de time ao redor dele, gerenciando atribuição, contexto das tarefas, progresso, bloqueios, resultados e revisão humana.
Preciso de uma assinatura de modelo separada para executar o Claude Code pelo Sharkly?
Não. O uso do modelo continua pelas assinaturas ou chaves de API já configuradas no Claude Code nos seus Computers conectados. A cota do modelo depende das ferramentas de codificação com IA, dos planos e das contas de API que seu time conectar.
Ainda posso usar o Claude Code diretamente no terminal?
Sim, e você deveria. Uma sessão direta ou um Agent Chat independente é a ferramenta certa para explorar uma questão, moldar um plano ou fazer uma alteração local rápida. Migre para uma Task quando o trabalho precisar de responsabilidade, status, histórico de execução ou revisão.
O que acontece quando uma execução falha?
A execução é marcada como com falha na Task, e o log de execução registra o título, além dos detalhes técnicos originais do serviço de modelo. As orientações de solução de problemas do Sharkly mapeiam casos comuns, como limites de taxa, cota esgotada e erros de autenticação, para os próximos passos, e trazem links para a referência de erros do próprio Claude Code. Tente novamente depois de corrigir a causa ou atribua a Task a outro Agent.
Várias Tasks do Claude Code podem rodar no mesmo repositório ao mesmo tempo?
Sim. No modo de diretório de trabalho Temporary, cada Task roda em seu próprio diretório isolado, e execuções baseadas em repositório podem receber cada uma um novo worktree git, de modo que Tasks simultâneas não gravam em um mesmo checkout compartilhado. Os limites de concorrência no Agent e no Computer definem quantas podem rodar ao mesmo tempo.
