Creare un piano tecnico dettagliato

Una specifica definisce ciò di cui hai bisogno per costruire. Un piano tecnico definisce come costruirlo. Questa unità illustra le tecniche di pianificazione avanzate per gli scenari brownfield aziendali.

Rivedere i concetti fondamentali del piano

Il file plan.md funge da documento di progettazione, colmando il divario tra i requisiti di alto livello in spec.md e le attività di implementazione concrete che seguono. Un piano tecnico completo contiene:

• Panoramica dell'architettura: panoramica generale del modo in cui interagiscono i componenti.
• Stack tecnologico e decisioni chiave: documentazione esplicita delle scelte tecnologiche con razionalità.
• Sequenza di implementazione: progressione logica dei passaggi di implementazione.
• Verifica della costituzione: verifica esplicita che le soluzioni proposte siano conformi ai principi del progetto.
• Presupposti e domande aperte: documentazione di presupposti e domande non risolte.

Tenendo presenti questi concetti fondamentali, verranno esaminate le considerazioni avanzate sulla pianificazione per lo sviluppo aziendale.

Separazione delle preoccupazioni - specifica vs piano

La separazione delle problematiche tra specifica e piano tecnico è fondamentale. Anche se la specifica rimane stabile e focalizzata su "cosa", il piano può evolversi man mano che si sperimentano diversi approcci "come".

Si supponga che la specifica richieda una funzionalità di caricamento dei documenti per un portale dei dipendenti interno. La specifica definisce i requisiti utente: limiti delle dimensioni dei file, formati supportati, commenti e suggerimenti per il caricamento e controlli di accesso. Il piano tecnico converte questi requisiti in decisioni architetturali concrete: quale servizio di archiviazione di Azure usare, come strutturare l'API, quale meccanismo di autenticazione implementare e come convalidare i file. Se si decide di passare da una tecnologia a un'altra, ad esempio passando da Archiviazione BLOB di Azure a File di Azure, si aggiorna plan.md mentre spec.md rimane in gran parte invariata. I requisiti delle funzionalità non vengono modificati; viene modificato solo l'approccio di implementazione.

Esaminare la struttura del piano e il contenuto

Un piano tecnico completo contiene diverse sezioni chiave che definiscono collettivamente l'approccio di implementazione.

Panoramica dell'architettura

La panoramica dell'architettura offre una panoramica generale del modo in cui interagiscono i componenti. Per la funzionalità di caricamento dei documenti, l'architettura potrebbe descrivere:

"Implementare un nuovo endpoint /api/documents/upload API back-end per gestire i caricamenti di file multipart. Il front-end React include un nuovo componente DocumentUpload con un indicatore di avanzamento e selezione file. Quando un utente seleziona un file, il front-end convalida le dimensioni e il tipo prima del caricamento. Il back-end riceve il file, convalida di nuovo, lo archivia in Archiviazione BLOB di Azure e registra i metadati nel database SQL. Al termine del caricamento, il front-end aggiorna l'elenco dei documenti per visualizzare il nuovo file."

Questo riepilogo stabilisce il flusso complessivo senza approfondire i dettagli a livello di codice. Garantisce che tutti comprendano i componenti principali e le relative interazioni.

Insieme tecnologico e decisioni chiave

Il piano documenta in modo esplicito le scelte tecnologiche e le motivazioni. In questa sezione viene impedita la confusione futura sul motivo per cui sono state selezionate librerie o servizi specifici.

Esempi di decisioni tecnologiche:

• Back-end: API Web .NET 8 con Azure.Storage.Blobs SDK v12 per le operazioni BLOB.
• Front-end: React 18 con componente Upload di Ant Design per la coerenza dell'interfaccia utente.
• Autenticazione: usare il token ID Microsoft Entra esistente dal contesto di autenticazione del portale.
• Archiviazione: contenitore BLOB di archiviazione di Azure denominato employee-documents.
• Database: estendere il database SQL esistente con una tabella DocumentMetadata (colonne: Id, UserId, FileName, BlobUrl, UploadDate, FileSize).

Ogni decisione deve essere allineata ai requisiti di specifica e ai principi di costituzione. Se la costituzione impone di usare i servizi di Azure per tutte le risorse cloud, il piano seleziona in modo esplicito l'archiviazione BLOB di Azure e fa riferimento a questo principio.

Sequenza di implementazione

Il piano descrive l'ordine dei passaggi di implementazione. Anche se non è granulare come l'elenco di attività generato in un secondo momento, questa sequenza fornisce una progressione logica dall'installazione al completamento.

Sequenza di implementazione tipica per la funzionalità di caricamento del documento:

1. Aggiornamento dello schema del database: creare una tabella DocumentMetadata con indici e vincoli appropriati.
2. Sviluppo di API back-end: implementare l'endpoint POST /api/documents/upload con convalida dei file, integrazione dell'archiviazione BLOB e persistenza dei metadati.
3. Creazione di componenti front-end: creare un componente DocumentUpload con selezione file, convalida lato client e visualizzazione dello stato di caricamento.
4. Integrazione: collegare il componente front-end all'API back-end, gestire le risposte e aggiornare l'elenco di documenti.
5. Protezione avanzata: implementare la convalida del tipo di file lato server, i limiti delle dimensioni e i controlli di autenticazione.
6. Gestione degli errori: aggiungere messaggi di errore completi per gli errori lato client e server.
7. Test: creare unit test per i metodi API e i test di integrazione per il flusso di caricamento.

Questa sequenza garantisce che gli elementi di base (schema del database) esistano prima dell'implementazione dei componenti dipendenti (API che scrive nel database). Ogni passaggio si basa sul lavoro precedente, riducendo la probabilità di problemi di integrazione.

Verifica della Costituzione

Il piano include una sezione di verifica che controlla in modo esplicito le soluzioni proposte contro la costituzione. Questa verifica impedisce la deriva dell'architettura e garantisce la coerenza con i principi del progetto.

Se la costituzione include "Tutte le risorse di archiviazione dei dati devono usare i servizi di Azure" e "le API devono convalidare gli input sia nel client che nel server", la sezione verifica del piano conferma:

• "L'uso dell'archiviazione BLOB di Azure soddisfa i requisiti dei servizi di Azure".
• "L'implementazione della convalida sia nel componente React (client) che nell'API .NET (server) è allineata con il principio di sicurezza approfondito della difesa."
• "Il requisito di autenticazione di Microsoft Entra ID viene soddisfatto usando il contesto di autenticazione del portale esistente".

Questa verifica funge da checkpoint. Se il piano propone qualcosa che viola la costituzione, l'IA lo contrassegna in genere o si nota durante la revisione. Affrontare i conflitti di costituzione nella fase del piano impedisce di rielaborare in un secondo momento.

Presupposti e domande aperte

I piani ben costruiti documentano i presupposti e le domande non risolte. Questa trasparenza consente di identificare potenziali problemi prima dell'inizio dell'implementazione.

Presupposti di esempio:

• "Si supponga che il contenitore di Archiviazione BLOB di Azure "employee-documents" esista e sia configurato per l'accesso privato".
• "Si supponga che il database SQL esistente abbia una capacità di archiviazione sufficiente per i metadati".
• "Si supponga che l'analisi di virus dei file caricati non rientra nell'ambito di questa iterazione".

Domande aperte di esempio:

• "Gli amministratori devono avere la possibilità di eliminare i documenti caricati da altri utenti?"
• "È necessaria la registrazione di controllo per tutti i tentativi di accesso ai documenti?"
• "Il sistema deve inviare notifiche tramite posta elettronica quando vengono caricati i documenti?"

Documentare questi presupposti e domande impedisce l'espansione dell'ambito e assicura che gli stakeholder affrontino decisioni importanti prima di iniziare la codifica. Se un presupposto dimostra un errore durante l'implementazione, è possibile aggiornare di conseguenza il piano.

Generare un piano usando /speckit.plan

GitHub Spec Kit genera piani tramite il /speckit.plan comando in GitHub Copilot Chat. Questo comando usa sia spec.md che constitution.md come input per produrre una progettazione tecnica completa.

Prima di richiamare il comando, considerare l'altro contesto necessario per l'intelligenza artificiale. La codebase esistente, le preferenze tecnologiche e i vincoli dell'infrastruttura influenzano tutti il piano. Fornire questo contesto in anticipo produce risultati più accurati e interattivi.

Per la funzionalità di caricamento dei documenti in uno scenario interno del portale per i dipendenti, è possibile specificare un contesto simile al seguente:

"Il portale esistente usa un front-end React con un back-end api Web .NET 8. È necessario integrare la funzionalità di caricamento in questo stack. Usare Archiviazione BLOB di Azure per la persistenza dei file. Richiedere l'autenticazione di Microsoft Entra ID per tutte le operazioni di caricamento. Nel portale è già disponibile un database SQL per l'archiviazione dei metadati."

Questo contesto guida l'intelligenza artificiale per generare un piano che si adatti perfettamente all'architettura esistente anziché proporre una soluzione greenfield che non sia allineata allo stack corrente.

Richiamare il comando di pianificazione

Aprire GitHub Copilot Chat in Visual Studio Code e immettere /speckit.plan. Se l'intelligenza artificiale richiede altre informazioni, fornire il contesto dell'architettura. GitHub Copilot elabora la specifica, la configurazione e il contesto aggiuntivo per generare plan.md.

La fase di pianificazione potrebbe richiedere qualche istante perché l'IA considera diversi approcci, li controlla in base alle tue preferenze e struttura l'output in un documento di progettazione coerente.

Esaminare e convalidare il piano

La generazione di un piano è solo il primo passaggio. La revisione critica garantisce che il piano sia accurato, completo e allineato alle esigenze del progetto.

Verificare la copertura dei requisiti delle specifiche

Confrontare il piano rispetto a spec.md sistematicamente. Ogni requisito nella specifica deve essere mappato a un approccio di implementazione nel piano.

Ad esempio, se spec.md richiede "Visualizza un messaggio di errore per i file che superano 50 MB", il piano deve descrivere dove e come si verifica questa convalida. Se il piano omette questa convalida, il piano è incompleto o la specifica richiede chiarimenti.

Controllare l'allineamento con gli standard tecnici

Assicurarsi che le scelte tecnologico del piano siano allineate agli standard e alle procedure consigliate dell'organizzazione. Se il team standardizza su librerie o modelli specifici, il piano deve riflettere queste preferenze.

Domande da considerare:

• L'architettura proposta si adatta ai sistemi esistenti?
• Le librerie selezionate sono approvate per l'uso nell'ambiente?
• Le scelte tecnologico sono conformi ai criteri di sicurezza e conformità dell'organizzazione?
• Esistono modelli stabiliti per funzionalità simili da seguire?

Per la funzionalità di caricamento dei documenti in un ambiente di Azure, verificare che Archiviazione BLOB di Azure sia un servizio approvato, che l'approccio di autenticazione sia allineato agli standard di identità aziendali (ad esempio usando l'ID Microsoft Entra) e che lo schema SQL proposto segua le convenzioni di denominazione del database.

Convalidare la conformità alla costituzione

Il piano deve includere la verifica esplicita che le soluzioni proposte siano conformi ai requisiti di costituzione. Esaminare attentamente questa sezione di verifica per assicurarsi che non vengano violati principi.

Se la costituzione richiede "Tutti i segreti devono essere archiviati in Azure Key Vault" e il piano propone di archiviare le stringhe di connessione di Archiviazione di Azure in appsettings.json, esiste un conflitto. Il piano deve essere rivisto per recuperare le stringhe di connessione da Key Vault in fase di esecuzione.

Le violazioni della Costituzione scoperte durante la pianificazione sono facili da correggere. Le violazioni della costituzione individuate durante la revisione del codice o la distribuzione della produzione sono costose e dispendiose.

Iterare e perfezionare il piano

I piani richiedono spesso perfezionamento dopo la generazione iniziale. Non aspettatevi la perfezione al primo tentativo. Usare le funzionalità di chiarimento di GitHub Copilot per migliorare la qualità del piano.

Risolvere ambiguità e lacune

Se il piano contiene istruzioni vaghe come "implementare la gestione degli errori appropriata", premere per informazioni specifiche. Quali errori possono verificarsi? Come deve essere gestito ogni errore? Quali informazioni sugli errori devono essere registrate rispetto a visualizzate agli utenti?

Usare GitHub Copilot Chat per porre domande di completamento: "Quali errori specifici devono essere gestiti dall'endpoint di caricamento?" o "Cosa deve accadere se l'archiviazione BLOB di Azure non è disponibile?" L'intelligenza artificiale può espandere sezioni vaghe in specifiche concrete.

Convalidare la fattibilità tecnica

Verificare che l'architettura proposta sia tecnicamente fattibile in base ai vincoli. Se il piano propone di caricare file da 50 MB in modo sincrono tramite un'API Web con un timeout di 30 secondi, esiste un problema. I file con dimensioni superiori a 50 MB potrebbero richiedere caricamenti in blocchi o timeout aumentati.

Rivolgersi ai membri del team che dispongono di competenze pertinenti. Se il piano propone modifiche allo schema del database, esaminare con un amministratore del database. Se richiede nuove risorse di Azure, verificare con i tecnici dell'infrastruttura che il provisioning sia possibile.

Considerare i requisiti non funzionali

Assicurarsi che il piano risponda ai requisiti non funzionali dalla specifica: prestazioni, sicurezza, scalabilità, gestibilità, accessibilità.

Per il caricamento dei documenti, verificare che il piano includa:

• Prestazioni: quanto rapidamente deve essere completato un caricamento? Qual è il volume di caricamento simultaneo massimo?
• Sicurezza: come vengono analizzati i file per individuare il malware? Come viene controllato l'accesso? Dove vengono archiviati i log di controllo?
• Scalabilità: in che modo il sistema gestisce un aumento del volume di caricamento? Quali sono i limiti di capacità di archiviazione?
• Manutenibilità: come vengono puliti i file caricati quando i dipendenti lasciano l'organizzazione?
• Accessibilità: l'interfaccia utente di caricamento soddisfa gli standard WCAG (Web Content Accessibility Guidelines) 2.1?

Se il piano omette una di queste considerazioni, aggiungerle in modo esplicito. I requisiti non funzionali diventano spesso un ripensamento durante l'implementazione se non vengono affrontati in fase di pianificazione.

Valutare fattibilità e completezza

Valutare se il piano fornisce indicazioni sufficienti per l'implementazione. I piani troppo vaghi ("Implementare il caricamento di file") non sono utili. I piani troppo prescrittivi ("Usare esattamente 47 righe di codice") vincolano eccessivamente.

Il livello di dettaglio corretto fornisce una direzione chiara senza rimuovere tutta la flessibilità. Il piano deve rispondere:

• Quali componenti devono essere creati o modificati?
• Come interagiscono questi componenti?
• Quali tecnologie e librerie vengono usate?
• Qual è l'ordine di implementazione?
• Quali passaggi di verifica garantiscono la correttezza?

Se non è possibile immaginare come implementare la funzionalità dal piano, sono necessari altri dettagli. Se il piano sembra scrivere il codice per te, potrebbe essere troppo dettagliato.

Identificare gli elementi mancanti

Cercare lacune nel piano. Le omissioni comuni includono:

• Gestione degli errori: in che modo il sistema gestisce gli errori di rete, gli errori di archiviazione o i problemi del database?
• Considerazioni sulle prestazioni: esistono problemi relativi alla velocità di caricamento, agli utenti simultanei o ai limiti di archiviazione?
• Strategia di test: quali test devono essere scritti per convalidare l'implementazione?
• Approccio di rollback: se la distribuzione causa problemi, come ripristinare le modifiche?

Risolvere questi gap modificando manualmente plan.md o fornendo più contesto e rigenerando le sezioni pertinenti.

Rigenerare mediante un contesto raffinato

Se il piano iniziale non centra l'obiettivo, fornire un contesto più specifico e rigenerare. Ad esempio, se il piano suggerisce l'uso di un nuovo database, ma è necessario usarne uno esistente, chiarire: "Usare il database EmployeePortal esistente. Aggiungere una tabella DocumentMetadata a questo database anziché crearne una nuova."

Rigenera il piano incorporando /speckit.plan in questo contesto aggiornato. L'intelligenza artificiale regola l'approccio di conseguenza.

Modificare manualmente il piano

Poiché plan.md è un file Markdown, è possibile modificarlo direttamente. Se l'intelligenza artificiale suggerisce un approccio che è 90% corretto ma richiede modifiche minime, modificare il file anziché rigenerare tutto.

Ad esempio, se il piano propone un nome specifico per il contenitore BLOB ma la vostra organizzazione ha convenzioni di denominazione, aggiornate direttamente in plan.md il nome del contenitore.

Collaborare con i membri del team

Negli ambienti di lavoro in team, condividere plan.md per revisione. Uno sviluppatore o un architetto senior può convalidare le decisioni relative all'architettura prima dell'inizio dell'implementazione. Questa revisione tra pari individua i problemi che i controlli automatizzati potrebbero non rilevare.

La revisione da parte del team promuove anche la comprensione condivisa. Quando più sviluppatori lavorano su una funzionalità, la revisione del piano assicura che tutti conoschino l'approccio e possano identificare potenziali conflitti con altri lavori in corso.

Documentare le decisioni relative all'architettura

I piani devono documentare non solo ciò che si creerà, ma perché sono state effettuate scelte architetturali specifiche per aiutare gli sviluppatori futuri a comprendere il contesto decisionale.

Registra le alternative considerate

Quando si sceglie tra più approcci validi, documentare le alternative considerate e il motivo per cui si è scelto uno rispetto agli altri.

Per l'archiviazione file, è possibile considerare tre approcci:

• Archiviazione BLOB di Azure: selezionata per l'efficienza, la scalabilità e l'integrazione con l'ambiente Azure esistente.
• File di Azure: rifiutato a causa di un costo più elevato per l'archiviazione di file di grandi dimensioni e l'overhead del protocollo SMB (Server Message Block) non necessario.
• FILESTREAM del database SQL: rifiutato per evitare di aumentare le dimensioni e la complessità del database.

Questa documentazione impedisce agli sviluppatori futuri di porre domande sui motivi per cui non sono stati usati approcci più semplici. La logica decisionale viene mantenuta anziché persa nel tempo.

Acquisire presupposti

I piani presupmettono i sistemi, l'infrastruttura e i vincoli dell'organizzazione esistenti. Fare in modo esplicito questi presupposti.

Presupposti di esempio per il caricamento di documenti:

• L'approvvigionamento del contenitore employee-documents di Archiviazione BLOB di Azure viene effettuato dal team di infrastruttura prima dello sviluppo.
• L'autenticazione del portale esistente fornisce token ID Microsoft Entra convalidati che possono essere considerati attendibili per l'identificazione dell'utente.
• Il database SQL ha una capacità sufficiente per un'altra tabella di metadati senza richiedere l'espansione dell'archiviazione.
• L'infrastruttura di rete supporta caricamenti HTTP da 50 MB senza restrizioni proxy o firewall.

Se un presupposto risulta errato durante l'implementazione, è possibile rivedere il piano e regolare di conseguenza. I presupposti documentati semplificano l'analisi dell'impatto quando cambiano le circostanze.

Pianificare l'evoluzione futura

Prendere in considerazione il modo in cui la funzionalità può evolversi e assicurarsi che l'architettura soddisfi le estensioni probabili.

Per il caricamento di documenti, i potenziali requisiti futuri possono includere:

• Supporto di altri tipi di file oltre a PDF e DOCX.
• Implementazione della condivisione di file tra dipendenti.
• Aggiunta del controllo delle versioni dei documenti.
• Abilitazione dei caricamenti in blocco di più file.
• Integrazione dell'analisi di virus

Se l'architettura rende difficili queste estensioni, valuta se sia opportuno modificare la progettazione iniziale. Non si implementano ora funzionalità future, ma si evita di trovarsi bloccati in situazioni che rendono dolorose le modifiche future.

Condividere e gestire il piano durante l'implementazione

Il piano diventa il riferimento in tutta l'implementazione. Gli sviluppatori devono consultare regolarmente il piano per assicurarsi che il codice sia allineato all'architettura documentata.

Condividere il piano con gli stakeholder

Dopo aver completato il piano, condividerlo con gli stakeholder pertinenti per la convalida:

• Product manager: verificare che il piano fornisca tutti i requisiti delle specifiche.
• Team di sicurezza: verificare che i controlli di sicurezza soddisfino gli standard dell'organizzazione.
• Team dell'infrastruttura: assicurarsi che sia possibile effettuare il provisioning e la configurazione delle risorse di Azure proposte.
• Team dell'architettura: convalidare l'allineamento con i principi dell'architettura organizzativa.

Questa revisione degli stakeholder rileva i problemi prima dell'inizio dell'implementazione. Se il feedback del team di sicurezza rivela che l'autenticazione proposta non è sufficiente, aggiornare il piano prima di scrivere codice.

Aggiornare il piano in base alle esigenze

I piani sono documenti viventi. Quando si individua durante l'implementazione che un approccio non funziona come previsto, aggiornare il piano in modo da riflettere il nuovo approccio.

Se hai pianificato di memorizzare lo stato di avanzamento del caricamento nel browser localStorage ma scopri che ciò causa problemi nella modalità di navigazione privata, aggiorna il piano per utilizzare lo stato in memoria. Documentare il motivo per cui la modifica è stata necessaria in modo che il ragionamento venga mantenuto.

Mantenere plan.md sincronizzato con l'implementazione effettiva. Quando il piano e il codice divergono, il piano perde valore come documentazione di riferimento.

• Gli approcci di sicurezza soddisfano i requisiti dell'organizzazione?
• La progettazione dello schema del database segue le convenzioni di denominazione?

Se il piano suggerisce l'uso di un database ma il portale esistente ne ha già uno, è probabile che sia eccessivo. Se il piano propone una tecnologia che il team evita, documentare il motivo o modificare il piano.

Problemi comuni di pianificazione per evitare

Evitare questi errori comuni durante la creazione e la revisione dei piani:

• Ignorare la fase di pianificazione: passare direttamente dalla specifica al codice senza un piano aumenta il rischio di errori architetturali. Il tempo investito nella pianificazione paga dividendi impedendo la rielaborazione.

• Accettazione di piani senza revisione: i piani generati dall'IA sono punti di partenza, non progetti finali. Esaminare sempre in modo critico e verificare in base al contesto specifico.

• Implementazione sovra-vincolata: i piani devono guidare, non dettare ogni dettaglio. Lasciare spazio agli sviluppatori per prendere decisioni tattiche appropriate durante l'implementazione.

• Ignorando i conflitti di costituzione: se il piano viola i principi di costituzione, affrontare immediatamente il conflitto. Modificare il piano per rispettare o aggiornare la costituzione se il principio necessita di revisione.

• Dimenticando di aggiornare i piani: quando l'implementazione rivela nuove informazioni, aggiornare plan.md. Piani obsoleti ingannano gli sviluppatori futuri e riducono il valore della documentazione.

Riassunto

Il piano tecnico trasforma la specifica in un'architettura pratica. Genera piani usando /speckit.plan con il contesto appropriato sul tuo stack tecnologico e sulla tua infrastruttura. Rivedere i piani in modo critico per assicurarsi che coprano tutti i requisiti di specifica, siano allineati alla normativa e forniscano indicazioni sufficienti per una corretta implementazione. Usare il piano convalidato per guidare la generazione e l'implementazione delle attività. Considerare plan.md come documento vivente che si evolve con la comprensione e fornisce un contesto prezioso per l'intero ciclo di vita dello sviluppo.