Crie um plano técnico detalhado

  • 12 minutos

Uma especificação define o que precisa de construir. Um plano técnico define como se constrói. Esta unidade abrange técnicas avançadas de planeamento para cenários empresariais de brownfield.

Revise os fundamentos do plano

O ficheiro plan.md serve como documento de design, fazendo a ponte entre os requisitos de alto nível em spec.md e as tarefas concretas de implementação que se seguem. Um plano técnico abrangente inclui:

  • Visão geral da arquitetura: Visão geral de como os componentes interagem.
  • Pilha tecnológica e decisões-chave: Documentação explícita das escolhas tecnológicas com justificações.
  • Sequência de implementação: Progressão lógica dos passos de implementação.
  • Verificação constitucional: Verificação explícita de que as soluções propostas cumprem os princípios do projeto.
  • Suposições e perguntas em aberto: Documentação de pressupostos e questões por resolver.

Com estes fundamentos em mente, vamos explorar considerações avançadas de planeamento para o desenvolvimento empresarial.

Separação de preocupações - especificação versus plano

A separação das preocupações entre especificação e plano técnico é crucial. Embora a especificação se mantenha estável e focada no "quê", o plano pode evoluir à medida que experimenta diferentes abordagens de "como".

Suponha que a sua especificação exige uma funcionalidade de upload de documentos para um portal interno de colaboradores. A especificação define requisitos do utilizador: limites de tamanho de ficheiro, formatos suportados, feedback de upload e controlos de acesso. O plano técnico traduz estes requisitos em decisões arquitetónicas concretas: que serviço de armazenamento Azure utilizar, como estruturar a API, que mecanismo de autenticação implementar e como validar ficheiros. Se decidir mudar de uma tecnologia para outra, como passar do Armazenamento de Blobs do Azure para Ficheiros do Azure, atualiza plan.md enquanto spec.md permanece praticamente inalterado. Os requisitos das funcionalidades não mudam; apenas a abordagem de implementação é alterada.

Analise a estrutura e o conteúdo do plano

Um plano técnico abrangente contém várias secções-chave que, em conjunto, definem a sua abordagem de implementação.

Visão geral da arquitetura

A visão geral da arquitetura fornece uma visão geral de como os componentes interagem. Para a funcionalidade de upload de documentos, a arquitetura pode descrever:

"Implementar um novo endpoint /api/documents/upload de API back-end para gerir uploads de ficheiros em múltiplas partes. A interface React inclui um novo componente DocumentUpload com um seletor de ficheiros e um indicador de progresso. Quando um utilizador seleciona um ficheiro, a interface valida o tamanho e o tipo antes de carregar. O backend recebe o ficheiro, valida novamente, armazena-o no Armazenamento de Blobs do Azure e regista os metadados na base de dados SQL. Após o upload bem-sucedido, a interface atualiza a lista de documentos para mostrar o novo ficheiro."

Este resumo estabelece o fluxo geral sem entrar em detalhes ao nível do código. Garante que todos compreendem os principais componentes e as suas interações.

Stack tecnológico e decisões-chave

O plano documenta explicitamente as escolhas e justificações tecnológicas. Esta secção evita confusões futuras sobre as razões pelas quais bibliotecas ou serviços específicos foram selecionados.

Exemplos de decisões tecnológicas:

  • Back end: .NET 8 Web API com Azure.Storage.Blobs SDK v12 para operações de blob.
  • Front end: React 18 com o componente Upload da Ant Design para consistência na interface.
  • Autenticação: Utilize o Microsoft Entra ID token existente do contexto de autenticação do portal.
  • Armazenamento: contentor de armazenamento de Blobs do Azure chamado employee-documents.
  • Base de Dados: Estender a base de dados SQL existente com uma tabela DocumentMetadata (colunas: Id, UserId, FileName, BlobUrl, UploadDate, FileSize).

Cada decisão deve alinhar-se tanto com os requisitos da especificação como com os princípios constitucionais. Se a sua constituição exige "Usar os serviços Azure para todos os recursos cloud", o plano seleciona explicitamente Armazenamento de Blobs do Azure e faz referência a este princípio.

Sequência de execução

O plano define a ordem dos passos de implementação. Embora não seja tão detalhada como a lista de tarefas gerada posteriormente, esta sequência fornece uma progressão lógica desde a configuração até à conclusão.

Uma sequência típica de implementação para a funcionalidade de carregamento de documentos:

  1. Atualização do esquema da base de dados: Criar tabela DocumentMetadata com índices e restrições apropriados.
  2. Desenvolvimento de API de back-end: Implementar o endpoint POST /api/documents/upload com validação de ficheiros, integração de armazenamento de blob e persistência de metadados.
  3. Criação de componentes front-end: Construir o componente DocumentUpload com seleção de ficheiros, validação do lado do cliente e exibição do progresso do upload.
  4. Integração: Ligue o componente front-end à API back-end, trate das respostas e atualize a lista de documentos.
  5. Reforço de segurança: Implementar validação de tipos de ficheiros do lado do servidor, limites de tamanho e verificações de autenticação.
  6. Tratamento de erros: Adicione mensagens de erro abrangentes para falhas do lado do cliente e do servidor.
  7. Testes: Criar testes unitários para métodos API e testes de integração para o fluxo de upload.

Esta sequência assegura que os elementos fundamentais (esquema da base de dados) existem antes de os componentes dependentes (API que escreve na base de dados) serem implementados. Cada etapa baseia-se em trabalhos anteriores, reduzindo a probabilidade de problemas de integração.

Verificação constitucional

O plano inclui uma secção de verificação que verifica explicitamente as soluções propostas em relação à constituição. Esta verificação previne desvios arquitetónicos e garante a consistência com os princípios do projeto.

Se a sua constituição incluir "Todo o armazenamento de dados deve usar os serviços Azure" e "As APIs devem validar entradas tanto no cliente como no servidor", a secção de verificação do plano confirma:

  • "Usar o Armazenamento de Blobs do Azure satisfaz o requisito dos serviços Azure."
  • "Implementar validação tanto no componente React (cliente) como na API .NET (servidor) está alinhado com o princípio de segurança de defesa em profundidade."
  • "O requisito de autenticação do Microsoft Entra ID é cumprido utilizando o contexto existente de autenticação do portal."

Esta verificação serve como um ponto de controlo. Se o plano propõe algo que viola a constituição, a IA normalmente assinala isso, ou reparas durante a revisão. Abordar conflitos constitucionais na fase de planeamento impede uma reformulação posterior.

Suposições e questões em aberto

Planos bem elaborados documentam pressupostos e questões por resolver. Esta transparência ajuda-o a identificar potenciais problemas antes do início da implementação.

Exemplos de pressupostos:

  • "Assuma que o contentor Armazenamento de Blobs do Azure 'employee-documents' existe e está configurado para acesso privado."
  • "Assuma que a base de dados SQL existente tem capacidade de armazenamento suficiente para metadados."
  • Assumir que a verificação de vírus dos ficheiros carregados está fora do âmbito desta iteração.

Exemplos de perguntas em aberto:

  • "Os administradores devem ter a capacidade de apagar documentos carregados por outros utilizadores?"
  • "Precisamos de registo de auditoria para todas as tentativas de acesso a documentos?"
  • "O sistema deve enviar notificações por email quando os documentos são carregados?"

Documentar estas suposições e perguntas previne o aumento do âmbito e garante que as partes interessadas abordam decisões importantes antes do início da programação. Se uma suposição se revelar incorreta durante a implementação, pode atualizar o plano em conformidade.

Gera um plano usando /speckit.plan

O GitHub Spec Kit gera planos através do /speckit.plan comando no GitHub Copilot Chat. Este comando utiliza tanto spec.md como constitution.md como insumos para produzir um design técnico abrangente.

Antes de invocar o comando, considere que outro contexto a IA precisa. A sua base de código existente, as preferências tecnológicas e as limitações da infraestrutura influenciam o plano. Fornecer este contexto desde o início produz resultados mais precisos e acionáveis.

Para a funcionalidade de upload de documentos num cenário interno de portal de colaboradores, pode fornecer este contexto:

"O portal existente usa uma interface React com um backend da API Web .NET 8. Precisamos de integrar a funcionalidade de carregamento neste stack. Use Armazenamento de Blobs do Azure para persistência de ficheiros. Exigir autenticação Microsoft Entra ID para todas as operações de upload. O portal já tem uma base de dados SQL disponível para armazenamento de metadados."

Este contexto orienta a IA a gerar um plano que se encaixe perfeitamente na sua arquitetura existente, em vez de propor uma solução greenfield que não esteja alinhada com a sua stack atual.

Invocar o comando de planeamento

Abra o GitHub Copilot Chat no Visual Studio Code e introduza /speckit.plan. Se a IA pedir mais informações, forneça o seu contexto arquitetónico. O GitHub Copilot processa a especificação, a composição e o seu contexto extra para criar o ficheiro plan.md.

A fase de planeamento pode demorar um momento enquanto a IA considera várias abordagens, compara-as com a sua constituição e estrutura o resultado num documento de design coerente.

Rever e validar o plano

Gerar um plano é apenas o primeiro passo. A revisão crítica garante que o plano é preciso, completo e alinhado com as necessidades do seu projeto.

Verificar a cobertura dos requisitos de especificação

Compare o plano com spec.md sistematicamente. Cada requisito na especificação deve corresponder a uma abordagem de implementação no plano.

Por exemplo, se spec.md exigir "Mostrar uma mensagem de erro para ficheiros acima de 50 MB", o plano deve descrever onde e como esta validação ocorre. Se o plano omitir esta validação, ou o plano está incompleto ou a especificação precisa de clarificação.

Verifique o alinhamento com normas técnicas

Assegure que as escolhas tecnológicas do plano estão alinhadas com os padrões e melhores práticas da sua organização. Se a sua equipa padronizar o uso de bibliotecas ou padrões específicos, o plano deve refletir essas preferências.

Perguntas a considerar:

  • A arquitetura proposta encaixa nos sistemas existentes?
  • As bibliotecas selecionadas são aprovadas para uso no seu ambiente?
  • As escolhas tecnológicas cumprem as políticas organizacionais de segurança e conformidade?
  • Existem padrões estabelecidos para funcionalidades semelhantes que devem ser seguidos?

Para a funcionalidade de upload de documentos num ambiente Azure, verifique se o Armazenamento de Blobs do Azure é um serviço aprovado, que a abordagem de autenticação está alinhada com os padrões de identidade empresarial (como usar o Microsoft Entra ID) e que o esquema SQL proposto segue as convenções de nomenclatura da base de dados.

Validar a adesão à constituição

O plano deve incluir uma verificação explícita de que as soluções propostas cumprem os requisitos constitucionais. Revise cuidadosamente esta secção de verificação para garantir que nenhum princípio é violado.

Se a sua constituição exigir "Todos os segredos devem ser armazenados no Azure Key Vault" e o plano propõe guardar as strings de ligação do Armazenamento do Azure em appsettings.json, existe um conflito. O plano deve ser revisto de modo a recuperar cadeias de conexão do Azure Key Vault em tempo de execução.

Violações constitucionais descobertas durante o planeamento são fáceis de corrigir. Violações constitucionais descobertas durante a revisão de código ou implementação em produção são dispendiosas e disruptivas.

Iterar e refinar o plano

Os planos frequentemente exigem aperfeiçoamento após a geração inicial. Não esperes perfeição à primeira. Utilize as capacidades de esclarecimento do GitHub Copilot para melhorar a qualidade dos planos.

Abordar ambiguidades e lacunas

Se o plano contiver declarações vagas como "implementar um tratamento adequado de erros", insista para detalhes específicos. Que erros podem ocorrer? Como deve ser tratado cada erro? Que informação de erro deve ser registada em vez de exibida aos utilizadores?

Use o GitHub Copilot Chat para fazer perguntas de seguimento: "Que erros específicos deve o endpoint de upload tratar?" ou "O que deve acontecer se o Armazenamento de Blobs do Azure não estiver disponível?" A IA pode expandir secções vagas em especificações concretas.

Validar a viabilidade técnica

Verifica se a arquitetura proposta é tecnicamente viável tendo em conta as tuas limitações. Se o plano propõe carregar ficheiros de 50 MB de forma síncrona através de uma API Web com um timeout de 30 segundos, existe um problema. Ficheiros com mais de 50 MB podem exigir uploads em blocos ou tempos de espera aumentados.

Consulte membros da equipa que tenham conhecimentos relevantes. Se o plano propõe alterações no esquema da base de dados, consulte com um administrador da base de dados. Se for necessário novos recursos Azure, confirma com engenheiros de infraestrutura se o provisionamento é possível.

Considerar requisitos não funcionais

Garantir que o plano aborda requisitos não funcionais da especificação: desempenho, segurança, escalabilidade, manutenção, acessibilidade.

Para o carregamento de documentos, confirme que o plano inclui:

  • Desempenho: Com que rapidez deve concluir um upload? Qual é o volume máximo de upload concorrente?
  • Segurança: Como são digitalizados os ficheiros para detetar malware? Como é controlado o acesso? Onde são armazenados os registos de auditoria?
  • Escalabilidade: Como é que o sistema lida com o aumento do volume de upload? Quais são os limites de capacidade de armazenamento?
  • Manutenibilidade: Como são limpos os ficheiros carregados quando os colaboradores saem da organização?
  • Acessibilidade: A interface de upload cumpre as Diretrizes de Acessibilidade de Conteúdos Web (WCAG) 2.1 AA?

Se o plano omitir alguma destas considerações, adicione-as explicitamente. Os requisitos não funcionais tornam-se frequentemente pensamentos laterais durante a implementação se não forem abordados no planeamento.

Avaliar a viabilidade e a completude

Avaliar se o plano fornece orientação suficiente para a implementação. Planos demasiado vagos ("Implementar upload de ficheiros") não ajudam. Planos demasiado prescritivos ("Use exatamente 47 linhas de código") são excessivamente restritivos.

O nível certo de detalhe fornece uma direção clara sem eliminar toda a flexibilidade. O plano deve responder:

  • Que componentes precisam de ser criados ou modificados?
  • Como é que estes componentes interagem?
  • Que tecnologias e bibliotecas são utilizadas?
  • Qual é a ordem de implementação?
  • Que passos de verificação garantem a correção?

Se não consegues imaginar como implementar a funcionalidade a partir do plano, é preciso mais detalhe. Se o plano parecer que está a escrever o código por ti, pode ser demasiado detalhado.

Identificar elementos em falta

Identifique lacunas no plano. Omissões comuns incluem:

  • Gestão de erros: Como é que o sistema lida com falhas de rede, erros de armazenamento ou problemas de base de dados?
  • Considerações de desempenho: Existem preocupações sobre velocidade de upload, utilizadores concorrentes ou limites de armazenamento?
  • Estratégia de testes: Que testes precisam de ser escritos para validar a implementação?
  • Abordagem de reversão: Se a implementação causar problemas, como reverter as alterações?

Aborde estas lacunas editando manualmente plan.md ou fornecendo mais contexto e regenerando secções relevantes.

Regenerar com contexto refinado

Se o plano inicial falhar, forneça um contexto mais específico e regenere. Por exemplo, se o plano sugerir usar uma nova base de dados mas precisar de usar uma já existente, esclareça: "Use a base de dados existente do EmployeePortal. Adicione uma tabela DocumentMetadata a esta base de dados em vez de criar uma nova."

Regenere o plano com /speckit.plan incorporando este contexto atualizado. A IA ajusta a abordagem em conformidade.

Editar manualmente o plano

Como plan.md é um ficheiro Markdown, pode editá-lo diretamente. Se a IA sugerir uma abordagem 90% correta mas que precise de pequenos ajustes, edite o ficheiro em vez de regenerar tudo.

Por exemplo, se o plano propõe um nome específico de contentor de blobs mas a sua organização tem convenções de nomenclatura, atualize o nome do contentor em plan.md diretamente.

Colaborar com os membros da equipa

Em ambientes de equipa, partilhe plan.md para revisão. Um programador sénior ou arquiteto pode validar decisões arquitetónicas antes do início da implementação. Esta revisão por pares detetou problemas que as verificações automáticas podem passar despercebidos.

A revisão em equipa também constrói compreensão partilhada. Quando vários programadores trabalham numa funcionalidade, rever o plano em conjunto garante que todos conhecem a abordagem e conseguem identificar potenciais conflitos com outros trabalhos em andamento.

Documentar decisões arquitetónicas

Os planos devem documentar não só o que irá construir, mas também porque fez escolhas arquitetónicas específicas para ajudar futuros promotores a compreender o contexto das decisões.

Registar alternativas consideradas

Quando estiver a escolher entre várias abordagens viáveis, documente as alternativas que considerou e porque escolheu uma em vez de outras.

Para o armazenamento de ficheiros, pode considerar três abordagens:

  • Armazenamento de Blobs do Azure: Selecionado para custo-benefício, escalabilidade e integração com o ambiente Azure existente.
  • Ficheiros do Azure: Rejeitado devido ao custo mais elevado de armazenamento de ficheiros de grande porte e à sobrecarga desnecessária do protocolo Server Message Block (SMB).
  • SQL Database FILESTREAM: Rejeitado para evitar aumentar o tamanho e a complexidade da base de dados.

Esta documentação impede que futuros programadores questionem porque não foram usadas abordagens mais simples. A justificação da decisão é preservada em vez de perdida com o tempo.

Capturar suposições

Os planos fazem suposições sobre os sistemas, infraestruturas e restrições organizacionais existentes. Tornem estas suposições explícitas.

Exemplos de suposições para o carregamento de documentos:

  • O contentor employee-documents Armazenamento de Blobs do Azure é provisionado pela equipa de infraestrutura antes do início do desenvolvimento.
  • A autenticação do portal existente fornece tokens validados do Microsoft Entra ID que podem ser confiáveis para a identificação do utilizador.
  • A base de dados SQL tem capacidade suficiente para outra tabela de metadados sem necessidade de expansão do armazenamento.
  • A infraestrutura de rede suporta uploads HTTP de 50 MB sem restrições de proxy ou firewall.

Se alguma suposição estiver errada durante a implementação, pode rever o plano e ajustar em conformidade. Pressupostos documentados tornam a análise de impacto simples quando as circunstâncias mudam.

Plano para a evolução futura

Considere como a funcionalidade pode evoluir e garanta que a sua arquitetura acomoda possíveis extensões.

Para o carregamento de documentos, os requisitos futuros potenciais podem incluir:

  • Suporta outros tipos de ficheiros para além de PDF e DOCX.
  • Implementar partilha de ficheiros entre colaboradores.
  • Adicionar versionamento de documentos.
  • Ativar uploads em massa de vários ficheiros.
  • Integrar a varredura de vírus

Se a sua arquitetura dificultar estas extensões, considere se é necessário ajustar o design inicial. Não implementas funcionalidades futuras agora, mas evitas colocar-te em situações complicadas que tornem as mudanças futuras dolorosas.

Partilhe e mantenha o plano durante a implementação

O plano torna-se a sua referência ao longo da implementação. Os programadores devem consultar regularmente o plano para garantir que o seu código está alinhado com a arquitetura documentada.

Partilhe o plano com as partes interessadas

Após finalizar o plano, partilhe-o com as partes interessadas relevantes para validação:

  • Gestores de produto: Verificar se o plano cumpre todos os requisitos da especificação.
  • Equipa de segurança: Confirme que os controlos de segurança cumprem os padrões organizacionais.
  • Equipa de infraestrutura: Garantir que os recursos Azure propostos podem ser provisionados e configurados.
  • Equipa de arquitetura: Validar o alinhamento com os princípios da arquitetura organizacional.

Esta revisão das partes interessadas detetou questões antes do início da implementação. Se o feedback da equipa de segurança revelar que a autenticação proposta é insuficiente, atualiza o plano antes de escrever código.

Atualize o plano conforme necessário

Planos são documentos vivos. Quando descobrir durante a implementação que uma abordagem não funciona como pretendido, atualize o plano para refletir a nova abordagem.

Se planeava armazenar o progresso do upload no localStorage do navegador, mas descobrir que isso causa problemas no modo de navegação privada, atualize o plano para usar o estado em memória. Documenta porque é que a mudança foi necessária para que o raciocínio seja preservado.

Mantém plan.md sincronizado com a implementação real. Quando plano e código divergem, o plano perde valor como documentação de referência.

  • As abordagens de segurança cumprem os requisitos organizacionais?
  • O design do esquema da base de dados segue convenções de nomenclatura?

Se o plano sugerir usar uma base de dados mas o seu portal existente já tem uma, provavelmente é exagero. Se o plano propõe uma tecnologia que a sua equipa evita, documente o motivo ou ajuste o plano.

Armadilhas comuns no planeamento a evitar

Evite estes erros comuns ao criar e rever planos:

  • Saltar a fase de planeamento: Saltar diretamente da especificação para o código sem um plano aumenta o risco de erros arquitetónicos. O tempo investido no planeamento dá frutos ao evitar retrabalhos.

  • Aceitar planos sem revisão: Os planos gerados por IA são pontos de partida, não designs finais. Revê sempre de forma crítica e verifica com base no teu contexto específico.

  • Implementação excessivamente limitada: Os planos devem guiar, não ditar cada detalhe. Deixar espaço para que os programadores tomem decisões táticas apropriadas durante a implementação.

  • Ignorar conflitos constitucionais: Se o plano violar os princípios constitucionais, aborde o conflito imediatamente. Ou ajustar o plano para cumprir ou atualizar a constituição se o princípio precisar de revisão.

  • Esquecer de atualizar planos: Quando a implementação revelar nova informação, atualize plan.md. Planos antiquados iludem programadores futuros e reduzem o valor da sua documentação.

Resumo

O plano técnico transforma a sua especificação numa arquitetura acionável. Gere planos usando /speckit.plan com o contexto adequado sobre a sua stack tecnológica e infraestrutura. Revise os planos de forma crítica para garantir que cobrem todos os requisitos de especificação, estão alinhados com a sua constituição e fornecem orientações suficientes para a implementação. Use o plano validado para orientar a geração e implementação de tarefas. Trata o plan.md como um documento vivo que evolui com a tua percepção e fornece um contexto valioso para todo o ciclo de vida do projeto.