archify: la mappa cliccabile del codice che ti ha scritto Claude

Cos'è e perché conta

Claude ti ha scritto un progetto intero. Funziona, ma dopo tre settimane non sai più cosa tocca cosa: quale file parla con il database, cosa rischi se cambi quella funzione.

archify è una skill, cioè un pacchetto di istruzioni e script che Claude usa quando serve. Chiedi la mappa con una frase: Claude legge i file del progetto e archify disegna un file HTML, con le parti principali in riquadri e i collegamenti in frecce. Prima di consegnarlo controlla che frecce ed etichette reggano; se un controllo non passa, Claude corregge.

È gratuito e open source (licenza Apache 2.0), con più di 90.000 stelle su GitHub a fine ottobre. È per chi costruisce da solo con Claude Code e vuole capire il proprio progetto o spiegarlo a un cliente. Funziona anche con Codex, Cursor e OpenCode.

1. Installalo in Claude Code

Ti serve Claude Code con Node.js sul computer. Su claude.ai, nel browser, dipende dall'accesso a Node.js della sandbox: è pensato per Claude Code. Nella cartella del progetto incolla la frase ufficiale:

Install Archify for me by reading https://raw.githubusercontent.com/tt-a1i/archify/main/llms.txt

Claude legge le istruzioni, ti dice cosa lancerà e ti chiede se lo vuoi in tutti i progetti (globale) o solo in questo. Poi installa e lancia il controllo doctor: archify è pronto solo se passa.

Dal terminale è una riga sola. --copy copia i file invece di collegarli, --yes salta le domande; senza --global vale solo nella cartella in cui la lanci:

npx -y skills@latest add https://archify.si --skill archify --agent claude-code --global --copy --yes

Poi il controllo, con il percorso che l'installer ti scrive alla fine (per Claude Code di solito ~/.claude/skills/archify):

node ~/.claude/skills/archify/bin/archify.mjs doctor

2. La mappa del tuo progetto

Nella cartella del progetto, copia questa richiesta. È quella ufficiale, tradotta:

Analizza questo repository, poi usa archify per creare un diagramma di alto livello dell'architettura in esecuzione. Mostra da 8 a 12 componenti principali, un percorso principale, le dipendenze esterne e i confini di fiducia. Metti i dettagli nelle schede invece di aggiungere altre frecce.

Le dipendenze esterne sono i servizi non tuoi: database in cloud, pagamenti, email. I confini di fiducia sono dove i dati passano a una parte che non controlli, tipo dal browser al tuo server. E 8-12 parti è il punto: 40 riquadri non li legge nessuno.

Claude segue chi chiama chi, dall'ingresso del progetto fino a dove i dati entrano, escono o vengono salvati. Alla fine ti dà il link al file, salvato anche nella cartella .archify del progetto.

Se il progetto è pubblico su GitHub, aggiungi «collega ogni componente ai file e alle righe che lo provano»: i riquadri si segnano con SRC e aprono il codice da cui vengono. Prima fai il commit: archify cita l'ultimo commit, non le modifiche aperte.

3. Senza codice: parti da un'idea

Il repository non serve: basta un'idea, un piano, un processo. A Claude serve solo una cartella qualsiasi dove scrivere il file.

Usa archify per trasformare questa descrizione in un diagramma di architettura di alto livello: [chi usa il prodotto, le parti principali, il percorso principale, i servizi esterni]. Non c'è un repository. Chiedimi solo i fatti che cambiano davvero il diagramma, segna come sconosciuto quello che non sai e tieni un percorso principale chiaro.

Per provarlo in dieci secondi: «Usa archify per disegnare: Browser -> API -> cache Redis -> PostgreSQL se la cache non ha il dato». Poi continui, una modifica per messaggio:

• «Aggiungi l'autenticazione.»
• «Evidenzia il percorso quando la cache non ha il dato.»
• «Sposta l'autenticazione a sinistra.»
• «Passa al tema chiaro.»

4. Una pagina sola per chi non programma

A volte la domanda è «come funziona questa cosa». archify fa anche una pagina sola: prima la risposta, poi un pannello per domanda. I passi stanno accanto al diagramma e, mentre leggi, accendono le parti di cui parlano.

Usa archify per rispondere con una pagina sola, da mandare a un cliente che non programma: come funziona [il pagamento] nella mia app, dal clic dell'utente fino a [la ricevuta]? Prima la conclusione, poi i passi accanto al diagramma del percorso. Parole semplici, niente gergo.

Anche questa è un file HTML: si esporta come immagine lunga o si stampa in PDF.

5. I tasti per esplorare la mappa

Apri il file nel browser del computer. Da qui in poi archify non serve: è tutto dentro il file.

• Clic su una parte: si accendono le parti collegate e si apre la sua scheda, con quello che entra e quello che esce. Esc la chiude.
• Upstream e Downstream, nella scheda: tutto quello che porta a quella parte, oppure tutto quello che parte da lì, passo dopo passo.
• R: il percorso. Clicchi la partenza e l'arrivo, archify mostra la strada più corta lungo le frecce e la puoi far scorrere.
• /: cerca una parte per nome. ?: la guida della mappa, con le azioni che quel file permette.
• E: esporta. T: tema chiaro o scuro. S: cambia stile. F: presentazione, con la mappa che prende tutta la finestra, comoda in una call.
• + e - per lo zoom, 0 per tornare alla vista iniziale. Live anima le frecce, Still le ferma.

Le frecce sono quelle che Claude ha scritto nella mappa: Upstream e Downstream seguono quelle, non il programma che gira. Ti dicono dove guardare, non l'impatto di una modifica: il codice lo rileggi tu.

6. Mandala a un cliente

La mappa è un file solo. Lo mandi per email o in chat, chi lo riceve lo apre nel browser e ha tutto, senza installare niente. Solo i link esterni, come quelli al codice su GitHub, vogliono la connessione.

Per un'immagine da mettere in una slide, premi E:

• La mappa intera in PNG negli appunti, o da scaricare in PNG, JPEG, WebP, SVG e come video WebM animato.
• Route Share Card: dopo aver tracciato un percorso con R, un'immagine 1200×630 con quel percorso in evidenza e il resto della mappa intorno.
• Reach Share Card: la stessa cosa, dopo Upstream o Downstream.

Le immagini non si cliccano: se il cliente deve esplorare, mandagli l'HTML. E prima rileggi etichette e schede: possono contenere dettagli del tuo codice che non vuoi far vedere.

Gli errori più comuni

• Chiedere «disegna tutto il progetto»: viene una mappa che non si legge. Chiedi 8-12 parti e un percorso, o una funzione alla volta.
• Prendere le frecce per verità: i controlli di archify dicono che il disegno è fatto bene, non che il programma si comporta così.
• Aprire la mappa sul telefono: non è pensata per gli schermi piccoli. Usa il computer.
• Cercare un link per condividerla online: archify non ospita le mappe. Mandi il file o un'immagine.

Checklist

• Ho installato archify e il controllo doctor è passato
• Ho chiesto la mappa del mio progetto con 8-12 parti e un percorso
• Ho cliccato una parte e provato Upstream e Downstream
• Ho tracciato un percorso con R ed esportato la sua Share Card
• Ho mandato il file HTML a qualcuno e l'ha aperto senza installare niente

Domande frequenti