Aggiornamento 2026. Questo è il paper originale del 2025, lasciato com’era. Il progetto oggi si chiama ContextDoc (file
.ctxin YAML, molte meno sezioni, strumenti reali): è descritto nel paper ContextDoc. In fondo, la sezione Aggiornamento 2026 riassume cosa è cambiato.
Abstract
Questo documento presenta ConceptDoc, un approccio innovativo alla documentazione software progettato per migliorare la collaborazione tra sviluppatori umani e assistenti IA. Le pratiche di documentazione tradizionali, sviluppate decenni fa per il consumo umano, potrebbero non essere sufficienti per una efficace collaborazione uomo-IA. ConceptDoc colma questo divario fornendo una documentazione strutturata e leggibile dalle macchine che cattura informazioni contestuali ricche sui componenti software. Utilizzando file di documentazione parallela in formato JSON, ConceptDoc consente sia agli umani che ai sistemi IA di comprendere non solo cosa fa il codice, ma anche perché esiste e come dovrebbe comportarsi. Questo documento descrive lo schema ConceptDoc, dimostra le sue applicazioni pratiche attraverso esempi e discute il suo potenziale impatto sui flussi di lavoro dello sviluppo software.
1. Introduzione
Man mano che gli strumenti di IA diventano sempre più integrati nei processi di sviluppo software, cresce la necessità di adattare le nostre pratiche di sviluppo per supportare questo nuovo paradigma di collaborazione. Gli approcci di documentazione attuali come commenti inline, docstring e file README sono stati progettati decenni fa principalmente per il consumo umano. Sebbene questi formati possano trasmettere informazioni di base sulla funzionalità del codice, spesso non riescono a catturare il ricco contesto, i vincoli e le decisioni di progettazione che rendono il codice veramente comprensibile.
ConceptDoc affronta questa sfida proponendo un formato per la documentazione strutturata e leggibile dalle macchine che migliora la collaborazione tra sviluppatori umani e assistenti IA. Catturando informazioni come modelli di stato, invarianti, test concettuali e regole di business in un formato strutturato, ConceptDoc consente ai sistemi IA di comprendere e ragionare meglio sul codice, portando a una generazione, analisi e test del codice più accurati.
2. L’Approccio ConceptDoc
ConceptDoc introduce il concetto di file di documentazione parallela che esistono accanto ai file di codice tradizionali. Per ogni file di codice (es. user_service.py), esiste un corrispondente file ConceptDoc (es. user_service.py.cdoc) che contiene metadati strutturati sul codice. Questi file utilizzano il formato JSON per garantire che possano essere facilmente analizzati ed elaborati sia dalle macchine che dagli umani.
2.1 Componenti Principali di un File ConceptDoc
Un file ConceptDoc in genere include le seguenti sezioni:
Metadata: Informazioni di base sul file documentato, inclusi nome file, versione e data dell’ultimo aggiornamento.
Purpose: Una descrizione concisa dello scopo del file e del suo ruolo all’interno del sistema più ampio.
Dependencies: Elenco di altri componenti da cui questo file dipende, insieme a spiegazioni del perché e come tali dipendenze vengono utilizzate.
Invariants: Condizioni che devono essere sempre mantenute dal codice, indipendentemente dal suo stato o percorso di esecuzione.
Components: Documentazione dettagliata di classi, metodi e funzioni, inclusi:
- Firma e descrizione
- Precondizioni e postcondizioni
- Esempi di input e output
- Potenziali errori e come gestirli
State Model: Definizione di stati possibili e transizioni per componenti con stato.
Test Fixtures: Dati di esempio per i test, garantendo coerenza tra gli scenari di test.
Conceptual Tests: Descrizioni dichiarative dei comportamenti attesi, espresse come sequenze di azioni e risultati previsti.
Business Logic: Regole e vincoli aziendali espliciti che il codice deve applicare.
AI Notes: Guida specifica per assistenti IA su come interpretare e lavorare con il codice.
2.2 Esempio di File ConceptDoc
Di seguito è riportato un esempio semplificato di un file ConceptDoc per un modulo todo_item.py:
{
"metadata": {
"filename": "todo_item.py",
"version": "1.0.0",
"lastUpdate": "2025-03-22"
},
"purpose": "Rappresenta un elemento todo con gestione del ciclo di vita e capacità di serializzazione",
"invariants": [
"Un elemento todo ha sempre un ID univoco",
"Un elemento todo ha sempre un titolo non vuoto",
"Se is_completed è true, completed_at deve contenere un timestamp",
"Se is_completed è false, completed_at deve essere None"
],
"stateModel": {
"states": ["active", "completed"],
"initialState": "active",
"transitions": [
{
"from": "active",
"to": "completed",
"trigger": "complete()",
"conditions": []
},
{
"from": "completed",
"to": "active",
"trigger": "reactivate()",
"conditions": []
}
]
},
"components": [
{
"name": "TodoItem.complete",
"signature": "complete()",
"description": "Segna l'elemento todo come completato",
"preconditions": [],
"postconditions": [
"is_completed è impostato su True",
"completed_at è impostato sulla data e ora correnti"
]
}
],
"conceptualTests": [
{
"name": "Ciclo di vita del Todo",
"steps": [
{
"action": "Crea un nuovo TodoItem",
"expect": "L'elemento è nello stato 'active' con is_completed=False"
},
{
"action": "Chiama complete()",
"expect": "L'elemento passa allo stato 'completed' con is_completed=True e completed_at impostato"
}
]
}
]
}
3. Elementi Distintivi di ConceptDoc
ConceptDoc riunisce in un unico file leggibile dalle macchine idee già note in altri contesti, e questo lo differenzia dagli approcci di documentazione tradizionali:
3.1 Test Concettuali
Uno degli elementi più significativi di ConceptDoc sono i “test concettuali”, che riprendono l’idea degli scenari BDD (Given/When/Then) in un formato JSON pensato per gli assistenti IA. A differenza dei tradizionali test unitari o di integrazione scritti in codice, i test concettuali sono descrizioni dichiarative di comportamenti attesi espressi come sequenze di azioni e risultati attesi. Questi test servono come:
- Documentazione di come il sistema dovrebbe comportarsi
- Criteri di verifica che i sistemi IA possono utilizzare per validare il codice
- Template per generare casi di test concreti
Descrivendo i test a livello concettuale, separati dai dettagli di implementazione specifici, ConceptDoc rende più facile sia per gli umani che per i sistemi IA comprendere il comportamento atteso del codice e verificare se soddisfa tali aspettative.
3.2 Modelli di Stato
I modelli di stato espliciti di ConceptDoc, analoghi alle macchine a stati (statechart, UML), forniscono una definizione chiara ed esplicita degli stati possibili e delle transizioni per i componenti con stato. Questa informazione è particolarmente preziosa per i sistemi IA, che possono utilizzarla per:
- Generare codice di gestione dello stato che gestisce correttamente tutte le transizioni valide
- Identificare potenziali casi limite o transizioni di stato non valide
- Produrre visualizzazioni del modello di stato per gli sviluppatori umani
3.3 Invarianti
Le invarianti in ConceptDoc, come precondizioni e postcondizioni, riprendono il Design by Contract e catturano condizioni che devono essere sempre mantenute dal codice. Documentando esplicitamente questi vincoli, ConceptDoc aiuta sia gli umani che i sistemi IA a comprendere le regole fondamentali che governano il comportamento del sistema. Questa informazione è cruciale per:
- Garantire la correttezza del codice durante lo sviluppo
- Generare test accurati che verifichino il mantenimento delle invarianti
- Rilevare potenziali bug o incoerenze nel codice esistente
4. Applicazioni e Benefici
4.1 Generazione di Codice Migliorata
ConceptDoc dovrebbe consentire una generazione di codice più accurata e completa da parte degli assistenti IA (ipotesi non ancora misurata). Con accesso a informazioni contestuali ricche come invarianti, modelli di stato e regole di business, i sistemi IA possono generare codice che:
- Mantiene adeguatamente tutte le invarianti richieste
- Gestisce correttamente le transizioni di stato
- Implementa correttamente le regole di business
- Include una gestione appropriata degli errori
- Segue pattern e convenzioni coerenti
L’ipotesi è che questo migliori la generazione di codice basata esclusivamente su descrizioni in linguaggio naturale, che spesso mancano della precisione e del dettaglio necessari per sistemi software complessi.
4.2 Sviluppo Basato su Specifiche
ConceptDoc permette un nuovo flusso di lavoro di sviluppo “specification-first”, dove gli sviluppatori:
- Iniziano creando un file ConceptDoc con specifiche dettagliate
- Utilizzano assistenti IA per generare il codice iniziale basato su queste specifiche
- Rifiniscono e migliorano il codice generato secondo necessità
Questo approccio ha diversi vantaggi:
- Incoraggia gli sviluppatori a pensare profondamente al design prima dell’implementazione
- Crea un contratto chiaro tra collaboratori umani e IA
- Fornisce un punto di riferimento per valutare la correttezza dell’implementazione
4.3 Miglioramento dell’Onboarding e Trasferimento di Conoscenze
ConceptDoc fornisce un modo strutturato per catturare e trasferire conoscenze su una codebase. I nuovi membri del team possono rapidamente comprendere:
- Lo scopo e il ruolo di ciascun componente
- Come i componenti interagiscono tra loro
- Le regole di business e i vincoli che governano il sistema
- Il comportamento atteso del sistema in diverse condizioni
Questo approccio strutturato alla cattura e al trasferimento di conoscenze potrebbe ridurre il tempo e lo sforzo necessari per l’onboarding di nuovi membri del team.
4.4 Testing Migliorato
I test concettuali e le fixture di test di ConceptDoc forniscono una solida base per test completi:
- I test concettuali potrebbero essere tradotti automaticamente in casi di test concreti
- Le fixture di test standard garantiscono coerenza tra diversi scenari di test
- Le invarianti esplicite e i modelli di stato aiutano a identificare casi di test importanti
Questo approccio aiuta a garantire che i test siano approfonditi, coerenti e focalizzati sulla verifica degli aspetti più importanti del comportamento del sistema.
5. Implementazione e Strumenti
Sebbene ConceptDoc possa fornire valore anche come file JSON autonomi, il suo pieno potenziale si realizza attraverso un appropriato supporto di strumenti. I seguenti tipi di strumenti possono migliorare l’esperienza ConceptDoc:
Plugin per IDE: Integrazione con IDE popolari per:
- Fornire navigazione tra codice e file ConceptDoc
- Offrire validazione e completamento automatico per file ConceptDoc
- Abilitare la visualizzazione di modelli di stato e altri metadati
Integrazione CI/CD: Strumenti che:
- Verificano la coerenza tra codice e file ConceptDoc
- Generano casi di test da test concettuali
- Controllano l’aderenza alle invarianti documentate
Assistenti di Sviluppo IA: Integrazione con assistenti di codifica IA per:
- Generare codice basato su specifiche ConceptDoc
- Suggerire aggiornamenti ai file ConceptDoc basati su modifiche al codice
- Validare il codice rispetto ai requisiti ConceptDoc
Al momento della pubblicazione questi strumenti sono solo proposte; nessuno è ancora disponibile. Nel 2026 alcuni sono diventati realtà: vedi la sezione Aggiornamento 2026.
6. Caso di Studio: Applicazione Lista Todo
Per dimostrare l’applicazione pratica di ConceptDoc, consideriamo una semplice applicazione di lista todo con tre componenti principali:
todo_item.py: Il modello di dominio che rappresenta un singolo elemento todostorage_service.py: Il livello di persistenza per memorizzare e recuperare i todotodo_service.py: Il livello di logica di business per gestire i todo
Utilizzando ConceptDoc, ciascuno di questi componenti è documentato con un file ConceptDoc parallelo (esempio nel repo) che cattura, dove applicabile:
- Lo scopo e il ruolo del componente
- Le invarianti che deve mantenere
- Gli stati e le transizioni che gestisce
- Le precondizioni e postcondizioni per ogni metodo
- Test concettuali che descrivono i comportamenti attesi
- Fixture di test standard per test coerenti
Questa documentazione strutturata fornisce una comprensione completa di come funziona l’applicazione, quali vincoli deve mantenere e come testarla efficacemente. Sia gli sviluppatori umani che gli assistenti IA possono utilizzare queste informazioni per lavorare con la codebase in modo più efficace.
7. Direzioni Future
Le possibili direzioni di sviluppo del progetto ConceptDoc sono:
Perfezionamento dello Schema: Continuare a perfezionare e migliorare lo schema ConceptDoc basato sull’uso nel mondo reale e sul feedback.
Sviluppo di Strumenti: Creare plugin, estensioni e strumenti autonomi per migliorare l’esperienza ConceptDoc.
Integrazione con Sistemi IA: Collaborare con sviluppatori di strumenti IA per ottimizzare l’integrazione con ConceptDoc.
Costruzione della Comunità: Promuovere una comunità di sviluppatori e ricercatori interessati a migliorare la collaborazione uomo-IA nello sviluppo software.
8. Conclusione
ConceptDoc potrebbe rappresentare un passo avanti nell’adattare le pratiche di documentazione software per l’era della collaborazione uomo-IA. Fornendo documentazione strutturata e leggibile dalle macchine che cattura informazioni contestuali ricche sui componenti software, ConceptDoc consente sia agli umani che ai sistemi IA di comprendere meglio e lavorare con il codice.
Man mano che gli strumenti IA diventano una parte sempre più integrante dei flussi di lavoro di sviluppo software, approcci come ConceptDoc potrebbero essere essenziali per colmare il divario tra la comprensione umana e quella delle macchine del codice. Il progetto ConceptDoc invita contributi da sviluppatori, ricercatori e creatori di strumenti IA interessati a plasmare il futuro dello sviluppo software collaborativo.
Aggiornamento 2026
Un anno di uso reale ha cambiato il progetto più di quanto questo paper prevedesse. Il formato e gli strumenti attuali sono descritti nel paper ContextDoc; qui il riassunto di cosa è cambiato rispetto alle pagine precedenti.
Il nome e il formato. ConceptDoc è diventato ContextDoc: file .ctx in YAML al posto dei .cdoc in JSON. Il cambio di nome riflette quello di approccio, da documentare i concetti in modo completo a fornire il contesto minimo che il codice non riesce a esprimere.
Le sezioni (2.1). Metadata, dependencies, components, test fixtures e AI notes sono state eliminate: ripetevano ciò che si legge nel codice e invecchiavano in fretta. Invarianti e regole di business sono confluite nelle tensions, le decisioni che sembrano sbagliate ma sono volute; il modello di stato, quando serve, diventa un workflow. I test concettuali sono rimasti e sono diventati il cuore del formato, con una regola nuova: sono la specifica, e un agente IA non deve mai modificarli per far passare il proprio codice.
Gli strumenti (sezione 5). Le proposte sono diventate strumenti:
| Proposta del 2025 | Oggi |
|---|---|
| Plugin per IDE: validazione e completamento | JSON Schema per lo YAML Language Server ed estensione ContextDoc per VS Code |
| CI/CD: coerenza tra codice e documentazione | ctx-watch (segnala i .ctx rimasti indietro) e un hook pre-commit che avvisa |
| Generazione di test dai test concettuali | prompt generate-tests e ctx-run, che valuta gli scenari con un LLM |
| Assistenti IA: generare codice dalle specifiche | sviluppo intent-first: il .ctx scritto prima del codice, con il prompt intent-first |
Le direzioni future (sezione 7). Perfezionamento dello schema e sviluppo di strumenti sono in gran parte avvenuti; è nata anche la convenzione project.ctx per i vincoli che riguardano l’intero progetto. Il caso di studio della sezione 6 vive ancora nel repository come examples/project-0, riscritto nel nuovo formato.
Letture correlate
Standard e lavori su temi affini, per approfondire:
- JSON Schema
- OpenAPI Specification
- Bertrand Meyer, “Applying ‘Design by Contract’”, IEEE Computer, 1992
- David Harel, “Statecharts: A Visual Formalism for Complex Systems”, Science of Computer Programming, 1987
- Dan North, “Introducing BDD”, 2006
- Michael Nygard, “Documenting Architecture Decisions”, 2011
Appendice: Schema ConceptDoc
La specifica completa dello schema (v0.1.0, pre-release) è nel README dello schema.
Risorse utili
- Repository al momento del paper (ConceptDoc, JSON)
- Schema ConceptDoc originale
- Paper EN
- Dal 2026 il progetto si chiama ContextDoc (file
.ctxin YAML): paper ContextDoc e post.
ConceptDoc: Documentazione Avanzata per la Collaborazione Uomo-IA nello Sviluppo Software