convention.sh

¿Qué es convention.sh?

convention.sh es un toolkit alojado para enseñar a los agentes de codificación a producir TypeScript más consistente y listo para producción. Proporciona una biblioteca de convenciones TypeScript ajustadas manualmente que los agentes pueden consultar bajo demanda en lugar de depender de un conjunto de reglas estático limitado por el tamaño del prompt.

El propósito principal es reducir la salida TypeScript descuidada proporcionando a los agentes convenciones concretas —como patrones de tipado más estrictos y enfoques de validación en tiempo de ejecución— entregadas a través de una interfaz estándar.

Características principales

• Servidor MCP alojado para convenciones: convention.sh se ejecuta como un servidor Model Context Protocol (MCP) alojado que un agente puede consultar para obtener los fragmentos de convenciones que necesita.
• Recuperación de fragmentos bajo demanda (27 convenciones): en lugar de incrustar un muro de reglas en cada prompt, los agentes extraen solo los fragmentos relevantes de una biblioteca de 27 convenciones cuando se solicitan.
• Convenciones orientadas a la corrección en TypeScript: las convenciones enumeradas enfatizan el tipado estricto (evitando any), el uso de Zod para validar entradas no confiables y la preferencia por uniones discriminadas sobre campos opcionales.
• Integración con contexto de modelo vía MCP: funciona con cualquier agente que soporte el Standard Model Context Protocol al agregar el endpoint MCP en la configuración del agente.
• Siempre actualizado sin redepliegues: como las convenciones se sirven desde el endpoint MCP alojado, los cambios se aplican en solicitudes posteriores sin necesidad de reescribir prompts o redeplegar aplicaciones.

Cómo usar convention.sh

1. Agrega el endpoint MCP en tu agente usando el comando de terminal proporcionado, que registra el endpoint alojado: claude mcp add conventiondotsh --transport http https://mcp.convention.sh.
2. Inicia tus tareas habituales de TypeScript en tu agente de codificación.
3. Deja que el agente solicite convenciones según sea necesario: durante una tarea, el agente pide el/los fragmento(s) de convención específico(s) del servidor convention.sh cuando los necesita.

Si usas un agente compatible con MCP diferente al ejemplo mostrado, configúralo para llamar al mismo endpoint MCP alojado descrito por convention.sh.

Casos de uso

• Refactorización de módulos TypeScript con estilo consistente: al generar o actualizar código TypeScript, solicita convenciones para que el agente aplique los mismos patrones de tipado y validación de entrada.
• Validación de entradas no confiables en manejadores de API: usa convenciones que recomiendan validación con Zod para mantener la verificación de entrada explícita y consistente.
• Evitar ambigüedad en campos opcionales: al diseñar formas de datos, prefiere uniones discriminadas sobre campos opcionales para aclarar el manejo de variantes en el código generado.
• Reducir el bloat de prompts en sesiones de codificación largas: mantén los prompts del agente enfocados al extraer solo los fragmentos de convención específicos cuando se requieran.
• Equipos estandarizando la salida de agentes: sirve los mismos fragmentos de convención desde un endpoint alojado compartido para que los agentes con integración MCP permanezcan alineados entre máquinas (las actualizaciones se aplican en la siguiente solicitud).

Preguntas frecuentes

• ¿Qué significa “bajo demanda” aquí? Las convenciones se entregan vía un servidor MCP alojado, y el agente solicita solo el/los fragmento(s) necesario(s) de una biblioteca de 27 convenciones durante una tarea en lugar de recibir un conjunto completo de reglas cada vez.

• ¿Necesito construir o alojar algo yo mismo? El sitio describe convention.sh como un servidor MCP alojado, por lo que agregas el endpoint a tu agente en lugar de alojar la biblioteca de convenciones tú mismo.

• ¿Cómo lo integro con mi agente de codificación? Usa el flujo de integración MCP: configura un agente compatible con MCP para usar el endpoint alojado en https://mcp.convention.sh. La página incluye un comando de ejemplo para agregar el servidor MCP.

• ¿Qué tipos de reglas de TypeScript están incluidas? La página enumera ejemplos de convenciones enfocadas en tipado estricto (sin any), validación de entradas no confiables con Zod y preferencia por uniones discriminadas sobre campos opcionales.

• ¿Necesitaré actualizar prompts cuando cambien las convenciones? No—como las convenciones se sirven desde el endpoint MCP alojado, el agente adquiere las nuevas reglas en la siguiente solicitud sin necesidad de redepliegues o copias obsoletas entre máquinas.

Alternativas

• Listas estáticas de reglas en prompts o wikis: puedes incluir directrices de TypeScript directamente en cada prompt, pero esto tiende a aumentar el volumen del prompt y aún puede llevar a una aplicación inconsistente.
• Cadenas de herramientas locales de linting/formateo (p. ej., TypeScript ESLint): estas herramientas ayudan a imponer estilos y detectar problemas después de los hechos, mientras que convention.sh proporciona convenciones durante la generación de código a través de MCP.
• Otras herramientas de contexto para agentes basadas en recuperación: si ya usas RAG o recuperación de contexto basada en herramientas para codificación, podrías construir un flujo de trabajo similar de “consultar convenciones según sea necesario”, aunque esto requeriría mantener tú mismo la biblioteca de convenciones y la lógica de recuperación.