Moxie Docs

Cos'è Moxie Docs?

Moxie Docs è un sistema di documentazione per repository GitHub che genera e mantiene automaticamente la documentazione della codebase. Indicizza un repo, crea documentazione ricercabile per architettura, convenzioni e walkthrough, e ricontrolla quelle pagine quando il codice cambia, così il materiale obsoleto può essere segnalato e riscritto.

Espone inoltre convenzioni del repo e contesto verificato agli strumenti AI tramite MCP, con accesso in sola lettura limitato al task. Inoltre, può aprire una pull request settimanale “Friday Cleanup” dedicata solo alla documentazione per raccogliere il drift accumulato durante la settimana.

Funzionalità principali

• Indicizzazione continua del repository: Moxie si collega a un repository GitHub e mantiene aggiornato l’indice man mano che avvengono i merge, così la documentazione resta allineata al codice più recente.
• Documentazione generata e con fonti: Crea pagine di architettura, convenzioni e walkthrough con citazioni al codice sorgente, rendendo l’output più facile da verificare.
• Rilevamento del drift al merge: Quando le modifiche al codice impattano la documentazione esistente, Moxie segnala il drift e rigenera le pagine rilevanti invece di lasciarle obsolete.
• Contesto MCP per gli agenti: Strumenti AI come Cursor, Claude Code e Codex possono recuperare convenzioni, documentazione e comandi verificati tramite MCP senza dover ricrawlare il repo a ogni prompt.
• PR Friday Cleanup: Una volta a settimana, Moxie può aprire una pull request dedicata solo alla documentazione per raccogliere e presentare gli aggiornamenti da revisionare.
• Controlli del flusso di lavoro delle PR: Può verificare l’impatto sulla documentazione e l’allineamento della descrizione prima del merge, lasciando al team il controllo delle modifiche al codice e del merge.

Come usare Moxie Docs

Inizia collegando un repository GitHub. Moxie indicizza la codebase, genera il primo set di documentazione e riassume le convenzioni riutilizzabili da persone o agenti AI.

Da lì, i team lo usano in due modi principali: revisionare la documentazione che Moxie genera e aggiorna, e far controllare le nuove pull request per individuare documentazione obsoleta o descrizioni non allineate. Se lo desideri, l’integrazione MCP può essere usata dagli agenti di sviluppo per recuperare contesto specifico del repo in modo limitato e in sola lettura.

Casi d'uso

• Mantenere aggiornata la documentazione dell’architettura: un team gestisce pagine come il comportamento dei webhook o i flussi di fatturazione, con Moxie che aggiorna la documentazione quando arrivano modifiche al codice correlate.
• Fornire contesto del repo agli agenti di coding: gli sviluppatori che usano Cursor, Claude Code o Codex possono recuperare convenzioni e comandi verificati senza navigare manualmente nel repository.
• Revisionare settimanalmente il drift della documentazione: i team che vogliono una cadenza regolare di pulizia possono rivedere la PR Friday Cleanup dedicata solo alla documentazione invece di rincorrere pagine obsolete in modo sporadico.
• Verificare l’impatto delle PR prima del merge: i maintainer possono vedere se una pull request impatta la documentazione o richiede una riscrittura della descrizione prima che venga mergiata.
• Onboarding di nuovi engineer: i nuovi contributor possono cercare la documentazione generata e i segnalibri in un unico workspace invece di leggere più file sorgente per capire le convenzioni.

FAQ

Moxie modifica automaticamente il mio codice? No. La descrizione fonte dice che le modifiche al codice restano sotto il controllo del team. Gli aggiornamenti della documentazione vengono consegnati come pull request dedicate solo alla documentazione e revisionabili, mentre l’allineamento della descrizione modifica la descrizione della PR anziché il codice.

Cosa succede dopo aver collegato un repository? Moxie indicizza il repo, genera documentazione ricercabile, riassume le convenzioni e inizia a controllare le nuove pull request per l’impatto sulla documentazione e l’allineamento della descrizione.

L’accesso al repository è limitato? Sì. La descrizione del prodotto dice che l’accesso è in sola lettura per impostazione predefinita e limitato per repository, e che il contesto MCP è ristretto al task e non all’intera codebase.

Quali tipi di documentazione genera? La pagina cita in particolare pagine di architettura, convenzioni, walkthrough e documentazione per temi come i webhook di fatturazione.

Funziona solo con GitHub? La pagina è scritta per repository GitHub, quindi GitHub è la fonte supportata descritta qui.

Alternative

• Documentazione manuale in Markdown o in un wiki dei documenti: è l’alternativa più semplice, ma non ricontrolla automaticamente la documentazione rispetto al codice né genera aggiornamenti con fonti.
• Strumenti generici di code search e navigazione dei repository: aiutano a ispezionare i file, ma non offrono un livello di documentazione mantenuto né PR di pulizia solo docs.
• Assistenti AI di coding standalone senza documentazione aware del repo: possono rispondere a domande e modificare il codice, ma si affidano comunque alla ri-scoperta del contesto da parte del modello, a meno di essere affiancati da un sistema come Moxie.
• Workflow interni per la documentazione basati su pull request e review: i team possono gestire i documenti manualmente tramite PR, ma devono creare e monitorare da soli i controlli di drift invece di farseli generare dal codebase.