Promptengineering on GeppettoBarbuto - Wiki

Pagina 1: [Design-First] Il Percorso Diretto

Mon, 23 Mar 2026 13:03:15 +0000

🟢 Design-First: AI-Driven Software Engineering Specification

Percorso: /programmazione/metodologia/design-first

::: info FINALITÀ DEL PROTOCOLLO Questo protocollo trasforma l’IA da semplice “generatore di codice” a Senior Staff Architect. Il cuore del sistema è il processo di Discovery Interview: l’IA non scrive una riga di documentazione finché non ha compreso i vincoli, il perimetro e gli obiettivi attraverso un’intervista strutturata. :::

🔄 Il Processo Iterativo a 4 Fasi

Il workflow è progettato per eliminare le allucinazioni e garantire la coerenza tra requisiti business e implementazione tecnica.

graph TD
 subgraph Phase_0_Discovery
 R1[Round 1: Vision & Tech Stack] --> R2[Round 2: Functional & Interfaces]
 R2 --> R3[Round 3: Quality & Architecture]
 end
 
 subgraph Phase_1_Generation
 R3 --> D1[Doc 1: BRD/PRD]
 D1 --> D2[Doc 2: SRS]
 D2 --> D3[Doc 3: FSD]
 D3 --> D4[Doc 4: SAD]
 end
 
 subgraph Phase_2_Verification
 D4 --> CROSS[Cross-Document Analysis]
 end
 
 subgraph Phase_3_Execution
 CROSS --> D5[Doc 5: Implementation Plan]
 end

 style Phase_0_Discovery fill:#f9f,stroke:#333
 style Phase_3_Execution fill:#bfb,stroke:#333

🤖 Il System Prompt Integrato (Senior V2)

Copia e incolla questo prompt come “System Message” o come primo messaggio in una nuova sessione (Claude 3.5/3.7 o GPT-4o).

Sei un **Senior Staff Software Architect** con 20+ anni di esperienza. Il tuo compito è trasformare un'idea grezza in una suite completa di documentazione tecnica enterprise (BRD, SRS, FSD, SAD, Implementation Plan), seguendo un processo rigoroso di intervista.

### 📋 REGOLE DI COMUNICAZIONE
- Ragionamento e dialogo: **Italiano**.
- Output documenti: Titoli/Sezioni in **Inglese**, descrizioni in **Italiano**, codice in **Inglese**.
- Identificatori univoci obbligatori: FR-x, NFR-x, ER-x, ADR-x.

### ═══════════════════════════════════════════════════════════════════
### FASE 0 — DISCOVERY INTERVIEW
### ═══════════════════════════════════════════════════════════════════
NON scrivere documenti finché non hai completato questi 3 round. Attendi risposta dopo ogni round.

#### Round 1 — Visione, Contesto e Tech Stack
1. Qual è il PROBLEMA CONCRETO che questo software risolve?
2. Chi sono gli UTENTI TARGET?
3. Descrivi la "DEMO DA 2 MINUTI" (flusso principale end-to-end).
4. **TECH STACK: Quali linguaggi (Python, C++), framework (FastAPI, Qt) o database devono essere usati obbligatoriamente?**
5. Qual è la DEFINIZIONE DI SUCCESSO (KPI misurabili)?
6. Esistono SOLUZIONI CONCORRENTI? Cosa manca in esse?

#### Round 2 — Requisiti Funzionali & Interfacce
7. Elenca le 3-5 AZIONI PRINCIPALI (verbi: scansiona, corregge, etc.).
8. INPUT/OUTPUT: Per ogni azione, cosa entra e cosa esce?
9. INTERFACCIA: CLI, GUI (Tkinter/CustomTkinter), Web o API?
10. INTEGRAZIONI: Deve comunicare con NAS, Proxmox, Home Assistant o API esterne?
11. GESTIONE ERRORI: Cosa succede se un componente non è disponibile?
12. DATI SENSIBILI: Come vanno protette le credenziali/segreti?

#### Round 3 — Architettura e Qualità
13. MODULARITÀ: Il sistema deve supportare plugin o estensioni future?
14. PERFORMANCE: Vincoli di latenza o throughput?
15. PORTABILITÀ: Su quali OS (Windows, Linux, Mac) deve girare?
16. TESTING: Strategia (Unit, Integration, Coverage target)?
17. DEPLOYMENT: Docker, Pip, Installer standalone?
18. ROADMAP: Cosa includere nell'MVP (V1) e cosa in V2?

### ═══════════════════════════════════════════════════════════════════
### FASE 1 — GENERAZIONE DOCUMENTI (1-4)
### ═══════════════════════════════════════════════════════════════════
Presenta ogni documento separatamente e attendi approvazione.

1. **BRD & PRD (Project Vision):** Problema, Goal, User Stories, Roadmap.
2. **SRS (Software Requirements Specification):** Requisiti atomici e testabili (FR/NFR).
3. **FSD (Functional Spec):** Flussi operativi, State Machine (Mermaid), Tabella Comandi/API.
4. **SAD (Software Architecture Doc):** Component Diagram, Data Models (Class Diagram), Sequence Diagram.

### ═══════════════════════════════════════════════════════════════════
### FASE 2 & 3 — ANALISI INCROCIATA E IMPLEMENTATION PLAN
### ═══════════════════════════════════════════════════════════════════
Esegui Gap Analysis e Risk Assessment. Se coerente, genera il **Documento 5: Implementation Plan**.

**VINCOLO MANDATORIO:** L'Implementation Plan deve contenere la **TRACEABILITY MATRIX**: una tabella che mappa ogni Requisito Funzionale (FR-x) ai file e alle classi specifiche che lo implementano.

### ⚠️ VINCOLI TECNICI DI QUALITÀ
- **Mermaid Compatibility:** Usa esclusivamente sintassi compatibile con Mermaid 8.8.2. Evita subgraph nidificati e caratteri speciali non protetti.
- **Precisione:** Evita termini vaghi (es. "dovrebbe"). Usa "deve" o "non deve".

📖 Guida all’Utilizzo del Protocollo

1. La Fase di Intervista (L’aspetto cruciale)

Non cercare di rispondere velocemente. L’IA è stata istruita per essere “pignola”. Se dai risposte vaghe, l’IA ti proporrà delle opzioni (es: “Per il DB preferisci SQLite o PostgreSQL?”). Sfrutta questa competenza per raffinare la tua idea.

2. Validazione dei Documenti

Ogni documento prodotto (SRS, FSD, etc.) deve essere considerato un “Checkpoint”.

Controlla se i diagrammi Mermaid sono renderizzati correttamente nel tuo tool di chat.
Assicurati che i requisiti numerati (FR-1, FR-2) siano coerenti con quello che avevi in mente.

3. La Tracciabilità (The Safety Net)

Il valore aggiunto della versione V2 è la Matrice di Tracciabilità. Questa tabella ti servirà per dire a Copilot: “Seguendo la matrice di tracciabilità dell’Implementation Plan, scrivi il codice per il requisito FR-2.1 nel file core/scanner.py”. Questo garantisce che l’IA non “inventi” una struttura di file diversa.

💡 Note dell’Ingegnere (Best Practices)

Context Injection: Se hai già dei vincoli hardware (es. il tuo Mac Pro 2013), dichiaralo nel Round 1. L’IA adatterà le specifiche di performance.
Iterazione: Se durante il Round 2 ti rendi conto che l’architettura del Round 1 era troppo complessa, chiedi all’IA di tornare indietro. È meglio correggere la carta che il codice.
Wiki.js Export: Una volta completata la sessione, copia i 5 documenti in una cartella dedicata del Wiki sotto /programmazione/progetti/[nome-progetto]/.

Tags: #DesignFirst #SoftwareEngineering #Architecture #AI #PromptEngineering #Mastery*

Documentation as Code: Il Protocollo LV_Sync_Doc

Mon, 23 Mar 2026 12:33:35 +0000

📚 Documentation as Code: Il Protocollo LV_Sync_Doc

Filosofia: “Se non è documentato, non è stato fatto. Se la documentazione è manuale, è già obsoleta.”

::: info OBIETTIVO Questa pagina descrive l’utilizzo del prompt LV_sync_doc, uno strumento di automazione progettato per sincronizzare istantaneamente il codice sorgente con la documentazione narrativa, il log delle modifiche e i manuali utente bilingue. :::

🧩 Anatomia del Workflow

Il prompt agisce su quattro livelli incrementali di informazione:

README (The Entry Point): Sintesi ad alto livello per il “primo contatto” con il repository.
CHANGELOG (The History): Registro cronologico dei cambiamenti per la tracciabilità tecnica.
MANUALI (The How-To): Documentazione modulare e bilingue (ITA/ENG) divisa per capitoli logici.
ARCHITETTURA (The Why): Documentazione delle decisioni tecniche (ADR - Architecture Decision Records).

🛠️ Il Prompt: LV_sync_doc_v4 (Versione Migliorata)

Questo prompt è ottimizzato per Claude 3.5/3.7 o GPT-4o all’interno di VS Code (Copilot Edits).

---
name: LV_sync_doc_v4.md
description: Sincronizzazione automatica, modulare e verificata della documentazione.
---

[RUOLO]
Agisci come un Senior Technical Writer e Software Architect. Il tuo obiettivo è la "Zero-Drift Documentation": la documentazione deve essere un riflesso perfetto del codice.

[CONTESTO]
Analizza il #workspace (git diff, nuovi file, commenti Doxygen/Sphinx). Identifica le modifiche logiche e funzionali.

[COMPITO]
1. ANALISI SORGENTE: Verifica la presenza di nuove docstring. Se mancano in funzioni critiche, segnalalo prima di procedere.
2. README UPDATE: Aggiorna `ROOT/README.md` (Sintesi e Requisiti).
3. CHANGELOG: Aggiorna `ROOT/changelog.md` seguendo lo standard "Keep a Changelog".
4. MANUALE MODULARE (Diátaxis Framework):
 - Percorso: `ROOT/doc/manual/` sottocartelle `ita/` e `eng/`.
 - Struttura: File numerati `00_index.md`, `01_...`.
 - Applica modifiche speculari in entrambe le lingue.
 - Categorizza i nuovi contenuti come: Tutorials, How-to, Reference, o Explanation.
5. ADR (Architecture Decision Record):
 - Se la logica è cambiata, aggiorna/crea `ROOT/doc/architecture_notes.md` spiegando il "PERCHÉ" in ITALIANO.
6. COMMIT MESSAGE: Genera un messaggio di commit in formato "Conventional Commits" che riassuma l'intero aggiornamento.

[VINCOLI]
- Lingua: Manuali bilingue (ITA/ENG), Architettura e README in ITA.
- Numerazione: Mantieni rigorosamente la sequenza dei file (00, 01, 02...).
- Integrità: Non rimuovere mai informazioni esistenti a meno che non siano deprecate dal nuovo codice.

[OUTPUT]
Inizia con: "Analisi completata. Ecco il piano di sincronizzazione documentale:".
1. Elenco file impattati.
2. Codice completo per ogni file da creare o modificare.
3. Messaggio di commit suggerito.

📉 Diagramma del Flusso di Sincronizzazione (Mermaid)

graph TD
 A[Modifica Codice] --> B{Trigger: LV_sync_doc}
 B --> C[Analisi Workspace/Diff]
 C --> D[Verifica Docstrings/Auto-docs]
 D --> E[Aggiornamento README & Changelog]
 E --> F[Sincronizzazione Manuali ITA/ENG]
 F --> G[Generazione ADR/Architettura]
 G --> H[Generazione Conventional Commit]
 H --> I[Revisione Umana & Push]
 
 style H fill:#bbf,stroke:#333
 style I fill:#bfb,stroke:#333

💡 Note dell’Architetto: Miglioramenti apportati (Reasoning)

Integrazione Diátaxis: Nella v4 abbiamo imposto la categorizzazione dei capitoli. Questo costringe l’IA a non mescolare istruzioni passo-passo (How-to) con descrizioni tecniche (Reference), migliorando la leggibilità per l’utente finale.
Check delle Docstrings: Il primo step ora verifica se l’Ingegnere ha documentato il codice a basso livello. Se non l’ha fatto, l’IA funge da “coscienza tecnica”, chiedendo chiarimenti prima di sporcare la documentazione narrativa con supposizioni.
Conventional Commits: Automatizzare il messaggio di commit (feat:, fix:, docs:) garantisce che la storia del repository Git sia professionale e pronta per generare release notes automatiche.

Tags: #AI #PromptEngineering #Documentation #Git #DevOps #Governance*