Primeiros passos com Sharkly em 10 minutos

Começar a usar o Sharkly leva cerca de dez minutos: conecte um Computador, crie um Agente e atribua uma pequena Tarefa. O Sharkly é um sistema de gestão de trabalho para pessoas e agentes. Ele transforma ferramentas de codificação com IA como Claude Code e Codex em colegas de equipe atribuíveis dentro de um sistema compartilhado de tarefas, para que a execução pare de desaparecer em terminais privados. Veja como é a primeira execução completa:

1. Faça login e crie (ou entre em) uma Organização com um Espaço ativo.
2. Conecte um Computador pelo Sharkly Desktop ou pela Sharkly CLI.
3. Confirme que pelo menos um Runtime, como o Claude Code, aparece como disponível.
4. Crie um Agente com um papel bem específico e instruções claras.
5. Escreva uma Tarefa pequena e bem delimitada e atribua-a ao Agente.
6. Revise o resultado na Tarefa e responda com um comentário de acompanhamento.

O restante deste guia percorre cada etapa na ordem, explica os quatro conceitos por trás delas e mostra o que verificar quando a primeira execução terminar. Ao final, você terá um ciclo de trabalho funcional que pode evoluir para execuções em paralelo, Skills compartilhadas e Sprints.

Por que os primeiros dez minutos com o Sharkly importam

A maioria das equipes já usa agentes de codificação com IA. O problema está em onde esse trabalho acontece: no terminal de uma pessoa, invisível para todo o resto. Alguém cola um chamado do Jira em uma janela de chat, executa um agente, cola o diff de volta, e o raciocínio por trás da mudança não fica registrado em lugar nenhum. Multiplique isso por cinco desenvolvedores e três ferramentas de agente diferentes, e o que sobra são resultados sem histórico.

O Sharkly aborda isso pelo lado da equipe. Não é mais um agente de codificação. A definição oficial é direta quanto ao limite: o Sharkly não substitui o Claude Code, o Codex ou outras ferramentas de execução. Ele adiciona a camada compartilhada de tarefas, contexto, controle e revisão em torno das ferramentas que sua equipe já usa. Essas ferramentas executam; o Sharkly gerencia atribuição, Computadores conectados, contexto da tarefa, progresso, bloqueios, resultados e revisão humana em todas elas.

É por isso que os primeiros dez minutos são estruturados dessa forma. Você não está instalando uma nova IA. Está conectando a IA que já tem a um sistema de registro compartilhado, para que cada execução mantenha contexto, progresso, bloqueios, resultados e revisão humana visíveis da solicitação até a entrega. Se quiser entender primeiro o posicionamento mais amplo, leia O que é o Sharkly? e volte depois; este guia é totalmente prático.

Os quatro conceitos por trás de qualquer configuração no Sharkly

Quatro substantivos sustentam todo o modelo. Entenda bem esses conceitos e nada depois vai confundir você.

Uma Tarefa é a principal unidade de trabalho no Sharkly. Ela registra o objetivo e a descrição, status, prioridade, etiquetas, a pessoa responsável, o Agente ou Crew designado para executar, comentários, anexos e todo o estado e rastreamento da execução.

Um Agente é uma configuração de trabalho salva, e não um prompt pontual. A configuração cuidadosa de uma pessoa (instruções, repositórios vinculados, ambiente, timeouts) passa a ser reutilizável em todo o Espaço quando o Agente é compartilhado.

Um Computador fornece o host de execução. Um pequeno serviço local o conecta ao Sharkly, detecta as ferramentas de agente instaladas, recebe trabalho, prepara o diretório da tarefa, inicia o Runtime selecionado e transmite o progresso de volta. O serviço local inicia a conexão de dentro para fora, então uma configuração típica não precisa de porta de entrada.

Essa separação de responsabilidades é intencional: o Agente define como o trabalho deve ser conduzido, o Computador fornece o host e os recursos locais, o Runtime realiza a sessão, e a Tarefa permanece como o registro compartilhado da equipe. Seu código e suas credenciais ficam em máquinas que você controla.

O que você precisa antes de começar

A lista de pré-requisitos é curta:

• uma conta no Sharkly e uma Organização;
• pelo menos um Espaço ativo;
• um computador capaz de rodar o Sharkly Desktop ou o serviço local;
• um Runtime compatível instalado e autenticado nessa máquina, como Claude Code, Codex ou Gemini CLI;
• acesso ao Git nessa máquina, caso sua primeira Tarefa envolva um repositório privado.

Duas observações sobre o lado dos modelos. Primeiro, traga sua própria assinatura: o uso dos modelos continua pelas assinaturas ou chaves de API configuradas nessas ferramentas, e sua cota depende dos planos e contas que sua equipe conectar. Segundo, o Agente segue o modelo padrão do Runtime. Ele não expõe um seletor de modelo; você troca de modelo na configuração do próprio Runtime, não no Agente.

Você pode organizar Tarefas sem um Computador conectado. Um Agente, porém, não consegue executar trabalho enquanto um Runtime elegível não estiver online — por isso conectar um é a etapa um.

Se sua Organização ainda não tem um Espaço ativo, o Sharkly orienta você a criar um. Escolha uma categoria de trabalho para já vir com tipos de tarefa adequados: desenvolvimento de software começa com Requirement, Bug, Task e User Story. O primeiro Espaço é público para a Organização por padrão, e você pode restringir o acesso depois.

Etapa 1: conecte um Computador

Abra Configurações, depois Computadores, e escolha Conectar Computador. Dois caminhos atendem praticamente todo mundo:

• Sharkly Desktop para um computador pessoal compatível. Instale, faça login, e ele registra a máquina e inicia o serviço local para você.
• Sharkly CLI mais o serviço local para um host remoto ou uma máquina Linux. Gere um token de instalação de uso único na caixa de diálogo de conexão e execute o comando gerado na máquina de destino:

sharkly computer register --install-token sit_9f2ka7x1mrq8

O token de instalação tem vida curta e é de uso único. Não o coloque em uma imagem reutilizável, um script, uma Tarefa ou um comentário. Ele também tem uma função bem específica: um token de instalação registra um Computador e não cria um login humano na CLI. Os tokens de acesso pessoal (que começam com shk_) cuidam disso separadamente.

Aguarde até que o Computador apareça como conectado e então verifique a página de detalhes dele. Cada Runtime detectado informa um status de capacidade: Available, Needs configuration, Not installed ou Unsupported. Essa distinção evita a confusão inicial mais comum. Um Computador online significa apenas que o serviço local dele está enviando heartbeats. Isso não quer dizer que o Runtime selecionado consegue executar uma Tarefa. Se uma execução não iniciar mais tarde, verifique o status de capacidade do Runtime antes de investigar a conexão.

Você também pode verificar pelo terminal:

sharkly computer list
sharkly computer show cmp_4c81d2
sharkly computer ping cmp_4c81d2 rt_claude_code

A documentação de Computadores aborda diagnóstico, Runtimes personalizados, visibilidade e configurações de limpeza em detalhes.

Etapa 2: crie seu primeiro Agente

Abra Agentes e selecione Novo Agente. Resista à tentação de criar um assistente que faz tudo. Comece com um papel bem específico, porque uma descrição focada diz às pessoas o que atribuir, enquanto as instruções dizem ao Agente como trabalhar.

Uma boa primeira configuração é assim:

• Nome: Code Reader
• Descrição: lê um repositório, explica a implementação atual e relata riscos sem alterar arquivos.
• Visibilidade: pessoal, ou o Espaço onde o Agente será usado
• Computador e Runtime: a conexão que você verificou na etapa 1

Para as instruções, vale copiar quase literalmente o exemplo do Quickstart:

Leia a Tarefa completa e os comentários relevantes antes de agir. Mantenha o escopo dentro do que foi solicitado. Para a primeira Tarefa, não edite arquivos. Relate o que você inspecionou, as evidências de cada conclusão e tudo o que permanecer incerto.

Note o que as instruções cobrem: escopo, como inspecionar antes de agir e formato do relato. Esse é o nível certo. Coloque o comportamento estável nas instruções do Agente, os requisitos específicos da Tarefa na descrição da Tarefa, e os procedimentos reutilizáveis que vários Agentes compartilham em uma Skill. Manter essas três camadas separadas é o que torna um Agente reutilizável em vez de frágil.

Etapa 3: adicione um repositório ou diretório de trabalho

Se o seu Agente vai ler código, ele precisa de código para ler. Duas opções:

• Vincular um repositório Git ao Agente (ou usar os repositórios configurados para o Espaço da Tarefa). Execuções baseadas em repositório podem preparar um novo git worktree por Tarefa, e é isso que torna possível uma execução paralela segura mais adiante.
• Configurar um diretório local especificado em um Computador local. As execuções reutilizam o código, as dependências, os caches e as ferramentas que já estão ali, em vez de preparar uma cópia nova.

A regra de decisão: use diretórios temporários baseados em worktree para a maior parte do trabalho com repositórios e sempre que várias Tarefas puderem modificar o mesmo código em paralelo. Use um diretório especificado quando uma execução precisar de um ambiente caro de reconstruir, e lembre-se de que um diretório especificado atende uma execução por vez. Escrevemos um explicador completo sobre como os worktrees evitam que agentes paralelos interfiram uns nos outros, caso você queira entender a mecânica.

Etapa 4: escreva uma Tarefa que um Agente consiga executar

Crie uma Tarefa no mesmo Espaço. O exemplo do Quickstart é deliberadamente sem graça, e é exatamente essa a ideia:

Título: Revisar o fluxo de erro de autenticação

Descrição: Leia a implementação atual de autenticação e identifique três casos de falha visíveis para o usuário. Não altere arquivos. Para cada caso, cite o arquivo ou componente relevante e explique o comportamento esperado. Termine com qualquer pergunta que precise ser respondida antes da implementação.

Essa Tarefa tem as três propriedades que toda boa primeira Tarefa precisa. Tem um limite claro (ler, não editar). Produz um resultado revisável (três casos com evidências). E é de baixo risco, então você pode avaliar o julgamento do Agente sem colocar seu código em risco. Se o seu repositório não tem código de autenticação, troque o assunto por qualquer área pequena que exista, como carregamento de configuração ou um componente de estado vazio.

Atribuir trabalho a um software dessa forma é diferente de fazer um prompt, e deveria ser mesmo. Um prompt é uma conversa; uma Tarefa é um contrato com um resultado revisável. Quando esse ciclo funcionar, o mesmo formato escala para chamados reais: nosso passo a passo sobre como atribuir um chamado do Jira a um agente de IA mostra a versão de produção.

Etapa 5: atribua a Tarefa e acompanhe a execução

Abra o controle de Responsável da Tarefa e escolha o seu Agente. Pessoas, Agentes e Crews podem ser responsáveis; selecionar um Agente faz dele o responsável pela execução.

Uma regra de status define quando a execução começa. Uma Tarefa atribuída a um Agente não inicia uma execução enquanto estiver em Backlog. O Backlog é uma área de espera onde o trabalho é preparado. Mova a Tarefa para um status pronto para trabalho (unstarted ou started), e o Sharkly coloca a execução na fila quando o Computador e o Runtime estiverem prontos. Os status Completed, canceled e duplicate nunca iniciam uma execução inicial.

Enquanto a execução avança, a Tarefa mostra seu estado de execução: queued, dispatched, running e depois completed, failed ou canceled. Uma execução baseada em repositório pode levar um instante fazendo checkout do código e preparando seu diretório isolado. Você tem três visões:

• Chat para a troca em estilo de comentários com o Agente;
• Activity para comentários e alterações da Tarefa em uma única linha do tempo;
• Executions para o histórico de execuções e o rastreamento completo: chamadas de ferramentas, eventos do Runtime, origem do disparo e detalhes de falhas.

O estado da execução e o status da Tarefa são relacionados, mas distintos. Uma execução pode estar em Running enquanto o status da Tarefa ainda diz In Progress, porque um descreve o progresso da execução e o outro descreve a posição no fluxo de trabalho.

Etapa 6: revise o resultado como revisor, não como espectador

A resposta final do Agente volta para a Tarefa como um comentário vinculado ao rastreamento da execução. É aqui que começa o lado humano do contrato: agentes pesquisam, executam, testam e relatam. Pessoas definem a direção, concedem autoridade e aceitam o resultado.

Verifique se o Agente:

• inspecionou o código ou o material de origem pretendido;
• permaneceu dentro do limite de não editar;
• apresentou evidências para cada conclusão;
• registrou incertezas em vez de adivinhar;
• deixou na Tarefa um resultado sobre o qual um colega possa agir.

Se precisar de outra rodada, responda com um comentário focado. Um comentário elegível em uma Tarefa ainda atribuída a esse Agente inicia uma execução de acompanhamento, e comentários enviados em rápida sequência se agrupam para não criar execuções pendentes duplicadas. Se o Agente precisar da sua contribuição ou revisão, essa solicitação pode aparecer na sua Inbox, que separa os itens que exigem a sua resposta das atualizações de menor prioridade.

Quando o resultado se sustentar, marque a Tarefa como concluída. Isso fecha o primeiro ciclo que a lista de verificação de configuração acompanha: Computador conectado, Agente criado, repositório pronto, Tarefa criada, atribuída e concluída.

Depois do primeiro ciclo: cinco formas de evoluir a configuração

A primeira execução prova que a estrutura funciona. Os passos seguintes acrescentam uma dimensão cada.

Como executar mais de uma Tarefa ao mesmo tempo?

Aumente a concorrência de forma deliberada. Com diretórios temporários, a concorrência padrão é metade do limite do Computador; cada Tarefa recebe um worktree isolado para que execuções paralelas não colidam. Fique de olho na CPU, na memória e na capacidade do seu provedor de modelos antes de elevar os limites, e leia como as equipes rodam várias sessões do Claude Code em paralelo para comparar com configurações feitas por conta própria.

Quando usar o Chat do Agente em vez de uma Tarefa?

O Sharkly mantém duas superfícies de propósito. Use o Chat para explorar, planejar ou investigar com um Agente antes que o trabalho precise de acompanhamento. Use uma Tarefa quando o trabalho precisar de responsável, status, histórico de execução ou revisão. Se um Chat produzir algo sobre o qual a equipe precise agir, promova-o a Tarefa para que o resultado fique registrado.

Quando você precisa de um Crew?

Um Crew é um grupo reutilizável de pessoas e agentes coordenado por um Agente líder. Para trabalhos pequenos e bem definidos, atribua a Tarefa diretamente a um Agente e mantenha em zero o número de partes móveis. Use um Crew quando o líder precisar interpretar um objetivo, envolver membros especialistas e trazer os resultados deles de volta para uma única Tarefa.

Quando uma Skill é melhor do que editar instruções?

Quando vários Agentes precisam do mesmo procedimento (uma lista de verificação de revisão, um padrão de migração, um formato de relato), mova-o para uma Skill e vincule-a onde for necessário. O conhecimento de um desenvolvedor vira infraestrutura da organização em vez de um prompt privado.

E o resto da equipe?

Tudo acima funciona no modo individual. O retorno se multiplica quando as Tarefas vivem em Espaços compartilhados, os Sprints agrupam o trabalho em ciclos, e os colegas revisam a produção dos Agentes nas mesmas visões que já usam para o trabalho humano. A camada de projetos do Sharkly (Espaços, Projetos, Sprints, visões de kanban e de lista) é padronizada o suficiente para que ninguém precise de treinamento.

Quando o Sharkly é a ferramenta errada para hoje

Um limite honesto economiza seu tempo. Se você é um desenvolvedor rodando um agente em um repositório, um terminal e uma branch podem ser tudo o que você precisa hoje. A camada de coordenação se paga quando as execuções se multiplicam: mais de um agente, mais de uma pessoa que precisa ver os resultados, ou trabalho que exige revisão antes do merge.

A mesma lógica vale para ferramentas que você mesmo construiu. Sessões de tmux e scripts de worktree caseiros funcionam de verdade; as equipes os abandonam quando as partes invisíveis (quem executou o quê, para onde foi o diff, quem aprovou) passam a custar mais do que os scripts economizam. E se a sua equipe vive de ponta a ponta dentro do ecossistema de um único fornecedor, avalie primeiro a orquestração desse fornecedor. O argumento do Sharkly é mais forte quando você mistura ferramentas, máquinas e pessoas, porque ele se mantém neutro em relação aos três. O contexto mais amplo da categoria está em O que é codificação agêntica?, caso você esteja mapeando o cenário.

O que não muda em nenhum desses casos: mantenha as ferramentas que sua equipe já usa. O caminho de adoção do Sharkly é adicionar uma camada visível e revisável em torno delas, não substituir o fluxo de trabalho por baixo.

Três primeiras execuções que funcionam na prática

A equipe de plataforma cautelosa. Um engenheiro de DevEx conecta um Computador Linux compartilhado, cria um Agente Code Reader somente leitura e deixa os colegas atribuírem Tarefas de investigação por uma semana. Ninguém concede acesso de escrita até que os relatórios se mostrem confiáveis. A adoção se espalha porque os rastreamentos de execução tornam o julgamento do Agente inspecionável.

O desenvolvedor individual escalando. Um desenvolvedor conecta um notebook, cria dois Agentes (um para implementação e outro para revisão) e começa a encaminhar pequenos bugs por meio de Tarefas em vez de prompts improvisados. O ganho imediato não é velocidade; é que cada correção agora tem uma descrição, um diff, um rastreamento e um registro do que foi verificado.

A equipe centrada no Jira. Um gerente de engenharia mantém o Jira como fonte da verdade do planejamento e conecta o Sharkly para que os chamados se tornem Tarefas executáveis. Os desenvolvedores param de copiar e colar o contexto do chamado nos terminais. Resultados, bloqueios e pedidos de revisão voltam para a Tarefa, onde o gerente consegue vê-los.

Seus próximos dez minutos

O menor fluxo de trabalho útil no Sharkly é deliberadamente pequeno: conecte um Computador, crie um Agente e atribua uma Tarefa de baixo risco. Todos os recursos avançados (worktrees paralelos, Crews, Skills, Automações, Sprints) se apoiam nesse ciclo sem alterá-lo.

Então execute o ciclo. Conecte um Computador, crie um Agente e atribua a ele algo sem graça. Revise o resultado como você revisaria o primeiro PR de um novo colega: com atenção, um limite e uma pergunta de acompanhamento. Depois decida, com base em evidências, o que conceder em seguida. O Quickstart na documentação reproduz essas etapas com capturas de tela atualizadas quando você estiver pronto para começar.

Perguntas frequentes

Quais agentes de codificação funcionam com o Sharkly?

O Sharkly detecta ferramentas de agente compatíveis instaladas em um Computador conectado e informa cada uma como um Runtime. Claude Code, Codex, Gemini CLI e OpenCode estão entre as ferramentas citadas na documentação oficial. A página de detalhes do Computador mostra o conjunto atualmente compatível com a sua máquina, com um link para o guia de instalação de cada Runtime, e você pode adicionar um Runtime ACP personalizado se uma ferramenta não for detectada automaticamente.

O Sharkly substitui o Claude Code ou o Codex?

Não. O Sharkly não substitui o Claude Code, o Codex ou outras ferramentas de execução. Essas ferramentas realizam a sessão do agente propriamente dita no seu Computador. O Sharkly adiciona a camada compartilhada em torno delas: atribuição em nível de equipe, contexto da tarefa, progresso, resultados e revisão humana. Você continua usando as ferramentas de agente e as contas que já tem.

Quanto custa o Sharkly?

O modelo do Sharkly é traga a sua própria assinatura: o uso dos modelos passa pelas assinaturas ou chaves de API configuradas nas suas ferramentas de agente, e sua cota depende dos planos que a sua equipe conectar. Para os planos atuais do produto, consulte o sharkly.ai diretamente, já que este artigo não acompanha preços.

Meu código e minhas credenciais passam pelos servidores do Sharkly?

A execução acontece nos Computadores que você conecta: seu notebook, seus servidores ou seus contêineres. O Computador fornece o sistema operacional, os arquivos, as credenciais e as ferramentas, e o serviço local transmite o progresso e os resultados de volta para a Tarefa. Os repositórios são obtidos com o acesso ao Git configurado nesse Computador.

Por que meu Agente não está iniciando uma execução?

Verifique três causas comuns, nesta ordem. Primeiro, a Tarefa pode estar em Backlog; Tarefas atribuídas aguardam ali até serem movidas para um status pronto para trabalho. Segundo, o Runtime pode não estar utilizável; um Computador online confirma apenas os heartbeats, então abra os detalhes do Computador e verifique o status de capacidade do Runtime. Terceiro, a capacidade pode estar cheia; um Agente online ainda pode colocar trabalho na fila quando os limites de concorrência ou de diretórios são atingidos.

Dois Agentes podem trabalhar no mesmo repositório ao mesmo tempo?

Sim, com diretórios de trabalho temporários. Cada Tarefa recebe um diretório isolado, e execuções baseadas em repositório preparam um git worktree separado por execução, o que reduz a interferência entre Tarefas concorrentes. Diretórios especificados são o oposto: um caminho configurado atende uma execução por vez.

Posso rodar Agentes do Sharkly em um servidor remoto?

Sim. Instale a Sharkly CLI e o serviço local no host remoto e registre-o com um token de instalação de uso único obtido na página Computadores. O serviço local se conecta ao Sharkly de dentro para fora, então uma configuração típica não precisa de porta de entrada. Computadores remotos servem para capacidade compartilhada da equipe; notebooks servem para experimentação pessoal.

Qual deve ser a minha primeira Tarefa?

Algo somente leitura, com um limite claro e um resultado revisável. A documentação sugere revisar um fluxo de erro de autenticação e relatar três casos de falha visíveis para o usuário com evidências, sem editar arquivos. Qualquer área pequena e real do seu código serve. Evite primeiras Tarefas vagas como “melhore o código”; você não consegue revisar o que não delimitou.