Scrivere intenti che contano

I documenti di intento descrivono il comportamento e i vincoli che vuoi far rispettare al software. Scrivi ciò che hai deciso, poi precisalo man mano che impari dall’implementazione e dalle prove. Così il documento resta leggibile e lascia all’Agent spazio per implementarlo.

Scegli i requisiti da conservare

L’intento può descrivere diversi tipi di requisiti:

Descrivi la condizione di attivazione e un risultato osservabile. “L’esportazione deve essere affidabile” è difficile da verificare. “Se l’esportazione fallisce, conserva i filtri attuali e consenti di riprovare” offre una base di valutazione più chiara.

Quando una scelta di implementazione è abbastanza importante da dover essere rispettata nelle modifiche future, scrivila nell’intento. I dettagli che non hai deciso possono restare scelte di implementazione.

Distingui i requisiti duraturi dall’attività di oggi

L’intento descrive ciò che il software deve continuare a fare. Non è una lista da eliminare quando il lavoro finisce. Conserva i requisiti dopo il completamento di una funzionalità e modifica le parole pertinenti quando decidi di cambiarne il comportamento.

Le chat contengono anche istruzioni per il lavoro attuale. Usa questa distinzione:

Chiediti cosa vincola davvero la frase. “Convalida i dati prima di ogni esportazione” definisce l’ordine di esecuzione del software e appartiene all’intento. “Questa volta indaga prima il modulo di esportazione” organizza l’attività attuale.

Indica all’Agent quali istruzioni sono requisiti duraturi e quali valgono solo per questa attività. Ripeti le istruzioni importanti per la singola attività quando serve; non presumere che una nuova chat le erediti.

Crea e modifica un documento

Fai clic su Nuovo intento (New Intent) nella barra laterale e inserisci un nome. Noea crea un file .noea.md alla radice della cartella degli intenti, con un titolo di primo livello.

I documenti usano Markdown, con lettura e modifica nella stessa vista. Fai clic sul testo per modificarlo e organizzalo con titoli, elenchi, tabelle e blocchi di codice.

Per esempio:

# Check-in giornalieri

Gli utenti possono effettuare un check-in al giorno.

## Ricompense

Assegna una ricompensa all’utente dopo 7 giorni consecutivi di check-in. Assegna la ricompensa una sola volta nella stessa serie.

Usa i titoli per le sezioni e i paragrafi per requisiti distinti. L’indagine tratta un intero elenco come un unico contenuto. Se vuoi indagare e discutere argomenti separatamente, dividili in paragrafi o sezioni.

Sviluppa l’intento attraverso la discussione

Se una regola non è ancora chiara, discutine prima di chiedere all’Agent di proporre una modifica:

Voglio evitare ricompense duplicate per i check-in. Aiutami a definire cosa significa “duplicato” qui e attendi la mia conferma prima di proporre una modifica all’intento.

Quando raggiungi una decisione, chiedi all’Agent di trasformarla in una proposta. Esamina la formulazione, modifica il testo nuovo se serve e accetta. Una frase nella chat entra nel documento di intento solo quando vi viene scritta.

Il testo risultante dovrebbe usare concetti e parole che comprendi. Chiedi chiarimenti sui termini sconosciuti o sui requisiti aggiunti prima di decidere di conservarli. Una buona formulazione ti permette di spiegare il requisito e trovare la frase da modificare quando vuoi un comportamento diverso.

Per proposte e schede di suggerimento, consulta Discutere ed esaminare le modifiche all’intento.

Usa diagrammi per le relazioni

Un blocco di codice con linguaggio mermaid può essere visualizzato come diagramma. Usalo per illustrare transizioni di stato, flussi di lavoro o relazioni tra moduli.

Il controllo in alto a destra alterna diagramma e sorgente. Passa al sorgente per modificarlo. Se la sintassi non è valida o il tipo di diagramma non è supportato, Noea mostra il sorgente e il motivo; il resto del documento rimane leggibile.

Salva e usa editor esterni

Salva manualmente con ⌘S su macOS, Ctrl+S su Windows / Linux oppure File → Salva (File → Save). Un punto accanto al titolo indica modifiche non salvate. Cambiare scheda le conserva; chiudere il documento o il progetto oppure uscire dall’app richiede di salvarle.

Il salvataggio normalizza la formattazione Markdown. Puoi gestire i file anche con un editor esterno. Se un file cambia su disco mentre lo modifichi in Noea, l’app offre opzioni di ricaricamento o salvataggio con nome invece di sovrascriverlo direttamente.

Comprendi cosa cambia con le parole

Aggiungere, sostituire ed eliminare testo influisce sui requisiti in modi diversi:

Rimuovere “La ricompensa deve essere un badge” non rende necessariamente invalida un’implementazione esistente con badge. Potrebbe ancora soddisfare l’intento rimanente. Per eliminare del tutto le ricompense, specifica che non devono più essere assegnate, invece di eliminare soltanto un requisito sulla loro forma.

Prima di modificare, chiedi all’Agent quali comportamenti cambierebbero e quali requisiti dovrebbero restare. Usa la risposta come base per la discussione, poi verifica l’implementazione effettiva e le prove.

Dopo il salvataggio, le spiegazioni precedenti mostrano Testo precedente (Previous text). Se il nuovo requisito richiede modifiche al codice, implementalo prima di indagare. Se vuoi solo verificare il comportamento esistente, indaga direttamente.

Continua con Lavorare con un Agent sull’implementazione o Mantenere aggiornate le spiegazioni.