Piano: Integrazione sviluppo - testing - documentazione¶
Stato: Bozza per discussione con il team Autore: Team R&D Data: 2026-04-20
Obiettivo¶
Utilizzare la documentazione tecnica come strumento operativo che lega le fasi del ciclo di sviluppo:
- Implementazione: il developer cita il task ClickUp nei sorgenti al momento della modifica
- Generazione automatica doc: l'auto-doc rileva le modifiche, le collega al task, aggiorna changelog e pagine di documentazione
- Testing: il tester trova nel changelog cosa e' cambiato, a quale task/progetto si riferisce, e nella documentazione dei programmi le modifiche effettuate
- Feedback: il tester puo' segnalare integrazioni/migliorie alla documentazione, che l'auto-doc applica
L'idea e' che il changelog diventi anche il piano di test del giorno, e la documentazione dei programmi sia sempre allineata a cio' che i tester vedono sul campo.
Situazione attuale¶
Cosa c'e' gia' nel sistema a supporto di questo flusso:
| Componente | Stato | Note |
|---|---|---|
Marker *>DOC: nei sorgenti COBOL |
Presente | Convenzione gia' in uso per segnalare modifiche alla logica di business |
| Auto-doc filesystem-snapshot | Presente | Rileva sorgenti modificati e triggera generazione doc |
| Integrazione ClickUp API | Presente | Script sync-bugs-clickup.py per i bug; riusabile per i task |
| Changelog giornaliero per programma | Presente | Pagine in docs/dev/changelog/YYYY/MM/YYYY-MM-DD.md e analogo utente |
| Validazione link changelog | Presente | Script validate-changelog-links.py integrato in auto-doc.sh |
Flusso proposto¶
Ciclo di vita di una modifica¶
ClickUp Sorgente COBOL Auto-doc Documentazione
──────── ────────────── ──────── ──────────────
TASK-1000 TASK-1010 assegnato
(progetto) │
├─ TASK-1010 │
├─ TASK-1015 Developer:
└─ ... modifica sorgente
+ *>TASK: TASK-1010
+ *>DOC: descrizione
│
│ Rileva sorgente
│ modificato
│ │
│ Scarica metadata
│ TASK-1010 da CU
│ │
│ Aggiorna:
│ │
│ ├──► Pagina programma
│ │ (sezione "Storia")
│ │
│ └──► Changelog giornaliero
│ (raggruppato per task/progetto)
│
Tester legge il changelog del giorno
│
├─► Verifica sul programma
│
└─► Legge la documentazione aggiornata
│
│ Suggerisce integrazioni
▼
Commento su TASK-1010:
"DOC: aggiungere nota su..."
│
│ Auto-doc scarica
│ i commenti DOC:
│ │
│ └──► Integra nella doc
Convenzione marker nei sorgenti¶
Proposta di estensione del marker attuale. Nei sorgenti COBOL, nel punto della modifica:
*>TASK: TASK-1010
*>DOC: Aggiunto campo stato estero obbligatorio per clienti con
*>DOC: partita IVA extra-UE. Il campo viene validato contro la
*>DOC: tabella stati ISO.
move cli-piva-estera to cli-ta-piva-estera
...
L'auto-doc estrae:
- TASK-1010 dal marker *>TASK: (identifica il task ClickUp)
- Descrizione dai marker *>DOC: successivi (fino al prossimo paragrafo o marker diverso)
Convenzioni:
- Un blocco di modifica puo' avere piu' *>DOC: consecutivi (righe descrittive)
- Puo' esserci un solo *>TASK: per blocco
- Se *>TASK: e' omesso, la modifica viene registrata senza riferimento task (comportamento attuale)
Modifiche necessarie¶
1. Convenzione marker e documentazione¶
- Aggiornare
CLAUDE.mdcon la convenzione*>TASK: - Aggiornare
AUTO-DOC.mdcon la logica di estrazione e uso del task ID - Comunicare la convenzione ai developer
Effort: 1 giornata
2. Script sync-tasks-clickup.py¶
Nuovo script, strutturato come sync-bugs-clickup.py, che:
- Legge tutti i marker
*>TASK:presenti nei sorgenti.cblmodificati (o su tutta la codebase al primo giro) - Estrae la lista di task ID univoci
- Interroga l'API ClickUp per ciascuno → scarica metadata: titolo, descrizione, progetto padre, stato, URL
- Salva i dati in
docs/import/tasks/task_{id}.md - Mantiene uno stato di sync in
docs/import/tasks/.sync-state.json
Questo fornisce all'auto-doc le informazioni sui task da includere nel changelog e nelle pagine programma.
Effort: 1 giornata
3. Changelog raggruppato per progetto/task¶
Modifiche alla Fase 5 di AUTO-DOC.md. Il changelog giornaliero cambia formato:
# Modifiche del 2026-04-20
## Progetto TASK-1000 — Gestione anagrafiche estere
### TASK-1010: Stato estero in anagrafica clienti
[Task ClickUp](https://app.clickup.com/t/TASK-1010)
Programmi modificati:
- [COGE08C - Anagrafica Clienti](../../../menu/contabilita/archivi-tabelle/coge08c.md)
- Aggiunto campo stato estero obbligatorio per PIVA extra-UE
- Validazione contro tabella stati ISO
### TASK-1015: Stampa stato estero nel DDT
[Task ClickUp](https://app.clickup.com/t/TASK-1015)
Programmi modificati:
- [COGV52 - Stampa DDT](../../../menu/...)
## Modifiche senza riferimento task
- [COGX04 - ...](...)
Effort: 1 giornata (modifica prompt auto-doc + test)
4. Sezione "Storia modifiche" nelle pagine programma¶
Ogni pagina programma (sia tecnica che utente) avra' in fondo una sezione:
## Storia modifiche
| Data | Task | Descrizione |
|------|------|-------------|
| 2026-04-20 | [TASK-1010](https://app.clickup.com/t/TASK-1010) | Aggiunto campo stato estero obbligatorio per PIVA extra-UE |
| 2026-03-15 | [TASK-0987](https://app.clickup.com/t/TASK-0987) | Rivista validazione P.IVA |
L'auto-doc aggiunge una riga ogni volta che il programma viene modificato con un task di riferimento. Le modifiche senza task non vengono registrate qui (restano solo nel changelog).
Effort: 2 giornate (richiede logica piu' complessa per gestire merge con righe esistenti)
5. Feedback loop dai tester¶
Opzione preferita: commenti ClickUp con prefisso.
Il tester, dopo aver testato una modifica, lascia un commento sul task con un prefisso convenzionale:
DOC: La nota sullo stato estero non menziona il comportamento quando
il cliente passa da extra-UE a UE. Aggiungere.
Lo script sync-tasks-clickup.py scarica anche i commenti. Il prefisso DOC: identifica i suggerimenti di integrazione doc. L'auto-doc, al successivo ciclo, presenta i commenti DOC non ancora processati a Claude come richiesta di integrazione alla pagina del programma collegato al task.
Stato commento: serve un meccanismo per sapere quali commenti sono stati "processati":
- Opzione A: aggiungere una reazione emoji (es. ✓) al commento dopo averlo processato (richiede permessi API)
- Opzione B: tenere lo stato localmente (hash del commento + task_id in un file di stato)
- Opzione C: il commento viene "risolto" su ClickUp dal tester dopo verifica
Opzione B e' la piu' semplice e indipendente.
Effort: 2 giornate (incluso test e documentazione del flusso per i tester)
Piano di implementazione a step¶
Consiglio di procedere incrementalmente, ciascuno step funzionante da solo e testabile:
| Step | Descrizione | Effort | Priorita' |
|---|---|---|---|
| 1 | Convenzione marker *>TASK: + docs |
1g | Alta |
| 2 | Script sync-tasks-clickup.py |
1g | Alta |
| 3 | Changelog raggruppato per progetto/task | 1g | Alta |
| 4 | Sezione "Storia modifiche" nelle pagine programma | 2g | Media |
| 5 | Feedback loop via commenti ClickUp | 2g | Bassa (nice-to-have) |
Totale stimato: 7 giornate uomo
Gli step 1-3 costituiscono il nucleo minimo (~3 giornate) che abilita il flusso sviluppo → test senza il loop di feedback. I passi 4-5 sono miglioramenti incrementali.
Punti aperti da discutere con il team¶
-
Formato task ID: sono effettivamente
TASK-NNNNo hanno un altro formato (es. CU-XXXX, hash ClickUp)? Il regex di estrazione dipende dal formato reale. -
Granularita' task: tutti i task (inclusi fix minori, bug) meritano un riferimento? O solo i task di sviluppo appartenenti a un progetto? I bug hanno gia' un flusso dedicato (
sync-bugs-clickup.py) — distinguere o unificare? -
Ruolo dei progetti padre: un task puo' appartenere a piu' progetti? Come gestire la gerarchia in ClickUp? Il raggruppamento nel changelog dipende da questa struttura.
-
Modifiche senza task: fix urgenti, refactoring tecnico, correzioni di typo — devono sempre avere un task? O e' ammesso un marker
*>DOC:senza*>TASK:? -
Feedback dai tester: la preferenza e' commenti ClickUp o un meccanismo alternativo (es. commento direttamente sulla pagina di doc tramite annotazione MkDocs)?
-
Privacy dei commenti: i commenti ClickUp potrebbero contenere riferimenti a clienti specifici o informazioni riservate. Politica di sanitizzazione prima di integrare nella documentazione pubblica?
-
Chi attiva il sync task: automaticamente ad ogni run di auto-doc? Su cron separato? Manuale?
Alternative considerate¶
Non usare ClickUp, usare solo marker interni¶
Si potrebbe rinunciare all'integrazione API e usare solo i marker nei sorgenti (es. *>TASK: 1010 — Aggiunto stato estero).
Pro: nessuna dipendenza esterna, piu' semplice. Contro: perdiamo il link bidirezionale con ClickUp (stato task, commenti tester, assegnazioni). I tester non hanno un punto unico di riferimento.
Valutazione: preferibile l'integrazione ClickUp, il flusso e' piu' completo.
Integrazione Git invece che filesystem-snapshot¶
Si potrebbe usare git log per rilevare le modifiche ai sorgenti invece del filesystem-snapshot attuale.
Pro: naturale integrazione con commit message (il developer cita il task nel commit). Contro: richiede commit per triggerare auto-doc (non immediato), e il progetto usa git come storico, non come strumento di rilascio (cit. AUTO-DOC.md). Cambierebbe il paradigma attuale.
Valutazione: non cambiare il paradigma, restare su filesystem-snapshot + marker nei sorgenti.
Benefici attesi¶
- Developer → Tester: tracciabilita' immediata di cosa cambia e dove verificarlo, senza chiedere al developer
- Tester → Developer: canale strutturato per segnalazioni di doc mancante, senza interruzioni
- Documentazione: sempre allineata, auto-aggiornata, con storia delle modifiche
- Project Manager: il changelog diventa anche reportistica di avanzamento progetti
- Cliente (in futuro): la doc utente arricchita con storia modifiche permette al cliente di capire cosa e' cambiato nei rilasci
Prossimi passi (dopo allineamento team)¶
- Confermare convenzione task ID e struttura progetti ClickUp
- Decidere se partire da tutti gli step o solo dal nucleo (1-3)
- Individuare un pilota: un progetto reale da usare come test (es. "Gestione anagrafiche estere" se esistente)
- Comunicare la convenzione
*>TASK:ai developer e iniziare a usarla sui nuovi task - Sviluppo iterativo degli step