Come abbiamo trasformato un progetto brownfield multi-repo in un workflow di sviluppo agentico con OpenCode e SpecKit — senza forzare un monorepo.
Modernizzare un progetto software legacy (“brownfield”) con l’assistenza dell’AI è oggi un obiettivo raggiungibile — anche quando il codice è distribuito su più repository. In questo articolo, ti guido attraverso come abbiamo evoluto un progetto Git multi-repository classico in un workflow di sviluppo assistito da AI utilizzando OpenCode e GitHub SpecKit. Lungo il percorso, confronteremo questo approccio con altri assistenti di coding AI come GitHub Copilot, Amazon CodeWhisperer e Sourcegraph Cody, e condivideremo lezioni pratiche apprese.
I nostri obiettivi erano chiari:
✅ Una vista unificata e coerente dell’applicazione multi-repo (frontend, backend, componenti condivisi)
✅ Generazione e manutenzione automatiche della documentazione tecnica “as-is”
✅ Un flusso operativo ripetibile per analisi, sviluppo di feature ed esecuzione locale
Questo percorso si inserisce in una esplorazione più ampia che sto documentando. Se ti interessano le basi architetturali di questo approccio, ti consiglio di leggere il mio articolo precedente:
👉 https://medium.com/p/627795029809
🧩 La Sfida del Multi-Repo Brownfield
In un setup enterprise tipico, una singola applicazione spesso si estende su più repository Git — ad esempio, una UI frontend, uno o più servizi backend, librerie condivise e codice di infrastruttura. Ogni repo ha la propria storia e il proprio ciclo di deployment. Questa separazione è intenzionale e vantaggiosa per l’autonomia dei team, ma crea problemi quando gli assistenti di coding AI devono comprendere il quadro completo.
I progetti brownfield amplificano questa sfida: la codebase è grande, matura e plasmata da anni di decisioni e convenzioni. Introdurre un agente AI in questo ambiente significa che deve apprendere i pattern del progetto e non rompere nulla. L’AI necessita di una vista panoramica del sistema per essere veramente utile — altrimenti potrebbe suggerire modifiche che ignorano dipendenze in un altro repo o codice che non segue le convenzioni esistenti.
Perché non passare direttamente a un monorepo? Migrare tutto il codice in un solo repository potrebbe dare all’AI il contesto completo, ma è di solito impraticabile per un sistema maturo. Il passaggio a un monorepo introduce overhead pesanti (cambiamenti CI/CD, tooling, interruzione dei flussi di team) e rischi significativi senza benefici immediati. A meno che non si parta da zero o i repository siano già strettamente accoppiati, una migrazione a monorepo raramente vale la pena per questo scopo. Invece, abbiamo cercato una soluzione non disruptiva: mantenere i repo separati ma lasciare che l’AI li veda e lavori su di essi come se fossero unificati.
🛠️ Implementazione Passo-Passo
Step 1: Consolida i Repository Localmente
Abbiamo creato un workspace locale e clonato tutti i repo Git rilevanti (frontend, backend, componenti condivisi) in sottocartelle. Questo fornisce una struttura di file unificata per l’analisi.
📎 Per approfondire questo setup e la sua rationale, vedi il mio articolo: https://medium.com/p/627795029809
mkdir workspace
cd workspace
git clone <repo-frontend-url> frontend
git clone <repo-backend-url> backend
git clone <repo-shared-url> shared
Step 2: Valida una Baseline Pulita
git -C frontend status
git -C backend status
git -C shared status
git -C frontend remote -v
git -C backend remote -v
git -C shared remote -v
Step 3: Crea un Repository Dedicato per le Specifiche
mkdir spec
cd spec
git init
git branch -M main
git remote add origin <repo-spec-url>
Step 4: Inizializza OpenCode e SpecKit
opencode init
speckit init
Step 5: Genera la Documentazione AS-IS
speckit scan --source ../workspace
speckit generate as-is
speckit export --format md --out ./docs/as-is
Step 6: Commit e Verifica
git add .
git commit -m "chore(spec): initial AS-IS baseline"
git push -u origin main
Poi verifica l’esecuzione locale:
cd ../workspace/frontend
npm install
npm start
cd ../backend
npm install
npm run dev
🤖 Usare Agenti AI su un Sistema Brownfield
Comprensione Cross-Repo
Con tutti i repository caricati nel contesto, l’AI poteva ragionare su modifiche che coinvolgevano frontend, backend e codice condiviso. Identificava correttamente dove posizionare le modifiche e ci chiedeva di confermare quale repo modificare.
Aggiornamenti Automatici della Documentazione
Dopo aver implementato le modifiche, riavviavamo:
speckit scan --source ../workspace
speckit generate as-is
speckit export --format md --out ./docs/as-is
Sviluppo Iterativo, Spec-First
Abbiamo seguito la metodologia di SpecKit:
- Scrivi o aggiorna una specifica
- Genera un piano con
/plan - Scomponi i task con
/tasks - Implementa con OpenCode
Guidare l’AI con le Regole
Abbiamo perfezionato la nostra Costituzione per:
- Prevenire la duplicazione del codice
- Applicare il layering architetturale
- Vietare anti-pattern (es. try/catch nei componenti UI) 📎 Ho esplorato questo argomento in modo più approfondito in un articolo dedicato: https://medium.com/p/da4204b3286a
📚 Perché Tenere le Specifiche e la Documentazione in un Repository Separato?
Abbiamo scelto di memorizzare tutte le specifiche e la documentazione in un repository Git dedicato (spec) invece di mescolarle nel codice dell’applicazione. Questo ha permesso:
- Versioning e storia indipendenti
- Workflow di review dedicati
- Meno rumore nei repository del codice
- Migliore governance della documentazione cross-repo
Alternative come incorporare le specifiche in ogni repo o memorizzarle in una cartella non versionata sono state scartate a causa della frammentazione, della mancanza di versioning e della scarsa revisionabilità.
⚖️ Confronto tra Tool: Assistenti AI per Progetti Brownfield
Un aspetto chiave della nostra valutazione è stato il confronto tra diversi strumenti di AI assistance. GitHub Copilot eccelle nel suggerire codice inline all’interno dell’IDE, ma ha un contesto limitato al file corrente o alla piccola porzione di codice aperta. Amazon CodeWhisperer e Sourcegraph Cody offrono una comprensione più ampia del repository, ma faticano ancora a coordinare modifiche coerenti su più repo separati. OpenCode, combinato con SpecKit, si è distinto per la capacità di operare su un workspace consolidato, applicare regole architetturali e mantenere la documentazione sincronizzata — senza richiedere una migrazione a monorepo.
Per progetti brownfield complessi, la scelta dello strumento non è solo una questione di qualità del completamento codice, ma di governance del cambiamento: quanto l’AI riesce a capire le regole del tuo sistema e a rispettarle durante modifiche estese.
🚀 Conclusione
Trasformare un progetto brownfield multi-repo in un workflow assistito da AI non è solo possibile — è potente. Federando i nostri repository in un singolo contesto AI e adottando un processo di sviluppo spec-first, abbiamo ottenuto:
- Coerenza tra i repository
- Documentazione sempre aggiornata
- Iterazioni più veloci con meno overhead manuale
Non abbiamo dovuto ristrutturare il progetto o forzare un monorepo. Invece, abbiamo introdotto tooling AI in modo complementare ai flussi esistenti. Ad ogni iterazione, l’AI si è allineata maggiormente alla nostra architettura e alle nostre convenzioni.
Questo approccio è adatto a tutti? Se gestisci una codebase grande e complessa distribuita su più repository, credo che meriti seria considerazione. Con il setup e la governance giusti, gli agenti AI possono diventare collaboratori potenti — che non dormono mai, non dimenticano mai e seguono sempre le regole che tu definisci.
Riferimenti
- https://medium.com/p/627795029809 — Architectural foundations
- https://medium.com/p/da4204b3286a — Constitution and guardrails
- OpenCode: https://opencode.dev
- SpecKit: https://speckit.dev
- GitHub Copilot, Amazon CodeWhisperer, Sourcegraph Cody
Andrea Schiona — AI Breakfast / Software Architecture
