Uma funcionalidade aprovada pode passar por três sistemas antes de ser concluída: um documento de requisitos, uma hierarquia de itens no Jira e um repositório. Claude Code pode ajudar a redigir e implementar o trabalho, mas as relações entre esses sistemas precisam de aprovação humana e verificações diretas. Este guia acompanha uma pessoa desenvolvedora ou líder de equipe por uma funcionalidade real, incluindo cada história aprovada, seus testes originais, atualizações autorizadas no Jira e uma decisão revisada sobre as orientações do projeto.

Este procedimento se baseia em documentação. A BIG CHANGE não acessou um projeto do Jira, executou Claude Code, alterou um repositório nem mediu o tempo de entrega de uma funcionalidade. Os tipos de item, campos, transições, comandos e custos exatos dependem do seu projeto e da sua conta.

A grande mudança

  • O que mudou: É possível acompanhar uma funcionalidade desde o requisito aprovado, passando por um item pai real no Jira e todas as histórias, até o código revisado, verificações originais e atualizações autorizadas.
  • Por que importa: O mapa de itens, os registros de testes e as releituras diretas do Jira mostram qual trabalho aprovado foi concluído e qual história continua aberta.
  • O que observar: Campos e transições específicos do projeto, gravações de resultado incerto e verificações com falha exigem solução humana; as orientações de Claude Code não autorizam o trabalho por si só.

Antes de começar

Escolha uma funcionalidade com uma descrição aprovada pelo responsável, um repositório que você possa editar e uma verificação de aceitação original que consiga executar. O trabalho real deve justificar um item pai no nível de épico, suas histórias aprovadas e pelo menos uma subtarefa relevante sob uma história no projeto escolhido do Jira Cloud. Sem uma subtarefa real, este resultado completo permanece pendente; adicionar um item decorativo falsearia o plano. Registre o solicitante, a autoridade de aprovação, a revisão de origem, os dados permitidos, o commit inicial do Git, o caminho de isolamento ou reversão e quem pode revisar o código e mudar o status no Jira.

Confira a versão, autenticação e permissões de Claude Code na sua instalação. Confirme que o arquivo CLAUDE.md do repositório fornece orientações do projeto sem conceder permissão para editar, executar comandos ou enviar dados. Decida quais requisitos e código Claude pode receber, quais comandos pode executar e o limite de uso para essa funcionalidade. O uso de Claude Code pode consumir a franquia de uma assinatura ou gerar cobranças do provedor; o guia de custos da Anthropic não determina sua fatura antecipadamente.

No Jira, obtenha permissão para visualizar e criar os tipos de item relevantes e, depois, comentar ou realizar transições como usuário autorizado. Um script privado pode usar o método de e-mail e token de API documentado pela Atlassian; uma integração pode precisar de OAuth. Guarde as credenciais em um armazenamento privado de segredos. Não as inclua em prompts, textos de itens, CLAUDE.md, logs nem controle de versão. Combine a visibilidade dos itens antes de enviar requisitos ao Jira.

Mantenha sete registros privados durante o processo: docs/feature-prd.md, ticket-plan.json, um diário de gravação de itens que aceite apenas acréscimos, ticket-map.json, um comprovante de implementação por história, um diário de atualizações do Jira e uma decisão retrospectiva. São registros da sua funcionalidade, não arquivos fornecidos ou executados pela BIG CHANGE.

1. Aprove um PRD exato

Forneça ao Claude Code a descrição realmente aprovada da funcionalidade e peça que identifique dúvidas pendentes antes de redigir docs/feature-prd.md. O documento precisa conter solicitante e responsável pela aprovação, revisão da entrada, problema e usuário pretendido, escopo e exclusões, IDs numerados de requisitos, verificações de aceitação e fontes de evidência, restrições não funcionais, projeto do Jira e questões abertas. Uma pessoa responsável deve comparar o rascunho com a descrição original e aprovar uma revisão exata do conteúdo e seu hash. Resolva questões relevantes antes de criar itens ou editar código.

O hash fornece uma origem precisa aos registros posteriores. Se o PRD mudar, revise novamente o plano de itens e as verificações afetadas; uma falha de implementação não justifica reescrever os critérios de aceitação para obter aprovação.

2. Descubra a hierarquia e os campos deste projeto do Jira

Com solicitações autorizadas e somente de leitura à API REST v3 do Jira, percorra as páginas de GET /rest/api/3/issue/createmeta/{projectIdOrKey}/issuetypes. Para cada tipo de item proposto, percorra as páginas de GET /rest/api/3/issue/createmeta/{projectIdOrKey}/issuetypes/{issueTypeId} para descobrir os campos obrigatórios de criação e os valores permitidos. A Atlassian marca a operação abrangente GET /issue/createmeta como obsoleta na referência da API de itens.

Confirme um item pai real equivalente a épico, filhos no nível de história e subtarefas compatíveis com este projeto. A Atlassian descreve a hierarquia padrão e sua configuração; nomes e IDs de tipos não são universais. Confira como o campo Parent do projeto funciona em cada nível filho e quais campos personalizados ou configurações de visibilidade são exigidos na criação. Se o projeto não representar a estrutura aprovada, registre o tipo, campo ou permissão ausente e suspenda a criação. Um vínculo genérico entre itens não cria uma relação de pai e filho.

3. Revise o plano inteiro de itens antes de gravar

Mapeie cada requisito e verificação de aceitação do PRD em ticket-plan.json. Registre seu planVersion, hash do PRD, site e chave do projeto do Jira, ID local da execução, pessoa que aprovou o plano e horário. Para cada item proposto, registre um ID local exclusivo, ID local do pai pretendido, ID do tipo descoberto, campos obrigatórios do projeto, resumo, descrição, IDs de requisitos e aceitação, responsável e visibilidade permitida. O trabalho aprovado determina a quantidade de histórias e subtarefas. Cada subtarefa precisa realizar trabalho real sob sua história correta.

A API REST v3 do Jira usa Atlassian Document Format (ADF), um documento JSON estruturado, para descrições e comentários com várias linhas. Prepare esses documentos a partir do conteúdo aprovado e confira os metadados de campos retornados pelo site antes de montar cada solicitação. A API de itens documenta a criação; não fornece um objeto de campos pronto para um projeto desconhecido. Uma pessoa deve aprovar a estrutura completa, cobertura de todos os requisitos, relações de parentesco e destino exato de gravação antes de qualquer POST.

4. Crie os pais primeiro e releia cada item

Crie o pai aprovado por meio de POST /rest/api/3/issue, depois suas histórias e então cada subtarefa real. Antes de cada solicitação, acrescente uma linha ao diário privado com ID da execução, ID local do item, chave confirmada do pai quando aplicável, destino, hash da solicitação exata aprovada, horário UTC da tentativa e estado pending. Não inclua um token. Ao receber HTTP 201, registre o ID e a chave retornados pelo Jira e faça diretamente GET /rest/api/3/issue/{issueIdOrKey}. Compare projeto, tipo, resumo, descrição ou referência ao PRD e pai com o plano aprovado. Marque a linha como confirmed somente depois dessa releitura. Um pai confirmado libera a criação dos filhos.

Se uma solicitação expirar ou a resposta se perder, marque-a como unknown. Examine o Jira por projeto, horário, resumo aprovado e referência do plano, abra diretamente qualquer correspondência provável e peça ao responsável autorizado que resolva sua identidade. A Atlassian alerta que a busca após uma gravação pode demorar a refletir o resultado. Não encontrar resultados não prova que a criação falhou. O ID da execução e o diário ajudam na conciliação, mas não fazem o servidor rejeitar criações duplicadas. Nunca repita às cegas um POST de resultado incerto.

Leia diretamente a estrutura concluída e registre em ticket-map.json: cada ID local, ID e chave reais do Jira, URL canônica do item, projeto, tipo, chave do pai, IDs de PRD e aceitação, horário da releitura e referência do diário. Compare todos os itens e critérios aprovados com o PRD. Interrompa novas gravações se faltar um item ou se ele tiver o pai errado; use o processo de correção revisado do projeto.

5. Implemente e revise de forma independente cada história aprovada

Trabalhe nas histórias aprovadas na ordem de dependência. Para cada uma, registre sua chave do Jira, commit inicial do Git e branch ou árvore de trabalho, comando original de aceitação, caminhos e comandos permitidos. Peça ao Claude Code para usar Plan mode e relacionar os critérios da história ao repositório. Uma pessoa desenvolvedora confere o plano e autoriza uma edição delimitada. O limite da história mantém a mudança revisável; não elimina as demais histórias aprovadas da funcionalidade.

Após editar, preserve o diff exato, o comando original de verificação com toda a saída e o status de saída, testes direcionados relevantes e um veredito por ID de requisito. Inspecione o código e os logs reais. Um plano escrito, arquivos gerados ou a afirmação de Claude de que os testes passaram não demonstram que a alteração funciona. Suspenda a história diante de uma verificação com falha, segredo inesperado, mudança de dependência, gravação externa ou refatoração ampla; corrija dentro do escopo aprovado e execute a verificação original novamente. Outra pessoa revisora de código decide se aceita o commit resultante ou mantém o diff pendente. Registre essa decisão para cada história. Nosso guia anterior sobre uma alteração revisada com Claude Code cobre a etapa mais restrita de revisão de código; o PRD e a estrutura completa do Jira aqui definem o limite maior da funcionalidade.

6. Verifique as atualizações autorizadas no Jira

Para cada história revisada, leia o status atual no Jira e solicite GET /rest/api/3/issue/{key}/transitions?expand=transitions.fields. Confira a transição realmente disponível para esse usuário, o destino, os campos obrigatórios e os valores permitidos. Um responsável autorizado pode então enviar a transição selecionada por meio de POST /rest/api/3/issue/{key}/transitions com os valores de campos definidos para o projeto. Releia o item diretamente e confirme o novo status. Passar em uma verificação de código não autoriza por si só Done, mesclagem nem implantação.

Registre no diário de atualizações do Jira o status anterior à gravação, transição pretendida, usuário, solicitação e resposta. Publique um comentário ADF factual de evidência por meio de POST /rest/api/3/issue/{key}/comment: commit aceito ou diff pendente, verificação original e testes direcionados, falhas restantes e decisão da revisão. Releia o ID e o corpo do comentário criado pela API de comentários do Jira. Se qualquer gravação tiver resposta incerta, confira diretamente o status ou os comentários antes de considerar outra solicitação. Uma lista vazia de transições ou um campo obrigatório indisponível é uma lacuna de fluxo de trabalho ou permissões a resolver com o responsável pelo projeto, não uma autorização para inventar um ID.

7. Decida se CLAUDE.md deve mudar

Compare os registros reais de PRD, itens, diff, testes, revisão e Jira. Peça a Claude uma breve retrospectiva que aponte mal-entendidos observados ou verificações ausentes. Uma pessoa escolhe uma alteração precisa nas orientações ou registra a decisão de não mudar, com revisor e horário. Se aprovada, inspecione e faça commit apenas do diff de CLAUDE.md e seu hash. O guia de memória da Anthropic descreve as orientações do projeto; essa revisão não autoriza trabalhos futuros automaticamente. Não acrescente segredos nem transforme uma lição especulativa em regra do projeto.

Conclusão e recuperação

A funcionalidade só está concluída quando a revisão aprovada do PRD corresponde à estrutura de épico, histórias e subtarefas confirmada diretamente; cada história aprovada tem seu estado inicial, diff aceito, evidências da verificação original e dos testes direcionados e revisão independente; cada transição autorizada e comentário de evidência no Jira tem uma releitura direta; e uma pessoa decidiu sobre a retrospectiva. Registre a etapa exata que falta se algum item estiver ausente. Escolher uma primeira tarefa de IA termina antes, na seleção da tarefa e na proposta de verificação; não comprova este resultado de implementação.

Uma criação incerta no Jira permanece unknown até uma pessoa conciliar sua identidade. Um pai errado interrompe a criação de filhos. Testes com falha mantêm seus critérios originais. Uma transição ausente ou limite de uso esgotado deixa um registro parcial datado para o responsável. Reduza requisitos e dados de clientes ao mínimo aprovado para Claude e Jira, confira os custos e permissões atuais da conta e reserve recursos para revisão humana do código. Este guia documenta um caminho condicional pelas ferramentas; não relata funcionalidade concluída, gravação no Jira, execução de modelo, economia medida, mesclagem ou implantação realizadas pela BIG CHANGE.

Fontes e leituras adicionais