A passagem de requisitos para código é onde a adoção de agentes falha silenciosamente. O agente não escreveu código ruim. O problema é que, seis semanas depois, ninguém consegue mostrar de qual requisito veio uma mudança, quem aprovou o escopo ou quais evidências o revisor viu antes de aceitá-la. O código chegou rápido. O registro, não.
Este tutorial constrói o registro de propósito: uma cadeia que vai de um requisito escrito até um pull request mesclado, em que cada elo é algo que você pode abrir. O Spec Kit do GitHub resolve a mesma lacuna com arquivos no repositório. Este guia resolve isso com um sistema de trabalho, usando o Sharkly porque ele mantém toda a cadeia em uma única Task, embora o padrão possa ser transportado para qualquer rastreador capaz de armazenar os mesmos vínculos. Se você quer primeiro o ciclo operacional, comece pelo nosso guia de gestão de projetos com agentes de IA.
Resumo rápido
Um fluxo de trabalho rastreável de requisitos até o código é aquele em que cada artefato aponta para o artefato que o originou: requisito, Task, subtarefas, execuções, pull request, aceite. No Sharkly, o requisito se torna uma Task, um agente propõe a decomposição no modo Plan e uma pessoa a confirma, cada subtarefa é executada em um worktree isolado com um log de execução, o pull request faz o link de volta pelo ID da Task, e uma pessoa aceita o resultado com base nos critérios de aceite definidos no início. Os agentes pesquisam, executam, testam e reportam. As pessoas definem a direção, concedem autoridade e aceitam o resultado.
O que rastreável precisa significar
Rastreabilidade não é um relatório que você gera no final. É uma propriedade da cadeia: cada elo existe por causa do anterior, e você pode percorrê-la em qualquer direção. Seis elos cobrem uma funcionalidade.
| Elo | Onde fica | O que o liga ao elo anterior |
|---|---|---|
| Requisito | Descrição da Task, tipo Requirement ou User Story | A pessoa que o escreveu |
| Decomposição | Subtarefas vinculadas à Task pai | Proposta do modo Plan confirmada |
| Execução | Execuções da Task e log de execução | Atribuição mais um status de prontidão |
| Evidência | Comentário do agente com verificações e resultados | A execução que a produziu |
| Mudança | Pull request | ID da Task no branch, no título ou no corpo |
| Aceite | Mudança de status feita por uma pessoa identificada | Revisão com base nos critérios de aceite |
Se qualquer elo estiver faltando, a cadeia é meramente decorativa. A lacuna mais comum é a última: um pull request mesclado tratado como aceite quando ninguém comparou a mudança com o requisito.
Passo 1: Escreva o requisito como uma Task
Uma Task é a unidade básica de trabalho rastreado no Sharkly, e um Space configurado para desenvolvimento de software começa com os tipos de tarefa Requirement, Bug, Task e User Story. Use Requirement ou User Story para a tarefa pai. O tipo determina quais campos personalizados e quais status de Workflow se aplicam, de modo que um Requirement pode ter seu próprio status de revisão sem poluir o fluxo de trabalho de Bug.
É a descrição que sustenta tudo. Escreva-a pensando em alguém que nunca viu a conversa: por que o trabalho importa, o que está dentro e fora do escopo, os arquivos relevantes ou o comportamento observado, as decisões já tomadas e como a conclusão será revisada. Essa última linha são os critérios de aceite, a âncora do sexto elo. Se você ainda não consegue escrevê-la, o requisito não está pronto, e o Backlog existe exatamente para isso: uma Task atribuída a um agente não é iniciada enquanto permanecer ali.
Anexe os repositórios no nível do Space para que cada subtarefa os herde. Um agente sem vínculos de repositório recorre aos repositórios Git do Space, que é o que você quer para uma funcionalidade com várias Tasks.
Passo 2: Deixe um agente moldar a decomposição e depois confirme
Abra o chat do agente da Task e mude a sessão para o modo Plan. No modo Plan, o agente pode propor ações para sua revisão, e o Sharkly só cria a Task e as subtarefas planejadas depois que você confirma a proposta. Você pode confirmar sem iniciar ou confirmar e iniciar o trabalho.
Este é o elo que a maioria das equipes pula, e é o que torna a decomposição rastreável em vez de improvisada. A proposta fica visível antes de se tornar trabalho: remova a subtarefa que amplia o escopo, adicione a etapa de migração que o agente deixou passar. As subtarefas permanecem no mesmo Space que a tarefa pai, e o Sharkly rejeita autovinculação de pai e ciclos, de modo que a hierarquia permanece uma árvore.
Use um único agente para um requisito que uma só função consegue cobrir. Use um Crew quando o líder precisa interpretar o objetivo, envolver outros membros agentes, como um redator de testes, e trazer os resultados deles de volta para uma única Task. Para uma mudança de três arquivos, o Crew adiciona peças móveis sem adicionar rastreabilidade. Nosso guia sobre Sharkly Crews aborda o modelo em que o líder vem primeiro.
Copie para a descrição da Task qualquer coisa decidida no chat. O chat de uma Task não é um comentário e não aparece na Activity, então uma decisão que existe apenas ali é invisível para a cadeia.
Passo 3: Execute em isolamento, com um rastro
Atribua cada subtarefa a um agente pelo controle de responsável (Assignee) e depois mova-a para fora do Backlog. O Sharkly verifica a categoria de status e a prontidão para execução, coloca a execução na fila e a despacha para o Computer selecionado, onde o serviço local prepara um diretório de tarefa isolado e inicia o Runtime.
Dois detalhes mantêm este elo honesto. A execução inclui o título e a descrição da Task, os comentários recentes e o Workflow do tipo de tarefa com seus status permitidos, de modo que o agente trabalha a partir do requisito, e não de uma paráfrase. E cada execução vinculada a um repositório recebe seu próprio worktree no modo Temporary, de modo que subtarefas paralelas não podem sobrescrever umas às outras. Nosso artigo sobre executar agentes em paralelo sem conflitos de merge explica por que o isolamento é o que torna o fan-out seguro.
O progresso, os eventos de rastreamento e o resultado retornam para a Task. O log de execução registra por que a execução foi enfileirada, quando começou e terminou, chamadas de ferramentas e eventos do Runtime, a origem do gatilho e detalhes de falhas. Esse log é o quarto elo.
Passo 4: Vincule o pull request pelo ID
Conecte a organização do GitHub uma vez e depois coloque o ID da Task no título do pull request, na descrição ou no nome do branch de origem. Tanto um SH-312 isolado quanto Fixes SH-312 criam o vínculo. Os linkbacks comentam a URL da Task no pull request, ativados por padrão para repositórios privados.
Agora, o limite, porque ele importa para a rastreabilidade: palavras como fixes e closes não carregam nenhum significado extra, e mesclar um pull request não altera o status da Task. O Sharkly vincula a mudança à Task; ele não decide que a Task está concluída. O status continua sendo uma decisão humana, que é justamente o ponto do sexto elo. Nosso passo a passo sobre atribuir um ticket do Jira a um agente de IA e receber um PR de volta mostra o mesmo vínculo do ponto de vista do rastreador.
Passo 5: Revise com base no requisito e depois aceite
Um agente pode deixar uma Task aguardando revisão humana, e esse sinal chega à Inbox da pessoa responsável, em Primary. Leia três coisas em ordem: os critérios de aceite do passo um, o comentário do agente listando as verificações que ele executou e o que permanece incerto, e o log de execução. Só então o diff.
Se uma Task de teste separada verifica a mudança, registre essa relação explicitamente. Owners e Admins da organização podem criar tipos de vínculo personalizados, e o exemplo da própria documentação, validates / is validated by, é a aresta de rastreabilidade deste elo. As relações não alteram o status por conta própria, então o aceite ainda precisa ser uma mudança de status feita por uma pessoa.
Uma regra de categoria protege você aqui: mover uma Task para Completed a marca como terminal, mas não cancela uma execução já ativa. Se o agente ainda estiver trabalhando, cancele primeiro e só depois decida.
Onde a cadeia se rompe
O fluxo de trabalho acima tem três pontos de ruptura conhecidos, e vale a pena enunciá-los claramente.
Conclusões deixadas no chat. Sessões de Agent Chat independentes pertencem à pessoa que as criou. Se o design foi definido ali, a Task não fica sabendo.
Execuções iniciadas fora de uma Task. A ação Run Agent de um fluxo de automação não cria uma Task; a execução fica registrada no agente. Aceitável para uma verificação noturna, errado para trabalho de funcionalidade.
Arquivos em vez de um registro. Os arquivos spec.md, plan.md e tasks.md do Spec Kit formam uma cadeia sólida para um desenvolvedor trabalhando em um único repositório. Use-os quando a equipe é você. Use um sistema de trabalho compartilhado quando uma segunda pessoa precisa revisar, aceitar ou perguntar o que aconteceu sem abrir o seu checkout. O Sharkly não substitui o Claude Code, o Codex ou outras ferramentas de execução; ele é a camada que mantém a cadeia visível ao redor delas. A documentação aborda cada conceito com mais profundidade em docs.sharkly.ai.
Perguntas frequentes
De requisitos ao código significa que o agente escreve o requisito? Não. Uma pessoa escreve o requisito e seus critérios de aceite. Um agente pode pesquisar a base de código e propor uma decomposição no modo Plan, mas a proposta só se torna Tasks depois que uma pessoa a confirma.
Posso manter o requisito no Jira e ainda assim obter o rastro? Sim. A importação e a sincronização com o Jira mantêm o rastreador que sua organização consulta, enquanto o Sharkly guarda o registro de execução. Nosso artigo sobre alternativas ao Jira para equipes de humanos e agentes aborda o caso em que o próprio rastreador está em vias de ser substituído.
E se o pull request for mesclado antes da revisão? O status da Task não muda, então a cadeia mostra uma Task não aceita com uma mudança mesclada. Esse é o sinal correto: uma pessoa ainda deve uma decisão.
Qual deve ser o tamanho da primeira funcionalidade rastreável? Um requisito, duas ou três subtarefas, um agente. Nosso passo a passo de gestão de projetos com Claude Code executa o ciclo de ponta a ponta em uma única Task.
