AnswersPublished14 sources
Test, specifiche e piani: una struttura più chiara, con le giuste eccezioni
Concentrare i test è una buona impostazione predefinita, ma alcuni test Go devono restare nel package per accedere ai suoi elementi non esportati. Le specifiche descrivono i requisiti attuali; gli ADR documentano le decisioni e le loro motivazioni; i test verificano il comportamento.
Pubblicato daImmagini generate con GPT Image 2
Research answer
Key takeaways
- Concentrare i test è una buona impostazione predefinita, ma alcuni test Go devono restare nel package per accedere ai suoi elementi non esportati.
- Le specifiche descrivono i requisiti attuali; gli ADR documentano le decisioni e le loro motivazioni; i test verificano il comportamento.
- Un piano congelato è incompleto e sospeso, non concluso: riprenderlo richiede una nuova verifica.
- I materiali temporanei si possono ripulire, ma non eliminando l’unica copia di prove ancora necessarie.
![[GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W](https://d15bya8fi85z1v.cloudfront.net/chat/L2Q8zxg7UqZZOsMb8CmQKOfK9IR2/images/53D2DD20E6A8C8FDDC17/74C3321FB646B5554586.png)
AI Prompt
openai.comCreate a landscape editorial hero image for this Studio Global article: [GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W. Article summary: <tool call {"name":"attempt completion","arguments":{"result":"这套布局可以作为收敛方向，但需要纠正三个等同关系：所有测试不能无条件迁出业务包，规范不是全部 ADR 的摘要，冻结也不是完成归档。以下是六项建议的明确边界；涉及的新路径均为候选，尚未创建或迁移。\n\n 1.. Topic tags: general web, openai, automation, workflow, code. Style: premium digital editorial illustration, source-backed research mood, clean composition, high detail, modern web publication hero. Use reference image context only for broad subject, composition, and topical grounding; do not copy the exact image. Avoid: logos, brand marks, copyrighted characters, real person likenesses, fake screenshots, UI text, readable text, watermarks, charts with fake numbers, clickbait thumbnails, icons, a
Riorganizzare cartelle e documenti può rendere un progetto più leggibile, ma non dovrebbe trasformare preferenze di layout in regole assolute. In particolare, concentrare tutti i test, trattare le specifiche come un riepilogo degli ADR e considerare un piano congelato come archiviato sono tre equivalenze da evitare.
Le indicazioni seguenti propongono una direzione, non descrivono una migrazione già eseguita: i percorsi nuovi citati sono candidati e, in questa proposta, non sono stati creati né spostati file.
1. Test in una cartella comune, salvo esigenze del linguaggio
È ragionevole adottare una cartella di test centralizzata come scelta predefinita, senza pretendere che ogni test lasci la directory del codice.
- Python: i test possono essere raccolti in
tests/. In caso di migrazione, occorre controllare import, individuazione dei test, fixture e configurazione CI. In questo progetto, la configurazioneCIutilizza già un percorso centralizzato. - Go: i test che devono accedere a elementi non esportati possono restare nello stesso package del codice. I test black-box, quelli tra componenti e quelli end-to-end possono invece essere organizzati in percorsi dedicati. Go compila i file di test insieme al package e supporta sia test nello stesso package sia test in un package esterno.
14
È importante distinguere due cose: le regole di importazione dei package sotto una directory internal dipendono dalla posizione nell’albero dei percorsi; l’accesso agli identificatori non esportati dipende invece dal confine del package.10
16 Perciò, spostare tutti i test Go fuori dalle directory dei package non è un requisito generale compatibile con ogni forma di test white-box. Non conviene esportare dettagli interni o duplicare la logica solo per ottenere un albero di cartelle più ordinato.
La regola da evitare non è «mai file di test separati», ma la proliferazione di ticket inutili e verifiche duplicate. I test di regressione continuativi vanno mantenuti sotto controllo di versione; le prove usa e getta appartengono invece a un’area temporanea.
2. Regole globali, specifiche e ADR hanno funzioni diverse
La cartella specs/ non dovrebbe diventare un compendio di tutti gli ADR. Una divisione più utile è questa:
| Livello | A quale domanda risponde | Da dove derivano i contenuti |
|---|---|---|
| Metodo globale | Come analizzare, verificare e consegnare il lavoro? | Dalle regole metodologiche condivise |
AGENTS.md del progetto |
Come si lavora in questo repository? | Dai vincoli confermati e dalle istruzioni operative del progetto |
Specifiche in specs/ |
Quali comportamenti e contratti devono valere adesso? | Dai requisiti e dalle decisioni accettate, con le modifiche autorizzate |
ADR in docs/adr/ |
Perché è stata scelta questa soluzione? | Dalle decisioni architetturali, dai compromessi e dalle alternative considerate |
Cline documenta un meccanismo di regole persistenti per conservare istruzioni tra diverse conversazioni.4 Questo, però, non dimostra che Cline scriva automaticamente una particolare categoria di file dentro la cartella delle specifiche: quella sarebbe una convenzione del progetto, non una funzionalità da attribuire al prodotto senza riscontri.
Le specifiche non devono essere tutte scritte a mano né aspettare che un problema costringa a crearle. Un processo possibile è:
- All’avvio, proporre specifiche sulla base delle richieste e delle evidenze presenti nel repository, lasciando esplicite le incognite.
- Prima di un’attività, leggere le specifiche e le decisioni pertinenti, quindi chiarire criteri di accettazione e verifiche.
- Proporre un nuovo ADR solo quando emerge una decisione significativa; se una decisione esistente è ancora valida, citarla invece di duplicarla.
- Usare l’esito dei test per valutare l’implementazione, senza lasciare che sia il risultato tecnico a decidere automaticamente cosa richiede il prodotto.
- Dopo l’approvazione di una decisione e delle relative modifiche, aggiornare la specifica interessata e collegare l’ADR pertinente, senza copiarne tutta la storia.
In breve: la specifica descrive il contratto attuale, l’ADR spiega la decisione, il test verifica una parte del comportamento. Sono elementi collegati, ma non intercambiabili. Inoltre, una scoperta valida per un singolo progetto non dovrebbe diventare una regola globale senza revisione.
3. ADR in docs/adr/, senza cambiare i criteri di accettazione
Usare docs/adr/ come posizione predefinita per le nuove decisioni è una convenzione di progetto sensata; non è necessario presentarla come l’unico standard possibile.
La riorganizzazione dei percorsi non modifica il modo in cui si accettano le decisioni:
- possono essere conservate proposte, decisioni accettate, rifiutate o superate, non soltanto quelle in vigore;
- quando una decisione esistente è applicabile, è preferibile riutilizzarla anziché creare un ADR equivalente;
- se una scelta viene sostituita, la nuova registrazione dovrebbe collegarsi alla precedente senza riscriverne a posteriori le motivazioni;
- il superamento dei test, da solo, non equivale all’autorizzazione ad accettare un ADR.
Una migrazione dovrebbe aggiornare anche riferimenti, routing e vincoli di accesso effettivamente dipendenti dai percorsi. Spostare i file, senza correggere questi collegamenti, non basta.
4. Piani in una cartella piatta: distinguere conclusione e sospensione
Una cartella plans/ piatta può essere sufficiente: non serve introdurre sottocartelle solo per ospitare pochi piani storici. Come convenzione candidata, si potrebbero distinguere tre casi:
| Uso | Nome di esempio | Significato |
|---|---|---|
| Piano attivo | plans/pending_implementation_plan.md |
Punto d’ingresso predefinito per il lavoro in corso |
| Piano completato | plans/plan-20261022-example-id.md |
Attività conclusa e archiviazione autorizzata |
| Piano sospeso | plans/plan-20261022-example-id-frozen.md |
Attività incompleta, conservata ma non più in esecuzione predefinita |
Congelare un piano non richiede per forza una nuova cartella o un nuovo stato formale. Il validatore supporta già uno stato di pausa: si può riutilizzare, annotando motivo della sospensione, attività residue e condizioni per riprendere.
Le distinzioni operative contano:
- Completato e archiviato: i criteri richiesti sono soddisfatti e l’archiviazione è autorizzata.
- Congelato: il piano esce dal punto d’ingresso attivo, ma resta incompleto. Non va indicato come concluso né usato per trasformare proposte non verificate in fatti.
- Abbandonato: è stato deciso di non procedere, con le relative conseguenze esplicitate. Non è semplicemente una pausa temporanea.
Se non si trovano altri documenti che definiscano già uno stato formale di abbandono, introdurlo richiederebbe una revisione del contratto. Per impostazione predefinita si legge solo il piano attivo, non tutti i file storici della cartella; i piani precedenti si cercano in modo mirato quando serve consultarli o riprenderli.
La regola di ciclo di vita in 02-bmad-core.md è coerente con questa cautela: per riprendere un piano congelato servono autorizzazione, una nuova istanza di esecuzione che conservi il collegamento all’originale e una nuova verifica. Il fatto che un file venga rinominato o archiviato non dimostra che il lavoro sia stato accettato. Bisogna anche evitare sovrascritture, conservare le attività non concluse e aggiornare i riferimenti. Non è necessario creare un piano vuoto solo per mantenere un nome fisso.
5. Mappare test e codice con relazioni molti-a-molti
Non è consigliabile imporre una corrispondenza uno-a-uno tra file di codice e file di test. Un test può coprire più componenti e un componente può richiedere test unitari, test basati su proprietà e verifiche d’integrazione.
Come punto di partenza:
- organizzare
tests/per modulo o responsabilità; - nelle specifiche pertinenti, indicare invarianti importanti, test correlati e comandi di verifica circoscritti;
- aggiungere un file come
tests/test-map.yamlsolo se i collegamenti sono davvero difficili da individuare senza una mappa.
Una mappa dovrebbe contenere solo le relazioni necessarie: identificativo del modulo o del contratto, porzione di sorgente, percorso dei test e comando di verifica. Non serve duplicare l’intero albero delle directory o registrare manualmente gli esiti dei test. La manutenzione dovrebbe assicurare che percorsi e comandi siano validi; la presenza della mappa, da sola, non dimostra né copertura sufficiente né test superati.
6. Ripulire i materiali temporanei senza perdere prove
Raccogliere bozze, script usa e getta e rapporti esplorativi in .scratch/ può aiutare a separare il lavoro effimero dai documenti mantenuti. Due regole, però, vanno formulate con attenzione: il contenuto di quella cartella non è automaticamente privo di valore probatorio e non tutto può essere cancellato senza verifiche.
- Un riepilogo di ricerca prodotto da un modello è un’interpretazione secondaria, non diventa una fonte primaria solo perché viene salvato nel repository.
- Un output di test originale o una diagnosi registrata direttamente può invece costituire una prova di prima mano anche se si trova in una cartella temporanea. La sua affidabilità dipende da provenienza, ambiente, data e completezza.
- Se un piano, una decisione o un criterio di accettazione dipende da una prova che esiste in un’unica copia, non va eliminata alla leggera. Prima occorre conservarla dove serve oppure ritirare esplicitamente la conclusione che ne dipende.
- Le informazioni importanti estratte dai materiali temporanei dovrebbero mantenere riferimenti alle prove, limiti di applicabilità e incognite. Sintetizzare non deve trasformare un’ipotesi in un fatto.
Anche i vecchi rapporti e diagrammi in docs/ vanno trattati in base al loro ruolo, non alla sola età:
- i documenti ancora validi dovrebbero indicare il proprio ambito e venire riesaminati quando cambia il contratto pertinente;
- diagrammi e proposte superati dovrebbero essere etichettati come storici o sostituiti e non usati come riferimento corrente;
- i materiali di processo senza valore durevole e senza dipendenze possono essere spostati nell’area temporanea o eliminati, una volta ottenuta l’autorizzazione.
Conservare una prova non significa caricarla nel contesto di ogni attività. Per limitare il rumore, è preferibile leggere i materiali in modo mirato e segnalare se sono attuali, storici o da verificare, anziché cancellare indiscriminatamente le tracce.
In sintesi
La proposta può funzionare con quattro limiti chiari: centralizzare i test lasciando spazio alle esigenze dei linguaggi; tenere le specifiche come contratto attuale, non come raccolta di tutti gli ADR; non confondere un piano congelato con uno completato; ripulire i materiali temporanei senza cancellare prove ancora necessarie.
I percorsi predefiniti e quelli consentiti in validate-roo-contracts.py, così come i permessi di modifica della modalità di analisi in custom_modes.yaml, risultano ancora legati alla struttura precedente. Un’eventuale migrazione dovrà aggiornare regole, modelli, riferimenti, validatori e adattamenti dell’ambiente. Rinominare le cartelle non basta a renderla effettiva. Questa analisi non ha modificato, trasferito, congelato o ripulito alcun materiale.
Studio Global AI
Continue your research
This page includes a source-backed answer you can continue inside Studio Global.
People also ask
What is the short answer to "Test, specifiche e piani: una struttura più chiara, con le giuste eccezioni"?
Concentrare i test è una buona impostazione predefinita, ma alcuni test Go devono restare nel package per accedere ai suoi elementi non esportati.
What are the key points to validate first?
Concentrare i test è una buona impostazione predefinita, ma alcuni test Go devono restare nel package per accedere ai suoi elementi non esportati. Le specifiche descrivono i requisiti attuali; gli ADR documentano le decisioni e le loro motivazioni; i test verificano il comportamento.
What should I do next in practice?
Un piano congelato è incompleto e sospeso, non concluso: riprenderlo richiede una nuova verifica.