Prompt per test e documentazione

Test e documentazione generati male danno una falsa sensazione di qualità. Un test che non fallirebbe mai e una docstring che ripete il nome della funzione non aiutano il progetto. Il prompt deve chiedere comportamento, casi limite e lettore atteso.

Perché questa lezione conta

Gli LLM producono facilmente test e docs. Proprio per questo bisogna essere severi: quantità non significa copertura, e frasi fluenti non significano documentazione utile.

Prompt per test

Un buon prompt per test specifica:

• comportamento da proteggere;
• casi limite;
• input ostili;
• regressione che vuoi evitare;
• framework usato;
• cosa non testare.

Esempio:

Aggiungi test per `normalizeEmail`.

Copri:
- input valido;
- spazi iniziali/finali;
- dominio maiuscolo;
- stringa vuota;
- input senza @.

Non testare dettagli di implementazione.
Ogni test deve fallire se la regola corrispondente viene rimossa.

La frase finale è importante: obbliga a pensare al valore del test.

Prompt per documentazione

La documentazione deve avere un lettore.

Aggiorna il README per uno sviluppatore che arriva nel progetto.
Spiega:
1. cosa fa il modulo;
2. come eseguire i test;
3. quali vincoli non violare;
4. un esempio minimo d'uso.

Non ripetere dettagli già evidenti dal nome delle funzioni.

Documentare per “tutti” produce testo generico. Documentare per un lettore concreto produce scelte.

Test prima, documentazione poi

Per modifiche di comportamento, chiedi prima test o scenari di verifica. La documentazione deve descrivere comportamento stabilizzato, non ipotesi.

Workflow consigliato:

1. chiedi casi da testare;
2. genera test;
3. applica patch;
4. verifica;
5. aggiorna documentazione solo dove cambia il comportamento pubblico.

Laboratorio guidato

Scegli una funzione o feature. Chiedi:

1. “aggiungi test e documentazione” in modo vago;
2. prompt strutturato con casi, lettore e vincoli.

Poi cancella tutto ciò che:

• non fallirebbe mai;
• testa implementazione invece di comportamento;
• ripete il codice;
• spiega ovvietà;
• non serve al lettore target.

Output atteso

Una lista di prompt per produrre test e docs di valore concreto.

Template test:

Comportamento da proteggere:
Casi normali:
Casi limite:
Input ostili:
Framework:
Vincoli:
Criterio: ogni test deve fallire se il comportamento si rompe.

Template docs:

Lettore:
Obiettivo della documentazione:
Cosa è cambiato:
Esempio minimo:
Cose da non ripetere:

Checklist di verifica

• ogni test protegge un comportamento;
• almeno un test copre un caso limite;
• la documentazione ha un lettore esplicito;
• non genero docs per codice autoevidente;
• test e docs sono coerenti con la patch reale.

Errori comuni

Test che assertano poco. Se il test passerebbe anche con codice rotto, è rumore.

Documentazione decorativa. “Questa funzione normalizza email” non aggiunge valore se il nome lo dice già.

Chiedere tutto insieme. Per patch rischiose, separa test, modifica e documentazione.

Collegamenti

• Modulo: Prompt per il ciclo di codice — lezione 20 del corso.
• Lezione precedente: Prompt per debug: sintomo, non causa.
• Prossimo modulo: Contesto e memoria nel progetto.