Edição em Markdown

AI-translated from English; not yet reviewed by a fluent editor.

# Da funcionalidade aprovada ao Jira e a uma alteração verificada com Claude Code

> Leve uma funcionalidade aprovada por um épico real do Jira, todas as histórias e subtarefas relevantes. Verifique cada alteração com Claude Code, confira as atualizações e revise a decisão sobre as orientações do projeto.

By BIG CHANGE Editorial

Published: 2026-10-20T13:23:38.288Z
Updated: 2026-10-20T13:23:38.288Z
Canonical: https://bigchange.ai/blog/claude-code-jira-approved-feature-guide

![Conceptual charcoal illustration of a developer at a standing counter reviewing a generic two-column code diff on an arm-mounted display.](https://bigchange.ai/api/media/file/claude-code-jira-feature-review-hero-v2.png)
AI-generated conceptual illustration by BIG CHANGE.

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](https://code.claude.com/docs/en/permissions) 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](https://code.claude.com/docs/en/costs) 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](https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis); 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](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/).

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](https://support.atlassian.com/jira-cloud-administration/docs/configure-the-issue-type-hierarchy/); 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](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/) 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](https://developer.atlassian.com/cloud/jira/platform/search-and-reconcile/). 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](https://code.claude.com/docs/en/common-workflows) 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](https://bigchange.ai/blog/superpowers-claude-code-plan-test-review-change-guide) 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](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-comments/) 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](https://code.claude.com/docs/en/memory) 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](https://bigchange.ai/blog/map-work-choose-first-ai-task-guide) 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

- [Atlassian, operações de itens da Jira Cloud REST API v3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/): metadados de criação com escopo delimitado, criação e leitura de itens e operações de transição. Os campos e IDs do projeto do leitor precisam ser descobertos nele.
- [Atlassian, comentários de itens](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-comments/): criação e releitura de comentários ADF. As permissões e a resposta real dependem do site.
- [Atlassian, busca e conciliação](https://developer.atlassian.com/cloud/jira/platform/search-and-reconcile/): explica por que a ausência de resultados logo após uma gravação não resolve uma criação de resultado incerto.
- [Atlassian, hierarquia de tipos de item](https://support.atlassian.com/jira-cloud-administration/docs/configure-the-issue-type-hierarchy/): níveis padrão e configuração; a estrutura do projeto escolhido ainda precisa ser examinada.
- [Anthropic, fluxos de trabalho de Claude Code](https://code.claude.com/docs/en/common-workflows), [permissões](https://code.claude.com/docs/en/permissions), [memória](https://code.claude.com/docs/en/memory) e [custos](https://code.claude.com/docs/en/costs): planejamento, autoridade para editar, orientações de `CLAUDE.md` e uso. Não documentam uma execução desta funcionalidade.

## Sources

- [Atlassian Jira Cloud REST API v3, itens](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/) — Documenta metadados de criação com escopo delimitado, POST/GET de itens e transições; os metadados amplos de criação estão obsoletos. Campos, IDs e transições permitidas devem vir do site do leitor.
- [Atlassian Jira Cloud REST API v3, comentários de itens](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-comments/) — Documenta criação e releitura de comentários ADF, conforme as permissões reais. Nenhum comentário foi publicado para este guia.
- [Atlassian, busca e conciliação](https://developer.atlassian.com/cloud/jira/platform/search-and-reconcile/) — Explica a consistência eventual da busca; não encontrar um item após uma resposta incerta de criação não comprova que ele não exista.
- [Atlassian, configurar a hierarquia de tipos de item](https://support.atlassian.com/jira-cloud-administration/docs/configure-the-issue-type-hierarchy/) — Explica a hierarquia padrão e configurável. Os níveis do projeto escolhido e o comportamento de Parent exigem descoberta direta.
- [Atlassian, autenticação básica para APIs REST](https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/) — Documenta e-mail mais token de API para um script privado simples e as diferenças para integrações; as credenciais devem permanecer privadas.
- [Anthropic Claude Code, fluxos de trabalho comuns](https://code.claude.com/docs/en/common-workflows) — Documenta Plan mode e padrões de fluxo de programação; não comprova a implementação ou as verificações do leitor.
- [Anthropic Claude Code, permissões](https://code.claude.com/docs/en/permissions) — Documenta permissões efetivas e aprovações de ferramentas; as orientações de CLAUDE.md, sozinhas, não autorizam comandos nem gravações.
- [Anthropic Claude Code, memória](https://code.claude.com/docs/en/memory) — Explica as orientações de projeto de CLAUDE.md; a edição retrospectiva proposta exige revisão humana e não é aprendizado automático.
- [Anthropic Claude Code, custos](https://code.claude.com/docs/en/costs) — O uso e a cobrança variam conforme o plano e o provedor; este guia baseado apenas em documentação não mediu cobranças nem economia.