Edição 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

> Conduza uma funcionalidade aprovada através de um épico real do Jira, todas as histórias e subtarefas relevantes. Verifique cada alteração com Claude Code, confirme as atualizações e reveja 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 atravessar três sistemas antes de ficar 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 estes sistemas exigem aprovação humana e verificações diretas. Este guia acompanha um programador ou responsável de equipa ao longo de uma funcionalidade real, incluindo **cada história aprovada**, os seus testes originais, atualizações autorizadas no Jira e uma decisão revista sobre as orientações do projeto.

Este procedimento baseia-se em documentação. A BIG CHANGE não acedeu a 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 principal real do Jira e todas as histórias, até ao código revisto, verificações originais e atualizações autorizadas.
- **Porque importa:** O mapa de itens, os registos de testes e as leituras diretas do Jira mostram que trabalho aprovado está concluído e que história permanece aberta.
- **A que estar atento:** Campos e transições específicos do projeto, escritas de resultado incerto e verificações falhadas exigem resoluçã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 possa editar e uma verificação de aceitação original que consiga executar. O trabalho real deve justificar um item principal ao nível de épico, as suas histórias aprovadas e pelo menos uma subtarefa relevante sob uma história no projeto escolhido do Jira Cloud. Se não existir uma subtarefa real, este resultado completo continua pendente; acrescentar um item decorativo falsearia o plano. Registe o requerente, a autoridade de aprovação, a revisão de origem, os dados permitidos, o commit inicial do Git, a via de isolamento ou reversão e quem pode rever código e alterar o estado no Jira.

Verifique 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 ficheiro `CLAUDE.md` do repositório fornece orientações de projeto sem conceder permissão para editar, executar comandos ou enviar dados. Decida que requisitos e código Claude pode receber, que comandos pode executar e o limite de utilização para esta funcionalidade. A utilização de Claude Code pode consumir a quota de uma subscrição ou gerar encargos do fornecedor; [o guia de custos da Anthropic](https://code.claude.com/docs/en/costs) não determina antecipadamente a sua fatura.

Para o Jira, obtenha permissão para consultar e criar os tipos de item relevantes e, mais tarde, comentar ou efetuar transições como utilizador 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 poderá precisar de OAuth. Guarde as credenciais num armazenamento privado de segredos. Exclua-as dos pedidos ao modelo, textos de itens, `CLAUDE.md`, registos e controlo de versões. Acorde a visibilidade dos itens antes de enviar requisitos para o Jira.

Mantenha sete registos privados ao longo do processo: `docs/feature-prd.md`, `ticket-plan.json`, um diário de escrita de itens que apenas aceite acrescentos, `ticket-map.json`, um comprovativo de implementação por história, um diário de atualizações do Jira e uma decisão retrospetiva. São registos da sua funcionalidade, não ficheiros fornecidos ou executados pela BIG CHANGE.

## 1. Aprove um PRD exato

Forneça ao Claude Code a descrição efetivamente aprovada da funcionalidade e peça-lhe que identifique perguntas pendentes antes de redigir `docs/feature-prd.md`. O documento precisa do requerente e responsável pela aprovação, revisão da entrada, problema e utilizador pretendido, âmbito e exclusões, identificadores numerados de requisitos, verificações de aceitação e fontes de prova, 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 respetivo hash. Resolva questões substanciais antes de criar itens ou editar código.

O hash fornece uma origem precisa aos registos posteriores. Se o PRD mudar, reveja 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 um resultado aprovado.

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

Com pedidos autorizados e **apenas 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 identificar os campos obrigatórios de criação e valores permitidos. A Atlassian assinala a operação abrangente `GET /issue/createmeta` como obsoleta na sua [referência da API de itens](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/).

Confirme um item principal real equivalente a épico, itens subordinados ao nível de história e subtarefas suportadas neste projeto. A Atlassian descreve [a hierarquia predefinida e a sua configuração](https://support.atlassian.com/jira-cloud-administration/docs/configure-the-issue-type-hierarchy/); os nomes e identificadores dos tipos não são universais. Examine como funciona o campo Parent do projeto em cada nível subordinado e que campos personalizados ou definições de visibilidade a criação exige. Se o projeto não representar a estrutura aprovada, registe o tipo, campo ou permissão em falta e suspenda a criação. Uma ligação genérica entre itens não estabelece uma relação hierárquica.

## 3. Reveja o plano completo de itens antes de escrever

Relacione cada requisito e verificação de aceitação do PRD em `ticket-plan.json`. Registe o seu `planVersion`, hash do PRD, site e chave do projeto do Jira, identificador local de execução, quem aprovou o plano e quando. Para cada item proposto, registe um identificador local único, identificador local do superior previsto, identificador do tipo descoberto, campos obrigatórios do projeto, resumo, descrição, identificadores de requisitos e aceitação, responsável e visibilidade permitida. O trabalho aprovado determina o número de histórias e subtarefas. Cada subtarefa deve realizar trabalho efetivo sob a sua verdadeira história.

A API REST v3 do Jira utiliza **Atlassian Document Format (ADF)**, um documento JSON estruturado, para descrições de itens e comentários com várias linhas. Prepare esses documentos a partir do conteúdo aprovado e verifique os metadados dos campos devolvidos pelo site antes de construir cada pedido. A [API de itens](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/) documenta a operação de criação; não pode fornecer um objeto de campos pronto para um projeto desconhecido. Uma pessoa deve aprovar a estrutura completa, cobertura de todos os requisitos, relações hierárquicas e destino exato de escrita antes de qualquer `POST`.

## 4. Crie primeiro os itens principais e volte a ler cada item

Crie o item principal aprovado através de `POST /rest/api/3/issue`, depois as suas histórias e, por fim, cada subtarefa real. Antes de **cada** pedido, acrescente ao diário privado uma linha com o identificador de execução, identificador local do item, chave do superior confirmado quando aplicável, destino, hash do pedido exato aprovado, hora UTC da tentativa e estado `pending`. Não inclua tokens. Quando receber HTTP 201, registe o identificador e a chave devolvidos pelo Jira e execute diretamente `GET /rest/api/3/issue/{issueIdOrKey}`. Compare projeto, tipo, resumo, descrição ou referência ao PRD e item superior com o plano aprovado. Assinale a linha como `confirmed` apenas depois dessa leitura. Um superior confirmado permite criar os seus subordinados.

Se um pedido exceder o tempo limite ou a resposta se perder, assinale-o como `unknown`. Examine o Jira por projeto, hora, resumo aprovado e referência do plano, abra diretamente qualquer correspondência provável e peça ao responsável autorizado que esclareça a sua identidade. [A Atlassian avisa que a pesquisa após uma escrita pode apresentar atraso](https://developer.atlassian.com/cloud/jira/platform/search-and-reconcile/). A ausência de resultados não prova que a criação falhou. O identificador de 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` com resultado incerto.

Leia diretamente a estrutura concluída e registe-a em `ticket-map.json`: cada identificador local, identificador e chave reais do Jira, URL canónico do item, projeto, tipo, chave do superior, identificadores do PRD e de aceitação, hora da leitura e referência do diário. Compare **todos** os itens e critérios aprovados com o PRD. Interrompa novas escritas se faltar um item ou estiver sob o superior errado; utilize o processo de correção revisto do projeto.

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

Percorra as histórias aprovadas pela ordem de dependência. Para cada uma, registe a chave do Jira, commit inicial do Git e ramo ou árvore de trabalho, comando original de aceitação, caminhos e comandos permitidos. Peça ao Claude Code que utilize [Plan mode](https://code.claude.com/docs/en/common-workflows) para relacionar os critérios da história com o repositório. Um programador verifica o plano e autoriza uma edição delimitada. A fronteira da história mantém a alteração fácil de rever; não elimina as restantes histórias aprovadas da funcionalidade.

Após a edição, preserve o diff exato, o comando original de verificação com toda a saída e código de saída, os testes específicos relevantes e um veredito por identificador de requisito. Inspecione o código e registos reais. Um plano escrito, ficheiros gerados ou a afirmação de Claude de que os testes passaram não demonstram que a alteração funciona. Suspenda a história perante uma verificação falhada, segredo inesperado, alteração de dependências, escrita externa ou refatorização ampla; corrija dentro do âmbito aprovado e volte a executar a verificação original. Outro revisor de código decide se aceita o commit resultante ou mantém o diff pendente. Registe essa decisão para cada história. [O nosso guia anterior sobre uma alteração revista com Claude Code](https://bigchange.ai/blog/superpowers-claude-code-plan-test-review-change-guide) cobre a fase mais restrita de revisão de código; o PRD e a estrutura completa do Jira definem aqui o âmbito mais amplo da funcionalidade.

## 6. Verifique as atualizações autorizadas no Jira

Para cada história revista, leia o estado atual no Jira e solicite `GET /rest/api/3/issue/{key}/transitions?expand=transitions.fields`. Examine a transição efetivamente disponível para esse utilizador, o destino, os campos obrigatórios e valores permitidos. Um responsável autorizado pode então enviar a transição escolhida através de `POST /rest/api/3/issue/{key}/transitions` com os valores dos campos definidos para o projeto. Volte a ler diretamente o item e confirme o novo estado. Passar uma verificação de código não autoriza, por si só, Done, integração de código ou implementação em produção.

Registe no diário de atualizações do Jira o estado anterior à escrita, transição pretendida, utilizador, pedido e resposta. Publique um comentário ADF factual com provas através de `POST /rest/api/3/issue/{key}/comment`: commit aceite ou diff pendente, verificação original e testes específicos, falhas restantes e decisão do revisor. Volte a ler o identificador e o corpo do comentário criado através da [API de comentários](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-comments/) do Jira. Se alguma escrita tiver uma resposta incerta, examine diretamente o estado ou os comentários antes de considerar outro pedido. Uma lista de transições vazia ou um campo obrigatório indisponível é uma lacuna no fluxo de trabalho ou permissões a resolver com o responsável pelo projeto, não uma autorização para inventar um identificador.

## 7. Decida se `CLAUDE.md` deve mudar

Compare os registos reais de PRD, itens, diff, testes, revisão e Jira. Peça a Claude uma breve retrospetiva que aponte mal-entendidos observados ou verificações em falta. Uma pessoa escolhe uma alteração exata nas orientações ou regista a decisão de não alterar, com revisor e hora. Se aprovada, inspecione e faça commit apenas do diff de `CLAUDE.md` e do respetivo hash. [O guia de memória da Anthropic](https://code.claude.com/docs/en/memory) descreve as orientações do projeto; esta revisão não autoriza automaticamente trabalho futuro. Não acrescente segredos nem transforme uma lição especulativa numa 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 diretamente confirmada; **cada história aprovada** tem o seu estado inicial, diff aceite, provas da verificação original e dos testes específicos e revisão independente; cada transição autorizada e comentário de prova no Jira foi diretamente relido; e uma pessoa tomou uma decisão sobre a retrospetiva. Registe a fase exata em falta se algum elemento 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 proposta de verificação; não demonstra este resultado de implementação.

Uma criação incerta no Jira permanece `unknown` até uma pessoa conciliar a sua identidade. Um superior errado interrompe a criação de subordinados. Os testes falhados conservam os critérios originais. Uma transição em falta ou limite de utilização esgotado deixa um registo parcial datado para o responsável. Limite os requisitos e dados de clientes ao mínimo aprovado para Claude e Jira, verifique os custos e permissões atuais da conta e reserve recursos para revisão humana do código. Este guia documenta um percurso condicional pelas ferramentas; não relata uma funcionalidade concluída, escrita no Jira, execução de modelo, poupança medida, integração ou implementação em produçã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 âmbito delimitado, criação e leitura de itens e operações de transição. Os campos e identificadores do projeto do leitor devem ser descobertos nesse projeto.
- [Atlassian, comentários de itens](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-comments/): criação e leitura de comentários ADF. As permissões e resposta efetiva dependem do site.
- [Atlassian, pesquisa e conciliação](https://developer.atlassian.com/cloud/jira/platform/search-and-reconcile/): explica porque a ausência de resultados imediatamente após uma escrita não esclarece uma criação incerta.
- [Atlassian, hierarquia de tipos de item](https://support.atlassian.com/jira-cloud-administration/docs/configure-the-issue-type-hierarchy/): níveis predefinidos e configuração; a estrutura do projeto escolhido continua a exigir inspeção.
- [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): planeamento, autoridade para editar, orientações de `CLAUDE.md` e utilização. 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 âmbito delimitado, POST/GET de itens e transições; os metadados de criação abrangentes estão obsoletos. Os campos, identificadores 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 a criação e leitura de comentários ADF, sujeitas às permissões reais. Não foi publicado qualquer comentário para este guia.
- [Atlassian, pesquisa e conciliação](https://developer.atlassian.com/cloud/jira/platform/search-and-reconcile/) — Explica a consistência eventual da pesquisa; a ausência de resultados não prova que não existe um item após uma resposta de criação incerta.
- [Atlassian, configurar a hierarquia de tipos de item](https://support.atlassian.com/jira-cloud-administration/docs/configure-the-issue-type-hierarchy/) — Explica a hierarquia predefinida 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 e 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 programação; não comprova a implementação ou verificações do leitor.
- [Anthropic Claude Code, permissões](https://code.claude.com/docs/en/permissions) — Documenta permissões efetivas e aprovações das ferramentas; as orientações de CLAUDE.md, por si só, não autorizam comandos nem escritas.
- [Anthropic Claude Code, memória](https://code.claude.com/docs/en/memory) — Explica as orientações de projeto de CLAUDE.md; a edição retrospetiva proposta exige revisão humana e não é aprendizagem automática.
- [Anthropic Claude Code, custos](https://code.claude.com/docs/en/costs) — A utilização e a faturação variam consoante o plano e fornecedor; neste guia baseado apenas em documentação não foram medidos encargos nem poupanças.