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*

AI-Powered Unit Testing: La Difesa Logica

Mon, 23 Mar 2026 12:18:50 +0000

🧪 AI-Powered Unit Testing: La Difesa Logica

Assioma: “Il codice generato dall’IA non esiste finché non esiste un test che ne dimostri la correttezza.”

::: info OBIETTIVO Utilizzare gli assistenti IA per generare suite di test complete (Happy Path, Edge Cases, Failures) che fungano da “rete di sicurezza”. Impareremo il workflow AI-Driven TDD (Test-Driven Development) per garantire che ogni refactoring suggerito dall’IA sia privo di regressioni. :::

1. Il Workflow: “The AI Validation Loop”

Non chiedere all’IA di “scrivere il codice e i test insieme”. Fallo in tre step separati per massimizzare il rigore:

Draft: Chiedi all’IA di generare la funzione (es. in Python o C++).
Challenge: Apri un file di test e fornisci la funzione come contesto. Chiedi: “Agisci come un esperto QA Engineer. Genera una suite di test completa per questa funzione, includendo casi limite, input nulli e scenari di errore.”
Execute: Esegui i test. Se falliscono, dai l’errore in pasto all’IA per il fix.

2. Tecniche di Testing per lo Stack IA

A. Python (PyTest & Mocks)

Quando l’IA genera codice Python, spesso dimentica di isolare le dipendenze (es. chiamate a database o API).

Prompt Strategy: “Usa pytest e unittest.mock per testare questa funzione senza toccare il database reale.”

B. C++ (GoogleTest / Catch2)

In C++, il focus deve essere sulla Memory Safety e sui Boundary Checks.

Prompt Strategy: “Genera test unitari usando GoogleTest. Assicurati di coprire i casi di buffer overflow e puntatori nulli.”

📈 Ciclo di Sviluppo Proattivo (Mermaid)

graph TD
 A[Requisito Funzionale] --> B[AI: Generazione Codice]
 B --> C[AI: Generazione Unit Tests]
 
 subgraph Test_Suite
 C --> C1[Happy Path: Input validi]
 C --> C2[Edge Cases: Valori limite]
 C --> C3[Error Handling: Eccezioni]
 end
 
 C1 & C2 & C3 --> D{Esecuzione: pytest / gtest}
 D -->|Fail| E[AI: Debug & Auto-fix]
 E --> D
 D -->|Pass| F[Codice Validato]
 
 style E fill:#f96,stroke:#333
 style F fill:#4CAF50,color:#fff

3. Strategie Avanzate di Prompting per i Test

Per ottenere test di alta qualità, chiedi esplicitamente queste tre categorie di verifica:

Categoria	Cosa chiedere all’IA	Obiettivo Tecnico
Happy Path	“Testa il funzionamento standard con dati validi.”	Validazione del requisito.
Edge Cases	“Testa con stringhe vuote, numeri negativi, liste giganti.”	Robustezza del codice.
Security	“Testa il comportamento con input malevoli (SQL injection, script).”	Hardening del software.

4. Esempio Pratico (Prompt per VS Code)

Seleziona una funzione e usa Inline Chat (Ctrl+I):

“Create a comprehensive PyTest suite for this function. Use a @pytest.mark.parametrize decorator to test at least 5 different edge cases including None, empty list, and maximum integer. Ensure 100% branch coverage.”

💡 Note dell’Architetto: “The Regression Shield”

Il vero valore dei test generati dall’IA si vede nel tempo. Quando tra sei mesi userai una nuova versione di Claude o GPT per rifattorizzare quel codice, i test che hai scritto oggi saranno l’unico modo per sapere se la nuova IA ha “rotto” qualcosa di fondamentale.

Non eliminare mai i test generati dall’IA: sono la tua polizza assicurativa contro l’evoluzione dei modelli.

Tags: #AI #UnitTesting #PyTest #GoogleTest #QualityAssurance #DevOps*

Devops on GeppettoBarbuto - Wiki