Desenvolvimento orientado a especificações no Jira
O desenvolvimento orientado a especificações envolve escrever uma especificação estruturada antes que um agente comece a desenvolver. Dessa forma, ele cria o que é necessário, em vez de fazer uma suposição plausível. No Jira, essa especificação fica no ticket em que você já trabalha, pois ele carrega a intenção real: resultados, escopo, restrições e critérios de aceitação. Um ticket pode conter a especificação completa de uma tarefa ou uma parte da especificação de uma função maior dividida em vários tickets.
Este guia aborda o que torna uma especificação pronta para o agente, por que o ticket é o lugar certo para ela e como escrever a primeira. Em resumo, o desenvolvimento orientado a especificações no Jira oferece três aspectos:
Uma única fonte de informações que o agente usa como base e o revisor usa para verificar
Critérios de aceitação que definem a conclusão tanto para o agente quanto para a pessoa
Menos retrabalho, porque a intenção é definida antes de o agente escrever uma linha de código
O que é desenvolvimento orientado a especificações?
É uma prática na qual você cria uma especificação estruturada que define o que desenvolver e como medir o sucesso. Dessa forma, o agente a implementa, em vez de tentar adivinhar o que fazer a partir de um prompt de uma linha.
A especificação se torna a fonte de informações. Ela direciona o planejamento, o build e a verificação, e no Jira os três acontecem no mesmo ticket. A ideia é anterior à IA, pois surgiu de práticas de design de APIs e métodos formais, nas quais o comportamento é definido antes de ser implementado.
A definição continua mudando conforme as ferramentas amadurecem, portanto, trate como uma prática, não como um formato de especificação fixo. O que não muda é o passo fundamental: definir o ticket antes que o agente o crie.
A diferença se resume a quando você resolve a ambiguidade. O vibe coding resolve isso depois que o código é escrito; o desenvolvimento orientado a especificações resolve isso antes.
Vibe coding: você direciona o agente com prompts e aceita o que ele retorna, de modo que o escopo, as restrições e os casos extremos que ele assume vêm à tona depois que o código existe.
Orientado a especificações: primeiro você define a intenção, as restrições e os critérios de aceitação para que o agente seja gerado com base em uma definição em vez de um palpite e a revisão seja feita em relação a essa mesma definição no ticket em que ela está.
Para códigos que precisam sobreviver em uma base de código real, um agente sem contexto definido pode oferecer uma resolução muito literal para o ticket e deixar passar a restrição que importava. É aí que o retrabalho começa.
Duas coisas que os prompts costumam misturar: a especificação é o que você está gerando, o plano é como isso é gerado. O desenvolvimento orientado a especificações define o "o que" primeiro e, em seguida, gera o "como" a partir disso. Essa é a etapa que o modo de planejamento nas ferramentas de codificação de IA costuma pular: ele esboça o "como" direto de um prompt, em geral sem nenhuma especificação acordada por trás.
O modo de planejamento pode servir como uma especificação simplificada, mas ele esboça o “como” a partir de um prompt no momento, não a partir de uma especificação acordada que persiste no ticket.
Por que as especificações são importantes para a codificação com IA?
Quando a geração de código fica barata, a parte difícil não é mais escrever código. É definir a coisa certa a gerar. Dessa forma, a especificação, e não o prompt, se torna o artefato mais importante que você produz.
Um prompt one-shot deixa as lacunas para o agente, que as preenche com suposições e produz um código que parece correto, mas resolve o problema errado. Uma especificação preenche essas lacunas primeiro, para que o agente gere com base em uma definição e não em uma suposição. No Jira, essa especificação é o ticket que a equipe já planeja, atribui e revisa.
O que compõe uma especificação que um agente pode usar para gerar?
Uma especificação pronta para o agente responde às perguntas que um bom engenheiro faria antes de começar. No Jira, elas ficam no resumo, na descrição, nos requisitos vinculados e nos critérios de aceitação do ticket. Seis elementos são importantes:
Resultados: o que a mudança deve alcançar, em termos que um revisor possa verificar.
Escopo: o que está incluído e, tão importante quanto, o que fica de fora.
Restrições: os limites de arquitetura, segurança e desempenho a serem respeitados.
Decisões anteriores: contexto já definido, assim o agente não precisa rediscutir.
Informações sobre a tarefa: o ticket dividido em etapas pequenas o suficiente para serem verificadas.
Critérios de aceitação: a definição testável de pronto que o agente trabalha para atingir e pela qual é avaliado. No Jira, eles ficam no ticket, e uma revisão de código por IA pode verificar a alteração com base neles antes de chegar a uma pessoa.
Como o ticket se torna a especificação no Jira
Um ticket bem estruturado pode servir como a especificação na qual o agente se baseia para desenvolver e revisar. A especificação também pode ficar em um documento vinculado, que é como muitas ferramentas de SDD funcionam; o Jira apenas permite que ela fique onde o ticket já funciona. É de nível de especificação quando inclui os seis elementos acima. Um ticket de uma linha "correção do bug de login" não é.
Manter a especificação no ticket tem uma vantagem estrutural: ela fica onde o ticket já está, sendo mais difícil de abandonar do que um arquivo markdown em um repositório que ninguém reabre. Mas isso não faz com que ela se mantenha sozinha. Apenas significa que a especificação e o ticket nunca se distanciam.
Tudo caminha junto: resumo, descrição, requisitos vinculados do Confluence e critérios de aceitação, em um único lugar que tanto o agente quanto o revisor leem.
Um arquivo de repositório, por outro lado, fica separado de onde o ticket é acompanhado, revisado e fechado, por isso fica desatualizado no momento em que o plano muda.
O mesmo ticket se torna o espaço de revisão assim que o agente termina, o local onde a equipe se alinha sobre os requisitos e as dúvidas em aberto.
O Jira define planos com requisitos claros, tarefas e estimativas integrados.
Como o Planejador do Jira gera uma especificação estruturada
A seção anterior abordou a linha de base: transformar um ticket em uma especificação por conta própria. O Planejador do Jira é para iniciativas complexas que abrangem várias equipes, em que escrever cada especificação à mão não é um problema. Começa pela iniciativa e a divide em tickets estruturados, cada um com a própria especificação.
O Planejador do Jira é o acelerador, não a linha de base. O método SDD de linha de base é um ticket bem estruturado mais os critérios de aceitação, e toda equipe pode fazer isso hoje. O Planejador do Jira acelera a parte mais difícil desse ticket: transformar uma solicitação complexa e ambígua em uma especificação estruturada.
Para projetos complexos, o Planejador do Jira se baseia no Teamwork Graph, incluindo a base de código, o histórico do Jira e do Confluence e o contexto da equipe, para definir os requisitos e gerar uma especificação técnica estruturada no Confluence, pronta para um desenvolvedor ou agente de codificação usar como base para gerar. Um plano, vários públicos: legível por humanos, útil para um agente.
O que faz:
Oferece um espaço compartilhado para você e a equipe colaborarem, garantindo o alinhamento prévio antes que um agente execute.
Extrai o contexto de todo o ticket, para que a especificação comece com o que a equipe já sabe em vez de um prompt em branco.
Produz uma especificação que é lida com clareza por uma pessoa e processada sem problemas por um agente, para que o mesmo artefato sirva para revisão e execução.
Mantém a especificação no Confluence, vinculada ao ticket, para que a intenção e as decisões fiquem registradas.
O Planejador do Jira transforma ideias iniciais em especificações estruturadas e prontas para agentes
O Planejador do Jira está em acesso antecipado — faça a inscrição na lista de espera
Como escrever a primeira especificação pronta para agentes no Jira
Pegue um ticket e o transforme à mão em uma especificação pronta para o agente, usando os seis elementos como checklist.
Comece por um ticket. Registre o resultado, os limites do escopo e as restrições na descrição, não apenas um título.
Transforme a intenção em uma especificação estruturada. Este é o verdadeiro ticket SDD. Transforme o contexto anterior em resultados, escopo e restrições no ticket, para que o agente herde uma definição.
Escreva critérios de aceitação testáveis. Estes são os contratos que o agente usa como base para criar e o revisor usa para verificar. A maioria dos critérios no geral precisa de algumas revisões antes de ser testável.
Atribua a um agente de codificação. Um ticket com nível de especificação oferece ao agente o suficiente para implementar e abrir uma pull request vinculada ao item.
Revise a pull request com base nos critérios e depois refine. Refine a especificação em que o agente fez suposições e reutilize o padrão no próximo ticket.
Perguntas frequentes sobre o desenvolvimento orientado a especificações
Preciso do Planejador do Jira para fazer o desenvolvimento orientado a especificações?
Não. A linha de base é um ticket bem estruturado com critérios de aceitação, que qualquer equipe pode escrever hoje. Para tickets complexos, o Planejador do Jira acelera o processo partindo de um plano de alto nível, uma iniciativa e dividindo isso em tickets estruturados do Jira, cada um com as próprias especificações preenchidas, para que você não precise escrever à mão.
Qual é a diferença entre uma especificação e os critérios de aceitação?
A especificação define toda a mudança: resultados, escopo, restrições e contexto. Os critérios de aceitação são uma parte, a definição testável de pronto que o agente busca alcançar e que o revisor usa para verificar.
Um prompt muito bom é o suficiente?
Para tickets pequenos e reversíveis, em geral é, sim. Para qualquer coisa complexa ou difícil de desfazer, um prompt faz o agente adivinhar o que você deixou de fora. Uma especificação elimina as suposições.
A especificação deve ficar em um arquivo do repositório ou em um ticket do Jira?
Um ticket mantém a especificação onde é acompanhado, revisado e fechado. Dessa forma, fica menos propenso a ficar desatualizado do que um arquivo markdown em um repositório que ninguém abre de novo.
O desenvolvimento orientado a especificações atrasa as equipes?
O processo exige mais esforço no início e evita retrabalho depois. Em tickets complexos, essa troca é um ganho líquido. Em correções triviais, pule a especificação e faça o prompt direto.
Quando devo escrever uma especificação e quando devo pular isso?
Escreva uma para um ticket complexo, de alto impacto ou difícil de reverter, ou qualquer coisa com restrições reais de arquitetura ou segurança. Ignore para correções pequenas e reversíveis, quando um prompt rápido for mais ágil.