convention.sh

O que é convention.sh?

convention.sh é um toolkit hospedado para ensinar agentes de codificação a produzir TypeScript mais consistente e pronto para produção. Ele fornece uma biblioteca de convenções TypeScript ajustadas manualmente que os agentes podem buscar sob demanda, em vez de depender de um conjunto de regras estático limitado pelo tamanho do prompt.

O propósito principal é reduzir a saída desleixada de TypeScript fornecendo aos agentes convenções concretas — como padrões de tipagem mais rigorosos e abordagens de validação em runtime — entregues por meio de uma interface padrão.

Principais Recursos

• Servidor MCP hospedado para convenções: convention.sh executa como um servidor Model Context Protocol (MCP) hospedado que um agente pode consultar para obter os trechos de convenções necessários.
• Recuperação de trechos sob demanda (27 convenções): em vez de embutir uma parede de regras em cada prompt, os agentes puxam apenas os trechos relevantes de uma biblioteca de 27 convenções quando solicitados.
• Convenções focadas na correção do TypeScript: as convenções listadas enfatizam tipagem rigorosa (evitando any), uso de Zod para validar entrada não confiável e preferência por discriminated unions em vez de campos opcionais.
• Integração com contexto de modelo via MCP: funciona com qualquer agente que suporte o Standard Model Context Protocol ao adicionar o endpoint MCP na configuração do agente.
• Sempre atualizado sem redeploys: como as convenções são servidas do endpoint MCP hospedado, as mudanças são capturadas nas solicitações subsequentes, sem necessidade de reescrever prompts ou redeployar a aplicação.

Como Usar convention.sh

1. Adicione o endpoint MCP no seu agente usando o comando de terminal fornecido, que registra o endpoint hospedado: claude mcp add conventiondotsh --transport http https://mcp.convention.sh.
2. Inicie suas tarefas usuais de TypeScript no seu agente de codificação.
3. Deixe o agente solicitar convenções conforme necessário: durante uma tarefa, o agente pede o(s) trecho(s) de convenção específico(s) do servidor convention.sh quando precisar.

Se você estiver usando um agente compatível com MCP diferente do exemplo mostrado, configure-o para chamar o mesmo endpoint MCP hospedado descrito pela convention.sh.

Casos de Uso

• Refatoração de módulos TypeScript com estilo consistente: ao gerar ou atualizar código TypeScript, solicite convenções para que o agente aplique os mesmos padrões de tipagem e validação de entrada.
• Validação de entrada não confiável em handlers de API: use convenções que recomendam validação com Zod para manter a verificação de entrada explícita e consistente.
• Evitando ambiguidade de campos opcionais: ao projetar formas de dados, prefira discriminated unions em vez de campos opcionais para tornar o tratamento de variantes mais claro no código gerado.
• Reduzindo inchaço de prompt em sessões de codificação longas: mantenha os prompts do agente focados, fazendo com que ele puxe apenas os trechos de convenções específicos quando necessário.
• Equipes padronizando saída de agentes: sirva os mesmos trechos de convenções de um endpoint hospedado compartilhado para que agentes com integração MCP permaneçam alinhados entre máquinas (atualizações são capturadas na próxima solicitação).

FAQ

• O que significa “sob demanda” aqui? As convenções são entregues via servidor MCP hospedado, e o agente solicita apenas o(s) trecho(s) necessário(s) de uma biblioteca de 27 convenções durante uma tarefa, em vez de receber um conjunto completo de regras toda vez.

• Preciso construir ou hospedar algo eu mesmo? O site descreve convention.sh como um servidor MCP hospedado, então você adiciona o endpoint ao seu agente em vez de hospedar a biblioteca de convenções sozinho.

• Como integro com meu agente de codificação? Use o fluxo de integração MCP: configure um agente compatível com MCP para usar o endpoint hospedado em https://mcp.convention.sh. A página inclui um comando de exemplo para adicionar o servidor MCP.

• Que tipos de regras TypeScript estão incluídas? A página lista convenções de exemplo focadas em tipagem rigorosa (sem any), validação de entrada não confiável com Zod e preferência por discriminated unions em vez de campos opcionais.

• Preciso atualizar prompts quando as convenções mudarem? Não — como as convenções são servidas do endpoint MCP hospedado, o agente capta as novas regras na próxima solicitação, sem necessidade de redeploys ou cópias desatualizadas entre máquinas.

Alternativas

• Listas estáticas de regras em prompts ou wikis: você pode incluir diretrizes TypeScript diretamente em cada prompt, mas isso tende a aumentar o tamanho do prompt e ainda pode levar a aplicações inconsistentes.
• Ferramentas locais de linting/formatação (ex.: TypeScript ESLint): essas ferramentas ajudam a impor estilos e detectar problemas após o fato, enquanto convention.sh fornece convenções durante a geração de código via MCP.
• Outras ferramentas de contexto para agentes baseadas em recuperação: se você já usa RAG ou busca de contexto baseada em ferramentas para codificação, poderia construir um fluxo de trabalho similar de “buscar convenções conforme necessário”, embora isso exija manter a biblioteca de convenções e a lógica de recuperação você mesmo.