Devin ora indicizza automaticamente i tuoi repository e genera wiki con diagrammi dell’architettura, link al codice sorgente e riepiloghi della tua codebase.
Usalo per orientarti rapidamente nelle parti della codebase che conosci meno: dagli un’occhiata nella tua barra laterale.
Ask Devin utilizzerà le informazioni presenti nel Wiki per comprendere meglio la tua codebase e trovare il contesto rilevante al suo interno.
DeepWiki verrà generato automaticamente quando colleghi i repository durante l’onboarding.
Per i repository pubblici
Il file .devin/wiki.json ti consente di controllare il comportamento predefinito di generazione della wiki di Devin, il che è particolarmente importante per i repository di grandi dimensioni che potrebbero raggiungere i limiti predefiniti.
Se durante la generazione della wiki viene trovato un file .devin/wiki.json nella directory radice del tuo repository, utilizzeremo i repo_notes e pages forniti per orientare la generazione della wiki. Se pages è presente, salteremo la pianificazione predefinita basata sui cluster e creeremo esattamente le pagine che specifichi. Questo garantisce che le parti importanti della tua base di codice vengano documentate anche quando il sistema automatico altrimenti le ignorerebbe.
Crea un file .devin/wiki.json nella directory principale del repository con la seguente struttura:
{
"repo_notes": [
{
"content": "Questo repository contiene i componenti UI principali nella cartella cui/, che devono avere priorità nella documentazione",
"author": "Team Lead"
}
],
"pages": [
{
"title": "Panoramica componenti CUI",
"purpose": "Documentare la struttura della cartella cui/ e i componenti UI principali",
"parent": null
},
{
"title": "Sistema di autenticazione",
"purpose": "Documentare il flusso di autenticazione e i componenti correlati",
"parent": null
},
{
"title": "Componenti di login",
"purpose": "Documentazione dettagliata dei componenti UI relativi al login",
"parent": "Authentication System"
}
]
}
Opzioni di configurazione
repo_notes (Array)
Fornisce contesto e indicazioni per aiutare il sistema di documentazione a comprendere meglio il repository.
- content (string, required): il contenuto della nota (fino a 10.000 caratteri)
- author (string, optional): chi ha scritto la nota
pages (Array, facoltativo)
- title (string, obbligatorio): Il titolo della pagina (deve essere univoco e non vuoto)
- purpose (string, obbligatorio): Cosa deve documentare questa pagina
- parent (string, facoltativo): Titolo della pagina padre per l’organizzazione gerarchica
- page_notes (array, facoltativo): Note aggiuntive specifiche per questa pagina
- Massimo 30 pagine (80 per i clienti enterprise)
- Massimo 100 note complessive (repo_notes + tutte le page_notes combinate)
- Massimo 10.000 caratteri per nota
- I titoli delle pagine devono essere univoci e non vuoti
Esempio 1: Repo Notes per guidare la generazione della wiki
{
"repo_notes": [
{
"content": "Il repository contiene tre aree principali: la cartella frontend/ con i componenti React, la cartella backend/ con i servizi API e la cartella infra/ con gli script di deployment. La documentazione deve evidenziare come queste parti interagiscono e mettere in risalto il livello API backend come priorità principale."
}
]
}
Esempio 2: Assicurarsi che cartelle specifiche siano documentate
{
"repo_notes": [
{
"content": "La cartella cui/ contiene componenti UI critici che devono essere documentati. La cartella backend/ contiene la logica API principale. La cartella utils/ contiene utility condivise utilizzate in tutta la codebase."
}
]
}
Esempio 3: Gestione dei componenti mancanti
{
"repo_notes": [
{
"content": "La directory testing/ contiene utility e pattern di test importanti che gli sviluppatori devono conoscere. La directory scripts/ contiene script di deployment e manutenzione essenziali per le operazioni."
}
]
}
Esempio 4: Struttura gerarchica della documentazione
{
"repo_notes": [
{
"content": "Si tratta di un'applicazione full-stack con componenti frontend, backend e condivisi distinti che devono essere documentati separatamente ma con relazioni chiare tra loro."
}
],
"pages": [
{
"title": "Panoramica dell'Architettura",
"purpose": "Panoramica ad alto livello dell'architettura dell'applicazione e delle interazioni tra componenti"
},
{
"title": "Frontend",
"purpose": "Struttura e componenti dell'applicazione frontend",
"parent": "Panoramica dell'Architettura"
},
{
"title": "Componenti React",
"purpose": "Documentazione dettagliata dei componenti React, delle loro props e del loro utilizzo",
"parent": "Frontend"
},
{
"title": "Gestione dello Stato",
"purpose": "Gestione dello stato dell'applicazione, inclusi store e flusso dei dati",
"parent": "Frontend"
},
{
"title": "Backend",
"purpose": "Servizi backend, API e livello dati",
"parent": "Panoramica dell'Architettura"
},
{
"title": "Endpoint API",
"purpose": "Documentazione delle API REST con endpoint e formati di richiesta/risposta",
"parent": "Backend"
}
]
}
Best practice consigliate
1. Usa le Repo Notes in modo strategico
- Fornisci contesto su quali parti della tua codebase sono più importanti
- Indica cartelle o componenti specifici a cui dare priorità
- Spiega le relazioni tra le diverse parti del tuo sistema
2. Organizza le pagine in modo logico
- Inizia con pagine di panoramica ad alto livello
- Usa relazioni padre-figlio per creare gerarchie chiare
- Raggruppa le funzionalità correlate
3. Sii specifico negli obiettivi di ogni pagina
- Indica chiaramente cosa dovrebbe documentare ciascuna pagina
- Specifica le directory, i file o i concetti su cui concentrarsi
- Fornisci dettagli sufficienti affinché il sistema comprenda le tue intenzioni
- Se sai che alcune parti della tua codebase vengono escluse, includile esplicitamente
- Usa titoli descrittivi che rendano chiaro cosa deve essere trattato
Risoluzione dei problemi più comuni
”Solo alcune cartelle vengono documentate”
Questo è il classico problema dei repository di grandi dimensioni.
Soluzione: Usa .devin/wiki.json per specificare in modo esplicito quali parti della tua codebase devono essere documentate.
Inizia aggiornando solo repo_notes e rigenera la wiki con quel contesto aggiuntivo per verificare se la wiki aggiornata includerà le cartelle mancanti. Aggiungi l’array pages solo se necessario.
”Mancano componenti importanti nella wiki”
Aggiungi pagine specifiche per questi componenti e usa repo_notes per evidenziarne l’importanza.
Ricorda: DeepWiki genererà solo le pagine incluse in questo array, quindi assicurati che siano presenti tutte le pagine, non solo quella mancante.
{
"repo_notes": [
{
"content": "La directory [missing-component] è essenziale per l'applicazione e deve essere documentata in modo completo."
}
],
"pages": [
{
"title": "Nome del componente critico",
"purpose": "Documentare la directory [missing-component] e le sue funzionalità"
}
]
}
- Crea
.devin/wiki.json nella directory principale del tuo repository
- Aggiungi repo_notes che spieghino la struttura e le priorità della tua codebase
- Se necessario, specifica tutte le pagine che vuoi vengano create, con titoli e finalità chiare
- Effettua il commit del file e rigenera la tua wiki
Il sistema ora creerà la documentazione basandosi sulle tue istruzioni esplicite anziché su un’analisi completamente automatica, garantendo una copertura più completa e accurata dei repository di grandi dimensioni. 