~/projects/fabulous-factory
Fabulous Factory
Lo starter Next.js costruito per lo sviluppo guidato dagli agenti: auth, billing, job, email, LLM e osservabilità sono già integrati, mentre guardrail eseguibili impediscono agli agenti di rompere silenziosamente il sistema che li circonda.
Il problema
Gli agenti AI sanno costruire funzionalità applicative molto in fretta. Possono anche aggirare un controllo di autenticazione, importare l'SDK di un vendor nel layer sbagliato, spargere l'accesso alle variabili d'ambiente nel codebase o pubblicare un webhook senza validarne l'input. Un documento di convenzioni chiede al modello di ricordare. Il software in produzione ha bisogno di garanzie più forti.
Allo stesso tempo, chi avvia un SaaS non dovrebbe passare settimane a ricollegare sempre le stesse fondamenta: autenticazione, pagamenti, job in background, email transazionali, analytics, error tracking, migrazioni e un gateway LLM. La velocità conta, ma uno starter ottimizzato solo per il primo commit crea debito già dal secondo.
Fabulous Factory tratta i due problemi come uno solo: offre agli agenti un telaio completo e coerente, poi codifica le regole non negoziabili in API, confini tra package e CI, così le decisioni meccaniche vengono verificate in modo meccanico.
Il mio ruolo e la tesi
Ho progettato e costruito Fabulous Factory come template open source per lo sviluppo di prodotto guidato dagli agenti. È l'espressione più concreta della mia tesi attuale: mentre i foundation model convergono, il vantaggio si sposta dal cervello al telaio — tooling, infrastruttura, contesto e cicli di feedback.
Ho disegnato architettura, workflow di adozione e tour rivolto agli esseri umani come un unico sistema. Il repository non contiene solo starter code: porta con sé istruzioni per gli agenti, specifiche, template ADR, scaffold, un registro delle capability e una definition of done verificabile dalla macchina.
Il principio di design è volutamente netto: ciò che è meccanico non deve mai essere probabilistico. Le persone dichiarano l'intento di prodotto; gli agenti lo implementano; il repository fa rispettare le regole che non possono dipendere dalla memoria o dalla qualità di un prompt.
L'architettura della factory
Il template congela uno stack volutamente opinionato e investe la complessità in profondità: seam sicuri, degradazione controllata e workflow di adozione capaci di reggere lavoro agentico continuativo.
Contratti al posto delle convenzioni
Ogni route e server action passa da defineHandler o defineAction. Modalità di autenticazione e schema di input sono argomenti obbligatori: un agente non può omettere per sbaglio la decisione. Gli handler grezzi fanno fallire i controlli del repository.
Confini visibili alla build
Gli SDK dei vendor restano nei rispettivi adapter, le chiamate LLM passano da un solo gateway e le variabili d'ambiente da un registro tipizzato. Regole sulle dipendenze e lint trasformano l'intento architetturale in un check che fallisce, non in un paragrafo destinato a invecchiare.
Graceful degradation come contratto
Solo PostgreSQL e un secret di autenticazione formano la base. Billing, LLM, job, email, analytics ed error tracking si risolvono a runtime e degradano senza rompere il resto: modalità gratuita, fallback manuali, trasporto console o no-op silenziosi.
Un solo quality gate
pnpm check esegue lint, confini delle dipendenze, formattazione, typecheck, test e verifica del manifest. La stessa definition of done è leggibile da persone, agenti e CI.
Il repository come memoria degli agenti
Skill, specifiche, ADR, convenzioni e scaffold vivono accanto al codice che governano. factory:init trasforma il template generico nel repository di prodotto di chi lo adotta e consegna agli agenti un modello operativo specifico.
Una demo viva e ispezionabile
Il page monitor incluso attraversa ogni package. Le pagine marketing e feature leggono la capability map reale del deployment: la documentazione mostra ciò che il sistema in esecuzione sa davvero fare, invece di descrivere una configurazione ideale.
In numeri
10
package con confini espliciti
6
seam di servizi opzionali
2
variabili richieste alla base
1
definition of done verificabile
I guardrail, in pratica
api/monitors/route.ts
export const POST = defineHandler({
auth: "required",
input: createMonitorSchema,
rateLimit: { windowSeconds: 60, max: 20 },
handler: async ({ session, input }) => ...
});
Le decisioni di sicurezza sono obbligatorie nell'API
disabled ≠ broken · runtime capability map
I servizi opzionali dichiarano il proprio stato a runtime
pnpm check
one definition of done
Un comando verifica l'intero repository
Stato
Fabulous Factory è pubblico e in sviluppo attivo sul branch develop. La versione attuale include le fondamenta complete, il layer di adozione della factory, il tour vivo delle feature e la demo del page monitor. È distribuito con licenza MIT ed è pensato per essere clonato, inizializzato una volta e reso interamente proprio.
Codice e documentazione
Altri progetti
Emovia
Un diario guidato con IA per il lavoro clinico, costruito con gli psicologi.
Arianna
Una piattaforma di studio che ricostruisce il materiale sparso di un corso in un manuale strutturato e collegato alle domande.
Power Puzzles
Un generatore di rompicapo basato su vincoli con soluzione unica garantita.