convention.sh

Cos'è convention.sh?

convention.sh è un toolkit hosted per insegnare agli agenti di coding a produrre TypeScript più consistente e pronto per la produzione. Fornisce una libreria di convenzioni TypeScript ottimizzate manualmente che gli agenti possono recuperare su richiesta, invece di affidarsi a un ruleset statico limitato dalla dimensione del prompt.

Lo scopo principale è ridurre l'output TypeScript approssimativo fornendo agli agenti convenzioni concrete—come pattern di typing più rigorosi e approcci di validazione runtime—consegnate tramite un'interfaccia standard.

Caratteristiche Principali

• Server MCP hosted per convenzioni: convention.sh funziona come un server Model Context Protocol (MCP) hosted che un agente può interrogare per ottenere gli snippet di convenzione necessari.
• Recupero snippet su richiesta (27 convenzioni): invece di incorporare un muro di regole in ogni prompt, gli agenti estraggono solo gli snippet rilevanti da una libreria di 27 convenzioni quando richiesti.
• Convenzioni orientate alla correttezza TypeScript: le convenzioni elencate enfatizzano typing rigoroso (evitando any), l'uso di Zod per validare input non fidati e discriminated unions preferite rispetto ai campi opzionali.
• Integrazione model-context via MCP: funziona con qualsiasi agente che supporta lo Standard Model Context Protocol inserendo l'endpoint MCP nella configurazione dell'agente.
• Sempre aggiornato senza ridistribuzioni: poiché le convenzioni sono servite dall'endpoint MCP hosted, i cambiamenti vengono rilevati nelle richieste successive senza bisogno di riscrivere prompt o ridistribuire applicazioni.

Come Usare convention.sh

1. Aggiungi l'endpoint MCP nel tuo agente usando il comando terminale fornito, che registra l'endpoint hosted: claude mcp add conventiondotsh --transport http https://mcp.convention.sh.
2. Avvia i tuoi soliti task TypeScript nel tuo agente di coding.
3. Lascia che l'agente richieda le convenzioni quando necessario: durante un task, l'agente chiede gli snippet di convenzione specifici dal server convention.sh quando ne ha bisogno.

Se usi un agente MCP-capace diverso dall'esempio mostrato, configuralo per chiamare lo stesso endpoint MCP hosted descritto da convention.sh.

Casi d'Uso

• Refactoring di moduli TypeScript con stile consistente: durante la generazione o l'aggiornamento di codice TypeScript, richiedi convenzioni affinché l'agente applichi gli stessi pattern per typing e validazione input.
• Validazione input non fidati in handler API: usa convenzioni che raccomandano validazione Zod per mantenere il controllo input esplicito e consistente.
• Evitare ambiguità campi opzionali: nel progettare shape dati, preferisci discriminated unions rispetto a campi opzionali per rendere la gestione varianti più chiara nel codice generato.
• Ridurre bloat prompt in sessioni coding lunghe: mantieni i prompt dell'agente focalizzati facendogli estrarre solo gli snippet di convenzione specifici quando necessari.
• Team che standardizzano output agente: servi gli stessi snippet di convenzione da un endpoint hosted condiviso così gli agenti con integrazione MCP rimangono allineati tra macchine (aggiornamenti rilevati alla prossima richiesta).

FAQ

• Cosa significa “su richiesta” qui? Le convenzioni sono consegnate via server MCP hosted, e l'agente richiede solo gli snippet necessari da una libreria di 27 convenzioni durante un task, invece di ricevere un ruleset completo ogni volta.

• Devo buildare o hostare qualcosa io stesso? Il sito descrive convention.sh come server MCP hosted, quindi aggiungi l'endpoint al tuo agente invece di hostare la libreria di convenzioni tu stesso.

• Come lo integro con il mio agente di coding? Usa il flusso di integrazione MCP: configura un agente MCP-capace per usare l'endpoint hosted su https://mcp.convention.sh. La pagina include un comando esempio per aggiungere il server MCP.

• Che tipi di regole TypeScript sono incluse? La pagina elenca esempi di convenzioni focalizzate su typing rigoroso (no any), validazione input non fidati con Zod e preferenza per discriminated unions rispetto a campi opzionali.

• Devo aggiornare i prompt quando cambiano le convenzioni? No—poiché le convenzioni sono servite dall'endpoint MCP hosted, l'agente rileva le nuove regole alla prossima richiesta senza bisogno di ridistribuzioni o copie obsolete tra macchine.

Alternative

• Elenchi statici di regole nei prompt o wiki: puoi includere linee guida TypeScript direttamente in ogni prompt, ma questo tende ad aumentare il volume del prompt e può comunque portare a un'applicazione incoerente.
• Catene di strumenti locali di linting/formattazione (es. TypeScript ESLint): questi strumenti aiutano a imporre lo stile e catturare problemi ex post, mentre convention.sh fornisce convenzioni durante la generazione del codice tramite MCP.
• Altri strumenti di contesto per agenti basati su retrieval: se usi già RAG o fetching di contesto basato su tool per il coding, potresti creare un workflow simile “recupera convenzioni al bisogno”, anche se ciò richiederebbe di mantenere tu stesso la libreria di convenzioni e la logica di retrieval.