Coroid utiliza desenvolvimento orientado por especificação: a especificação permanece vinculada a uma tarefa desde o planejamento até os testes e a revisão, garantindo que todas as etapas sigam a mesma definição de sucesso.
Em vez de começar com uma frase e decidir os detalhes enquanto escreve o código, Coroid transforma a solicitação em escopo explícito, exclusões e critérios de aceite. Esse documento se torna a fonte da verdade para o plano, a implementação, os testes e a revisão final.
O que é desenvolvimento orientado por especificação?
O desenvolvimento orientado por especificação é uma forma de criar software a partir de uma descrição acordada e testável do resultado esperado. A especificação define o que vai mudar, o que não vai mudar, quais restrições se aplicam e como um revisor pode confirmar que o trabalho foi bem-sucedido.
Ele separa duas decisões que costumam ser confundidas:
- A especificação define o que significa sucesso.
- O plano de implementação define como alcançá-lo.
Essa separação permite corrigir o escopo antes que o código seja escrito, sem prescrever a implementação precocemente. No Coroid, você também pode ativar o fluxo de trabalho opcional de fluxo de trabalho SDLC quando desejar aprovar a intenção e a especificação antes do início do planejamento.
Como o fluxo de trabalho funciona no Coroid
- Descreva o resultado desejado. Forneça ao Coroid o resultado que você precisa, o contexto relevante e quaisquer restrições ou objetivos não desejados.
- Revise a especificação. Verifique o escopo, as exclusões e os critérios de aceite na aba Especificação da tarefa.
- Aprove o plano. O arquiteto transforma o resultado acordado em etapas ordenadas de implementação.
- Construa e verifique. Os agentes de desenvolvimento e de QA usam os mesmos critérios para implementar a alteração e comprovar cada comportamento prometido.
- Revise o pull request. A alteração entregue traz o plano, os resultados dos testes, as constatações e as evidências de volta à especificação original.
O resultado é a rastreabilidade desde a intenção do produto até o código e as evidências que um revisor humano vê. Veja Como uma tarefa se torna um pull request para conhecer todo o caminho de execução.
Especificação
- Escopo
- Armazenar em cache buscas bem-sucedidas de usuário por ID por 60 segundos.
- Fora de escopo
- Não alterar a assinatura pública de getUser.
- Critérios de aceitação
- Duas buscas em 60 segundos acionam a fonte de dados uma única vez.
ArquitetoPlaneja como atendê-la
DesenvolvedorDesenvolve com base nela
QAComprova cada critério
RevisorCompara o pull request com ela
Por que essa etapa extra?
Uma instrução como "adicionar cache à busca de usuários" tem pelo menos quatro implementações viáveis e nenhuma definição de conclusão. Um agente escolherá uma delas. Se ela for a sua, será sorte.
A especificação torna essa escolha explícita antes do início da implementação, no momento em que mudar de ideia custa menos.
Ela também fornece algo para ser verificado. Sem critérios de aceite, a pergunta "isso funcionou?" se reduz a "os testes ainda passam?", o que é uma questão muito mais fraca.
O que uma especificação contém
| Parte | O que responde |
|---|---|
| Escopo | O que vai mudar |
| Fora de escopo | O que deliberadamente não será incluído, para evitar que a alteração se expanda desnecessariamente |
| Critérios de aceite | Como qualquer pessoa pode confirmar que funcionou |
| Contexto | Restrições, convenções e decisões anteriores que se aplicam |
Você pode ler e editar isso na aba Especificação da tarefa antes do início da execução. Para a descrição do trabalho e o contexto de apoio que alimentam esse processo, veja Descrevendo o que você precisa.
Exemplo prático: do resumo à especificação testável
Suponha que o resumo original seja:
Add caching to the user lookup so repeated requests are faster.Isso indica o resultado desejado, mas deixa escolhas importantes sem definir. Uma especificação útil transforma essas escolhas em limites e verificações:
Scope
- Cache successful user lookups by user id for 60 seconds.
- Invalidate the cached entry when the user record is updated.
Out of scope
- Do not cache failed lookups.
- Do not change the public signature of getUser.
Acceptance criteria
- Two lookups for the same user id within 60 seconds call the data source once.
- Updating that user invalidates the existing cache entry.
- A cache miss preserves the current result and error behavior.Agora o plano pode escolher uma implementação, o QA pode transformar os critérios em testes e o revisor pode comparar o pull request com o comportamento prometido.
Um exemplo registrado: um critério que o plano omitiu
Numa tarefa registrada do Coroid na Expo Coroid, o solicitante estabeleceu seis critérios de aceite para remover style-src 'unsafe-inline' de uma política de segurança de conteúdo. Um deles exigia que as fontes em árabe, japonês e chinês fossem carregadas num navegador real sem violar a política. O plano limitou-se a verificar uma única fonte; todos os critérios planejados foram atendidos e o pull request foi lançado sem a verificação para os três idiomas. A revisão com base nos critérios apresentados revelou a lacuna; uma pessoa solicitou a alteração e o segundo ciclo incluiu um teste de navegador para os três idiomas. Agora, o Coroid lista os critérios do solicitante no plano e recusa planos que os omitam ou reescrevam.
Leia o caso para ver as execuções dos agentes, capturas de tela, tempo decorrido e gastos com modelo.
O que torna os critérios de aceite bons
Eles devem ser verificáveis por alguém que não participou da conversa.
Fraco:
Caching works correctly and performance is improved.Destacado:
- Repeated lookups for the same user id within 60s hit the cache, verified
by a test asserting the data source is called once across two lookups.
- Cache entries are invalidated when the user record is updated.
- A cache miss behaves identically to today, including error handling.
- No change to the public signature of `getUser`.A segunda versão informa ao agente desenvolvedor o que construir, ao agente de QA o que testar e a você o que verificar no pull request. A primeira deixa cada uma dessas decisões em aberto.
As linhas de escopo são tão importantes quanto os critérios.
A causa mais comum de um pull request excessivamente grande não é um agente ultrapassando seu escopo, mas sim uma especificação que nunca definiu onde o escopo termina.
Se você não quiser que o módulo circundante seja refatorado enquanto estiver lá, indique isso. "Não altere os pontos de chamada" é uma instrução legítima e útil.
Erros comuns em especificações
| Erro | Abordagem melhor |
|---|---|
| Descrever a implementação em vez do resultado esperado | Defina o comportamento e as restrições, e deixe que o plano escolha a implementação. |
| Usar termos como "rápido", "seguro" ou "funciona corretamente" | Substitua-os por um limite observável, comportamento ou teste. |
| Omitir objetivos não desejados | Indique o código, as interfaces ou os comportamentos adjacentes que devem permanecer inalterados. |
| Combinar resultados não relacionados | Divida o trabalho para que uma tarefa resulte em um pull request passível de revisão. |
| Copiar um ticket sem verificar as premissas | Adicione o contexto e as decisões que o repositório não consegue revelar. |
Quando você discordar dele
Edite-o. A especificação é um documento dinâmico até o início da execução, e corrigi-la custa muito menos do que corrigir o código que dela derivaria.
Se a especificação indicar que o trabalho na verdade corresponde a duas tarefas distintas, divida-as em duas. Uma tarefa deve resultar em um pull request que uma pessoa possa revisar em uma única sessão.
Próximos passos
Para qualquer alteração além de uma pequena mudança, a especificação se torna um plano. Veja Tarefas, planos, sprints e fluxos de trabalho, que explica como o trabalho é dividido e aprovado antes da escrita do código.
Perguntas frequentes
Uma especificação é o mesmo que um projeto técnico?
Não. Uma especificação define o resultado e os limites exigidos. Um projeto técnico ou plano de implementação descreve a arquitetura e os passos usados para alcançar esse resultado.
Toda alteração precisa de uma especificação detalhada?
Não. Uma alteração pequena e inequívoca pode precisar apenas de algumas linhas de escopo e critérios de aceitação. A especificação deve eliminar incertezas relevantes, não gerar burocracia desnecessária.
Quem deve aprovar a especificação?
A pessoa responsável pelo resultado deve confirmar que o escopo e os critérios atendem às necessidades da equipe. Avaliadores técnicos, de segurança ou de conformidade podem participar quando suas restrições impactarem o sucesso.
Uma especificação pode ser alterada após o início do trabalho?
Pode, mas a alteração deve gerar uma nova versão e disparar a revisão do plano e do trabalho dependentes. Alterações silenciosas de escopo rompem a cadeia de evidências entre a solicitação e o pull request entregue.