Chi lavora con assistenti di programmazione basati su intelligenza artificiale incontra presto un problema molto concreto. Ogni strumento ha il suo modo di ricevere istruzioni: Claude Code legge il file CLAUDE.md, Cursor utilizza .cursorrules o la cartella .cursor/rules, GitHub Copilot cerca .github/copilot-instructions.md, Cline, Roo Code, Windsurf e altri hanno convenzioni ancora diverse. Se in più si usano Model Context Protocol, comandi personalizzati, sotto-agenti e hook, la configurazione si sparpaglia in decine di file. Basta cambiare una policy interna, uno standard di codice o un endpoint MCP per dover aggiornare tutto a mano, con il rischio di dimenticanze e comportamenti incoerenti tra strumenti.
Rulesync affronta esattamente questo problema. È un progetto open source che propone un'unica fonte di verità leggibile e versionabile, da cui generare le configurazioni native per i diversi assistenti. Pensato per sviluppatori singoli, piccoli team, PMI e agenzie che non vogliono legarsi a una piattaforma pesante, funziona in locale, senza server dedicati e senza canoni per API.
Cos'è Rulesync
Rulesync è una interfaccia a riga di comando scritta in Node.js, pubblicata su GitHub dall'autore dyoshikawa e distribuita con licenza MIT. Non è un assistente AI in sé e non esegue modelli linguistici: è uno strumento di sincronizzazione e generazione di file di configurazione.
L'idea di fondo è semplice. Invece di mantenere a mano CLAUDE.md, .cursorrules, .github/copilot-instructions.md e le altre varianti, si mantiene una sola cartella chiamata .rulesync nella radice del repository. Al suo interno si scrivono regole in Markdown, definizioni di server MCP in JSON, comandi, sotto-agenti, skill e hook in un formato normalizzato. Quando serve, si lancia il comando di generazione e Rulesync produce o aggiorna i file specifici richiesti da ciascuno strumento di destinazione.
Il flusso tipico prevede pochi comandi. Con rulesync init si inizializza la struttura nella cartella corrente. Con rulesync add si aggiungono nuovi elementi. Con rulesync generate --targets si generano i file per uno o più assistenti, ad esempio solo per Claude Code oppure per tutti quelli supportati. Sono disponibili anche funzioni di importazione da configurazioni esistenti, conversione tra formati e recupero di set di regole condivisi tramite fetch, utili per partire da esempi o standard comuni.
Essendo file di testo, tutto il contenuto resta ispezionabile, modificabile con qualsiasi editor e tracciabile in Git come il resto del codice. Questo lo rende molto diverso da soluzioni cloud che centralizzano i prompt su server esterni.
Il problema che risolve: il drift delle istruzioni
Con l'adozione di più assistenti AI nello stesso team, il fenomeno più frequente è il cosiddetto drift: le istruzioni divergono lentamente senza che nessuno se ne accorga. Un aggiornamento viene applicato a Cursor ma non a Copilot, una regola di sicurezza viene aggiunta a Claude Code ma non agli altri agenti, un server MCP aziendale viene configurato su una macchina ma non documentato altrove.
Le conseguenze sono pratiche. Lo stesso modello, interrogato dallo stesso sviluppatore sullo stesso codice, può dare risposte diverse solo perché legge istruzioni diverse. Le revisioni diventano più difficili, perché non è chiaro quale standard l'assistente abbia seguito. Per chi lavora su commessa o in contesti regolati, la mancanza di uniformità crea anche un problema di responsabilità: non si può dimostrare quale policy fosse attiva al momento della generazione.
Rulesync non elimina la necessità di scrivere buone regole, ma elimina la duplicazione manuale. La modifica avviene una sola volta nella cartella sorgente e viene propagata in modo deterministico. Il diff generato può essere revisionato in pull request come qualsiasi altra modifica di codice, con commenti, approvazioni e storia completa. Per team distribuiti e agenzie con collaboratori esterni, questo significa poter imporre standard condivisi senza dover controllare a mano ogni postazione.
Un altro vantaggio è la portabilità. Se un freelance passa da un assistente a un altro, o se un'azienda decide di valutare un nuovo strumento, non deve riscrivere tutto da zero: rigenera i file per il nuovo target a partire dalla stessa base.
Come funziona in pratica
Il funzionamento è volutamente vicino alle abitudini degli sviluppatori. Dopo aver installato il pacchetto via npm, in genere con installazione globale, si entra nella cartella del progetto e si esegue l'inizializzazione. Viene creata la directory .rulesync con sottocartelle per i diversi tipi di contenuto e un file di configurazione principale.
All'interno, le regole sono file Markdown con front-matter per metadati come descrizione, priorità o ambito di applicazione. I server MCP sono descritti in file JSON con comando di avvio, argomenti e variabili d'ambiente. Comandi, sotto-agenti e skill seguono schemi analoghi, pensati per essere facilmente leggibili e convertibili.
Il comando generate legge questa sorgente e applica dei template specifici per ogni strumento. Ad esempio, per Claude Code produrrà o aggiornerà CLAUDE.md e le eventuali directory .claude/commands e .claude/agents, per Cursor produrrà .cursorrules o i file in .cursor/rules, per Copilot il file in .github/. Le opzioni permettono di selezionare destinazioni e funzionalità: si può generare solo per un target, solo per regole e MCP, oppure per tutto l'insieme, spesso con una modalità di anteprima che mostra cosa cambierebbe senza scrivere nulla.
Il comando import fa il percorso inverso: legge configurazioni esistenti sparse nel progetto e le porta dentro .rulesync per iniziare la migrazione senza perdere lavoro precedente. Il comando convert aiuta a trasformare direttamente un formato in un altro, mentre fetch permette di scaricare set di regole pubblicati da terzi come base di partenza.
La pratica consigliata è versionare in Git sia la cartella .rulesync sia i file generati, oppure versionare solo la sorgente e rigenerare in fase di build o onboarding. In entrambi i casi, la revisione resta trasparente e automatizzabile in integrazione continua con un semplice controllo di coerenza.
Cosa si può centralizzare: regole, MCP, comandi, subagenti, skill e hook
Il valore di Rulesync dipende da quante tipologie di configurazione riesce a coprire. Secondo la documentazione del progetto, le aree principali sono sei.
Le regole sono il cuore: linee guida di stile, convenzioni di naming, stack consentiti, policy su test, documentazione e lingua delle risposte. È qui che una PMI può fissare, ad esempio, che il codice Python segua un certo linter, che le commit seguano un formato convenzionale o che le risposte siano sempre in italiano.
La configurazione MCP è la seconda area chiave. Il Model Context Protocol permette agli assistenti di accedere a strumenti esterni come database, repository, motori di ricerca o API interne. Centralizzare la lista dei server MCP evita che ogni sviluppatore ne usi una versione diversa e semplifica la distribuzione di connettori aziendali.
I comandi personalizzati sono prompt riutilizzabili richiamabili con una scorciatoia, come revisiona-codice, genera-test o spiega-funzione. I sotto-agenti sono assistenti specializzati con istruzioni proprie, utili per compiti come refactoring, analisi di sicurezza o scrittura di documentazione. Le skill sono pacchetti di istruzioni modulari, spesso in formato SKILL.md, che descrivono come svolgere compiti ricorrenti.
Infine, gli hook sono automazioni legate a eventi, come eseguire un formatter prima di accettare un suggerimento o bloccare operazioni rischiose. Non tutti gli strumenti supportano tutte le funzionalità allo stesso modo, quindi la conversione può richiedere adattamenti. La documentazione invita a verificare la matrice di compatibilità per ogni combinazione di target e funzionalità, perché alcune opzioni avanzate potrebbero non avere un equivalente diretto altrove.
Perché è rilevante per PMI, agenzie e freelance italiani
Per una piccola impresa o un'agenzia web italiana, il tema non è accademico. Spesso lo stesso team usa strumenti diversi: un socio preferisce Claude Code, un collaboratore usa Cursor, il cliente impone Copilot su repository GitHub. Senza un meccanismo comune, ogni standard interno deve essere riscritto tre volte e aggiornato tre volte.
Rulesync permette di trattare le istruzioni per l'AI come parte del patrimonio aziendale, allo stesso livello delle linee guida di design o dei manuali qualità. Una software house può mantenere un repository interno di regole condivise su stile, privacy, gestione dei dati personali e best practice, e distribuirlo su tutti i progetti clienti con un semplice fetch e generate. Un'agenzia che lavora per settori diversi può avere varianti per e-commerce, gestionali o siti vetrina, mantenendo comunque una base comune.
Per i freelance è un modo per professionalizzare il lavoro: stessi standard applicati ovunque, onboarding più rapido su nuovi progetti, possibilità di mostrare al cliente esattamente quali istruzioni segue l'assistente. Poiché tutto avviene in locale e in chiaro, non ci sono dati di configurazione inviati a servizi terzi, aspetto rilevante per chi tratta codice proprietario o dati sensibili.
Dal punto di vista economico, l'approccio è leggero. Non richiede infrastrutture aggiuntive né abbonamenti: basta Node.js e Git, strumenti già presenti in quasi tutti i team. Il costo principale è organizzativo, cioè prendersi il tempo per scrivere regole chiare e mantenerle, ma è un investimento che riduce rilavorazioni e incomprensioni.
Licenza, requisiti, limiti e dove trovarlo
Il progetto è pubblicato su GitHub all'indirizzo github.com/dyoshikawa/rulesync, dove si trovano codice sorgente, documentazione, esempi ed elenco delle versioni. La licenza dichiarata è MIT, tra le più permissive: consente uso commerciale, modifica e redistribuzione, a condizione di mantenere avviso di copyright e testo di licenza. Il pacchetto è distribuito anche tramite npm per installazione globale o come dipendenza di sviluppo.
I requisiti sono contenuti: una versione recente di Node.js, accesso a terminale e familiarità di base con Git e Markdown. Non sono richiesti server, database o chiavi API per le funzioni principali di generazione locale.
Esistono limiti da considerare. La copertura non è identica per tutti gli assistenti: alcuni target sono supportati meglio di altri e le funzionalità più recenti degli assistenti potrebbero non essere ancora mappate. La conversione automatica tra formati diversi non è sempre perfetta, soprattutto per hook e sotto-agenti con semantiche proprietarie, per cui è consigliabile revisionare sempre il diff generato. Come per qualsiasi strumento che scrive file di configurazione ed esegue script di installazione, è buona norma provarlo prima in un repository di prova, controllare cosa viene generato e leggere gli script prima di eseguirli in ambienti di produzione.
Per chi inizia, il percorso più prudente è importare le configurazioni esistenti di un piccolo progetto pilota, generare per un solo assistente in modalità anteprima, confrontare il risultato e solo dopo estendere agli altri strumenti e agli altri repository. In questo modo Rulesync diventa non un ulteriore livello di complessità, ma il punto unico dove la conoscenza operativa del team resta scritta, condivisa e verificabile.