Coroid utiliza desenvolvimento orientado a especificações: a especificação acompanha 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 código, Coroid transforma a solicitação em escopo explícito, exclusões e critérios de aceitação. Esse documento se torna a fonte de verdade para o plano, a implementação, os testes e a revisão final.
O que é desenvolvimento orientado a especificações?
O desenvolvimento orientado a especificações é 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 mesmo da existência do código, sem prescrever a implementação cedo demais. No Coroid, você também pode ativar o fluxo de trabalho opcional 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 esperado. Informe ao Coroid o resultado necessário, 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 aceitação na aba Especificação do Projeto.
- Aprove o plano. O arquiteto transforma o resultado acordado em etapas ordenadas de implementação.
- Construa e verifique. Os agentes de desenvolvedor e 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 de volta ao plano original, aos resultados dos testes, às descobertas e às evidências a 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ê. Consulte Como uma Tarefa se torna um pull request para conhecer todo o caminho de execução.
Por que essa etapa extra?
Uma instrução como "adicionar cache à busca de usuários" tem pelo menos quatro implementações razoáveis e nenhuma definição de conclusão. Um agente escolherá uma delas. Se ela for a sua, será por 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 contra o qual fazer a verificação. Sem critérios de aceitação, 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 do escopo | O que será deliberadamente excluído para evitar o aumento desnecessário do escopo |
| Critérios de aceitação | Como verificar se a funcionalidade atende aos requisitos |
| Contexto | Restrições, convenções e decisões anteriores aplicáveis |
Você pode ler e editar no campo de Especificação da aba antes do início da execução. Para ver a descrição do trabalho e o contexto de apoio que alimentam esse processo, consulte Descrevendo o que você precisa.
Exemplo prático: do resumo inicial à especificação testável
Suponha que o resumo inicial seja:
Add caching to the user lookup so repeated requests are faster.Isso define o resultado desejado, mas deixa escolhas importantes sem definir. Uma especificação útil transforma essas escolhas em limites e critérios de verificação:
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 planejamento 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.
O que torna os critérios de aceitação eficazes
Eles devem ser verificáveis por alguém que não participou da conversa.
Fraco:
Caching works correctly and performance is improved.Forte:
- 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 indica 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 todas essas decisões em aberto.
Os limites 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 resumo — é uma especificação que nunca definiu onde o resumo termina.
Se você não quiser que o módulo circundante seja refatorado durante o processo, especifique isso. "Não alterar os pontos de chamada" é uma instrução legítima e útil.
Erros comuns de especificação
| Erro | Abordagem melhor |
|---|---|
| Descrever a implementação em vez do resultado | Defina o comportamento e as restrições, e deixe o planejamento escolher a implementação |
| Usar termos como "rápido", "seguro" ou "funciona corretamente" | Substitua-os por um limiar observável, comportamento ou teste |
| Omitir os objetivos não alcançados | Nomeie o código, interfaces ou comportamentos adjacentes que devem permanecer inalterados |
| Combinar resultados não relacionados | Divida o trabalho para que uma tarefa resulte em um único pull request passível de revisão |
| Copiar um ticket sem verificar as suposições | Adicione o contexto e as decisões que o repositório não consegue revelar |
Quando você discordar dela
Edite-a. 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 resultaria.
Se a especificação indicar que o trabalho na verdade consiste em duas partes, divida-o em duas tarefas. Uma tarefa deve resultar em um único pull request que uma pessoa possa revisar em uma única sessão.
Para onde isso vai em seguida
Para alterações maiores que uma simples modificação, a especificação se torna um plano. Veja Tarefas, planos, sprints e etapas, explicando como o trabalho é dividido e aprovado antes da escrita de código.
Perguntas frequentes
Uma especificação é o mesmo que um projeto técnico?
Não. Uma especificação define o resultado esperado e os limites exigidos. Um projeto técnico ou plano de implementação descreve a arquitetura e as etapas usadas para alcançar esse resultado.
Toda alteração precisa de uma especificação detalhada?
Não. Uma alteração pequena e sem ambiguidades pode exigir apenas 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 do trabalho.
É possível alterar uma especificação após o início do trabalho?
Sim, mas a alteração deve gerar uma nova versão e disparar uma revisão do plano e do trabalho dependentes. Alterações silenciosas de escopo quebram a cadeia de evidências entre a solicitação e a entrega do pull request.