Creare un Claude Code Mod in TypeScript: il primo progetto

Per creare un Claude Code Mod in TypeScript parti da un plugin piccolo: manifest, collegamento al modulo e file di ingresso. Il codice può reagire agli eventi e usare la Mods API; Claude Code carica direttamente JavaScript e TypeScript nel percorso base, senza richiedere bundler o build. La guida ufficiale di creazione indica Claude Code 2.1.287 o successiva.

Il primo obiettivo dovrebbe essere capire il ciclo scrivere, caricare, validare e provare, non costruire subito un’integrazione aziendale completa. Questa guida, verificata il 9 ottobre 2026, descrive un progetto didattico: un contatore delle chiamate agli strumenti. I frammenti di configurazione sono esempi; non dichiariamo un plugin eseguito o un benchmark. Per il contesto generale vedi cosa sono i Mods.

Quale primo mod scegliere per imparare senza complicare il progetto?

Un contatore è un buon esercizio perché il suo requisito può essere descritto senza rete, credenziali o dati di clienti: mostra quante chiamate sono state osservate e offre un modo per consultare il valore. Il tutorial ufficiale usa proprio un contatore. Puoi studiarne l’architettura senza copiare subito tutte le parti: prima chiarisci cosa conta, quando riparte e dove appare.

Una chiamata osservata non è necessariamente un’operazione riuscita. Questa distinzione deve comparire nel testo dell’interfaccia, altrimenti il numero suggerisce una precisione che non possiede. Se vuoi contare operazioni concluse, il requisito cambia: devi definire quali esiti includere, come trattare errori e rifiuti e quale evento osservare. È una scelta di prodotto prima che di codice.

Un’alternativa è un indicatore del branch. Sembra altrettanto semplice, ma richiede leggere un dato e mantenerlo aggiornato. Un branch vecchio mostrato come attuale può essere più dannoso dell’assenza dell’indicatore. Scegli quindi il contatore se vuoi imparare eventi e stato; scegli l’indicatore se il bisogno reale è riconoscere il contesto del repository. Non unire i due esercizi soltanto per rendere il primo progetto più impressionante.

Quali sono i tre file del mod?

La confezione base separa identità, caricamento e comportamento. Il manifest descrive il plugin. hooks/hooks.json indica quale modulo caricare. Il modulo esporta register, che collega eventi e funzioni. La documentazione dei componenti plugin e la guida Mods descrivono questi confini.

Un manifest didattico può essere:

{
  "name": "conteggio-locale",
  "version": "0.1.0",
  "description": "Contatore didattico delle chiamate osservate"
}

Il collegamento al modulo, salvato in hooks/hooks.json, può essere:

{
  "description": "Modulo del contatore didattico",
  "modules": ["./register.ts"]
}

Questi due JSON descrivono soltanto la confezione. Mancano intenzionalmente il comportamento e le prove: il loro contenuto non basta a chiamare il mod funzionante. Il percorso ./register.ts è relativo a hooks.json; collocare il file altrove senza cambiare il collegamento è un errore semplice da diagnosticare prima di aprire una sessione.

Percorso assistito o manuale: come decidere?

Il percorso assistito parte da una descrizione nella sessione interattiva e usa la Skill integrata /plugin-authoring. Il percorso manuale permette di vedere ogni responsabilità del pacchetto. Entrambi richiedono comprendere il codice e il processo di caricamento; delegare la scrittura a Claude non trasferisce automaticamente la responsabilità del plugin. Il tutorial su claude.dev presenta il contesto del primo progetto.

Per una richiesta assistita scrivi un requisito chiuso: contare chiamate osservate, rendere disponibile il valore, dichiarare quando si azzera e non leggere contenuti dei file. Aggiungi il comportamento in caso di reload. Questa descrizione rende la review possibile: puoi confrontare ogni operazione del codice con qualcosa richiesto. «Fammi un mod utile» non offre lo stesso criterio.

La guida ufficiale prevede approvazioni per i file di sviluppo e per il caricamento nella sessione. La cartella generata è legata alla sessione, non una sede permanente di distribuzione. Se decidi di conservarla, prepara una directory riconoscibile e un README prima di coinvolgere colleghi. La guida a installare Mods in Claude Code distingue la prova locale dall’installazione abituale.

Come leggere eventi, API e continuazione senza confonderli?

Un handler riceve l’API, il dato dell’evento e una continuazione. In un osservatore il comportamento normale deve proseguire; in un comando gestito dal mod il risultato può essere prodotto dal componente. La differenza va scelta deliberatamente. Omettere la continuazione in un punto sbagliato può trasformare un indicatore passivo in un componente che altera il flusso. React to events.

Per il contatore, disegna prima una mappa testuale: un evento inizializza o prepara la funzione, uno aggiorna il valore, uno mostra il risultato richiesto. Poi chiedi quale parte necessita davvero della UI. Un comando di consultazione è già sufficiente per verificare il valore; il disegno durante il lavoro è un requisito aggiuntivo. Separare questi passaggi facilita il debugging.

Se il mod deve modificare un evento, non ragionare come se potessi cambiare liberamente l’oggetto ricevuto. La reference documenta un evento congelato: la trasformazione passa da una copia. Anche la relazione fra più Mods merita attenzione: la funzione osserva un punto della catena, non una visione onnisciente di tutte le operazioni. Reference Mods.

Perché i tipi locali contano più di uno snippet online?

Le pagine online evolvono. Il progetto deve invece funzionare sulla versione installata. I file .d.ts generati dentro .claude-plugin/types/ descrivono eventi, metodi e componenti di quella build; la guida invita a preferirli quando divergono dalla pagina. Cercare un metodo nel tipo locale è una verifica più utile di assumere che un nome copiato sia già disponibile.

Questo vale anche per le funzioni recenti. La possibilità di registrare un tool con isDeferred: false ha un confine 2.1.293 o successiva, documentato nelle release ufficiali. Il primo contatore non ha bisogno di quel campo: aggiungerlo solo perché esiste farebbe crescere il requisito di compatibilità senza aiutare l’esercizio.

Nel README scrivi la versione contro cui hai controllato il progetto, la superficie scelta e il significato dei dati mostrati. Il typecheck può scoprire un campo mancante, ma non capisce se la scritta «operazioni completate» descrive davvero un contatore di tentativi. La review del codice con Claude va quindi affiancata a criteri funzionali precisi.

Quali forme di codice deve riconoscere l’analisi statica?

Il caricatore non interpreta il modulo come un programma arbitrario privo di vincoli. La guida richiede nomi di evento letterali, chiamate dell’API riconoscibili e import compatibili con il percorso Mods. Per esempio, rendere un namespace dell’API una variabile generica può impedire l’analisi. Prima di introdurre helper o registrazioni generate, controlla le regole della versione locale. Regole di analisi statica.

Per il primo progetto conviene mantenere registrazioni esplicite. Non serve un framework interno per pochi eventi: rende meno evidente cosa viene osservato e cosa viene lasciato proseguire. Un helper può essere utile quando riduce una duplicazione reale, ma deve restare compatibile con l’analisi e rendere la responsabilità più chiara. La brevità non coincide con l’uso di nomi calcolati o con una registrazione nascosta in un ciclo.

Prima della review prepara una piccola mappa dei dati: da quale evento nasce il valore, chi lo aggiorna e quale ingresso lo legge. Se il contatore è temporaneo, chiarisci il reset nel comando. Se deve sopravvivere al reload, progetta quel passaggio e la sua prova. Questo disegno evita di scegliere uno store persistente soltanto perché una variabile si è azzerata: la durata del dato deve seguire il requisito del prodotto.

Quale ciclo di verifica usare durante lo sviluppo?

Lavora sulla directory di sviluppo, non sulla cache di una copia installata. Prima controlla struttura e manifest con claude plugin validate, poi verifica i comportamenti con i test pertinenti. Soltanto dopo carica il plugin esaminato nella superficie prevista. La reference CLI separa validazione e test, compresa la modalità stretta della validazione.

Il ciclo può essere descritto così: modifica piccola, validazione, prova del comportamento interessato, confronto del risultato, eventuale reload. Non serve rifare ogni esperimento per una correzione di testo; serve invece ampliare la prova quando cambi stato, eventi o autorità del componente. Registra l’esito, senza trasformare il semplice salvataggio di un file in una verifica.

Quando posso dire che il contatore è verificato?

Quando una sequenza nota produce il valore atteso, un evento non pertinente non altera il valore e reload o nuova sessione rispettano il comportamento dichiarato. La UI deve usare una descrizione coerente con ciò che viene contato. Se manca una di queste prove, il progetto può essere un prototipo valido ma non ancora una funzione verificata per quel workflow.

La guida a testare un mod senza login o chiamate al modello approfondisce fixture e stub. Un test di comportamento non richiede una sessione produttiva, ma non certifica da solo tutta la resa visiva. Per un componente UI servono prove sulle superfici che il progetto dichiara di supportare.

Due primi progetti ipotetici in un team italiano

Esempio ipotetico: una software house di Firenze vuole capire un flusso di strumenti. Il gruppo costruisce il contatore su dati sintetici. Definisce che il numero rappresenta chiamate osservate, non edit riuscite. Un comando mostra il valore dopo una sequenza nota e il test verifica che il reload abbia il comportamento dichiarato. Il componente non deve registrare nomi clienti o contenuti dei file.

La prima review controlla quindi parole e confini prima dell’estetica. Se il numero sale anche quando una chiamata viene rifiutata, non è automaticamente un bug: dipende dal requisito. Il team può cambiare la descrizione o scegliere un evento diverso, aggiornando le prove. Il progetto insegna a rendere esplicita una metrica, non a rivendicare un guadagno di produttività.

Esempio ipotetico: un’agenzia di Verona prova un indicatore del branch. Il requisito nasce da un passaggio frequente tra repository. L’indicatore deve mostrare il branch corrente e un messaggio chiaro quando non può leggerlo. La prova include il cambio di directory, una cartella senza repository e il ricaricamento del mod.

Il responsabile scopre che un’informazione statica non basta: conta il suo aggiornamento. Prima di aggiungere colori e pulsanti, il gruppo decide quando rileggere il valore e come riconoscere un dato vecchio. Se non riesce a farlo con un contratto piccolo, riconsidera l’idea. La reversibilità della prova consente di fermare l’esperimento senza averlo reso dipendenza del lavoro quotidiano.

Quali scorciatoie rendono fragile il primo mod?

La prima è aggiungere rete, processi e credenziali a un esercizio che non ne ha bisogno. La seconda è modificare l’evento come un oggetto qualsiasi, ignorando il contratto documentato. La terza è usare una variabile di modulo e aspettarsi che sopravviva a ogni reload. La quarta è considerare l’analisi statica una prova del risultato. La quinta è distribuire la cartella temporanea senza versione e responsabile.

Ogni scorciatoia nasconde una decisione. Quale servizio serve davvero? Quando deve vivere il dato? Cosa prova il test? Chi riceverà l’aggiornamento? Rispondere prima di aggiungere codice riduce il numero di elementi da diagnosticare. Se un progetto non si carica, conserva il messaggio e usa la diagnosi pratica dei Mods, invece di riscrivere tutto il modulo alla cieca.

Come passare dal primo esercizio a una funzione utile?

Scegli un solo bisogno del workflow e scrivi il contratto con input, risultato, errore e durata dello stato. Poi decidi se basta il comando o serve anche uno strumento per Claude. La guida a comandi e tool con la Mods API aiuta in questa scelta. Non trasformare automaticamente ogni comando dell’utente in un tool disponibile al modello.

Se la personalizzazione deve entrare nel lavoro di più persone, prepara test, versionamento e provenienza prima della distribuzione. Il percorso di software su misura può partire da questo piccolo requisito e collegarlo al processo del team. Le guide a Claude per codice e sicurezza dei dati completano il quadro per scegliere quali responsabilità affidare alla nuova funzione.