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.