Internacionalizei minha UI e esqueci meu servidor MCP

Na noite passada, um dos meus agentes de IA terminou uma limpeza em FlurryPORT e me deu uma instrução: remover a antiga vinculação de roteamento.

Palavras razoáveis. Ele as obteve da minha própria implementação do MCP. Eu construí o produto do qual ele estava falando, e ainda assim abri a aba errada. A coisa mais próxima na minha tela das palavras do agente era uma lixeira, e aquela lixeira teria levado toda a transformação com ela, cascata e tudo.

O agente estava certo sobre o trabalho. A instrução falhou na última polegada. Sua palavra para a coisa não era a palavra do botão para a coisa, e a correspondência mais próxima às suas palavras era destrutiva.

Eu parei com o cursor sobre a lixeira. Essa é a única razão pela qual esta é uma história sobre design, em vez de uma tarde passada redefinindo entidades que nunca precisaram ser perturbadas.

Depois de ter trabalhado principalmente como revisor de código de planos de desenvolvimento cuidadosamente elaborados, perdi uma coisa crucial: a redação apresentada a um agente de IA através da minha implementação do MCP era diferente da redação que a interface do usuário apresentava ao usuário daquele agente. Neste caso, eu era o usuário, na minha própria aplicação, sendo solicitado por um agente de IA através de um protocolo MCP de meu próprio design. Não me ocorreu que, quando a passagem da interface do usuário foi concluída semanas atrás, a convenção de nomenclatura que a IA estava produzindo para a receita do MCP sairia diferente. O que gera outra regra a ser observada ao projetar software -- estabelecer o vocabulário que ambos os membros da audiência usarão, IA e humano.

O design mobile-first ensinou uma geração de nós a projetar para a menor tela primeiro e deixar que tudo o mais seguisse. O design agent-first soa como o mesmo movimento. Essa é a armadilha, porque o agente não é um humano menor.

É um segundo leitor e tradutor. Cada superfície que você envia agora tem dois leitores: o humano que clica e o agente que lê, planeja e retransmite instruções de volta ao humano. Eles não falham de forma independente. O agente retransmite em seu vocabulário, o humano executa pela correspondência mais próxima, e a lacuna entre esses dois vocabulários é onde o produto quebra. Não no modelo. Não na API. Na transferência de IA para humano.

O que torna isso caro é que nada sobre isso parece um bug. Ambos os lados passam. A interface do usuário faz exatamente o que seus rótulos dizem. A superfície do MCP faz exatamente o que suas descrições dizem. Nada lança, nada registra, nenhum teste fica vermelho, porque o defeito só existe no espaço entre os dois e nenhuma suíte que você possui está olhando lá. Portanto, não aparece no desenvolvimento. Aparece nas mãos de um usuário, ou no meu caso, nas minhas próprias mãos, com o cursor sobre uma lixeira.

Essa é a mais antiga discussão em software, vestindo novas roupas. Uma hora gasta decidindo como as coisas são chamadas é mais barata do que a tarde gasta desfazendo o que alguém deletou porque ninguém decidiu.

A transferência soa abstrata até você ir procurá-la, e então acaba tendo um endereço. Em uma implementação do MCP, tudo o que o agente lê se encaixa em uma lista curta: nomes e descrições de ferramentas, nomes de parâmetros e seus valores permitidos, strings de erro e o texto do resultado que você devolve. Isso é tudo. Todo o resto é implementação que o agente nunca vê.

Agora, eu tenho um hábito que irrita outros desenvolvedores e que eu corrijo constantemente em agentes de codificação de IA. Cada string que um humano verá vai em um arquivo de configuração. Não inline, não no componente, em um arquivo de recursos com uma chave, para que no dia em que alguém precisar do produto em alemão, eu possa entregar esse arquivo a um tradutor e recebê-lo de volta. É disciplina a serviço de um futuro que pode nunca chegar, que é exatamente o motivo pelo qual as pessoas resistem a isso.

Essa disciplina teria evitado isso. Uma chave contém uma palavra. Se o rótulo do botão e a descrição da ferramenta ambos se resolvem a partir da mesma chave, eles não podem se desviar, porque há apenas um deles para se desviar. Mas eu nunca a estendi para a prosa que uma IA escreve para outra IA. Qual é o mal, eu pensei, em deixar a coisa que codifica a coisa escolher as palavras que descrevem a coisa.

Há o mal. Strings voltadas para o agente são strings visíveis para humanos, elas apenas fazem uma parada extra para chegar lá. Descrições de ferramentas, nomes de parâmetros, texto de erro, o corpo de um resultado: tudo isso eventualmente é lido em voz alta para uma pessoa por um agente, o que torna isso a voz do seu produto, quer você tenha escrito ou não. Mesmo arquivo. Mesmas chaves que a interface do usuário, onde quer que seja a mesma palavra. E se você está começando de uma base de código que já se desviou, o caminho de volta é maçante. Descrições de ferramentas em uma coluna, rótulos da interface do usuário na outra, leia na transversal. Cada linha onde as palavras diferem é uma linha onde um agente entregará ao seu usuário uma frase à qual seu produto não responde. Isso não é uma revisão de código. É uma revisão de design, e pertence à passagem em que você decide os rótulos dos botões, não semanas depois.

Nada disso é uma nova preocupação, e outras pessoas estão nomeando isso. O design voltado para agentes é a frase que continuo vendo, e é uma justa. Marca o momento em que uma audiência secundária se tornou uma primária, da mesma forma que o mobile-first fez.

O que estou descrevendo é mais estreito do que uma categoria. É o método que usamos dentro de uma, e aqui chamamos de design de piloto de porto. Quando um navio entra em um porto que não conhece, um piloto embarca. O piloto possui o conhecimento local: os canais, as profundidades, os marcadores, o que as palavras no mapa realmente significam neste porto. O capitão mantém a ponte. O piloto navega, o capitão comanda, e nenhum dos dois finge ser o outro.

Essa é a forma que eu quero entre um agente de IA e a pessoa para quem ele trabalha. O agente embarca no seu produto e navega nele fluentemente, porque possui o conhecimento local e eu o dei de propósito. As chamadas que apenas um capitão faz permanecem na ponte: o que publicar, o que deletar, o que gastar. E o trabalho todo do produto entre eles é fazer a transferência sem perdas, que é onde as últimas três seções têm estado. A palavra do piloto para uma coisa tem que ser a palavra da ponte para essa coisa. Caso contrário, o piloto diz para remover a antiga vinculação de roteamento, o capitão alcança a coisa mais próxima que parece com isso, e o porto recebe um novo naufrágio no mapa.

A lixeira tem um fim, e não é um pós-mortem.

A descoberta foi arquivada na mesma manhã: a cópia voltada para o agente usa as palavras da interface do usuário. Até aquela noite, a correção estava pública na versão do CLI, e a ferramenta agora diz exatamente o que o botão diz. Quase nada disso foi código. Foi uma decisão que eu ainda não havia tomado, e uma vez que foi tomada, o resto foi digitação.

Que é a parte que vale a pena refletir. A coisa cara nunca foi a correção. Foram as semanas que a discrepância ficou lá, enviada, na frente de cada agente que a leu, enquanto eu revisava planos de desenvolvimento cuidadosamente elaborados que estavam todos corretos sobre o código e silenciosos sobre as palavras. Uma hora de design durante a passagem da interface do usuário teria custado uma hora. Encontrá-la da maneira que encontrei custou a correção, mais as semanas, mais um cursor pairando sobre uma lixeira.

Três regras, então. Nenhuma delas precisa de uma nova ferramenta, e todas são decisões de design em vez de código.

1. O vocabulário é decidido uma vez, e ambas as audiências leem a partir dessa decisão. Eu já passei uma seção inteira sobre isso, então aqui está a versão que cabe em um post-it. Se o botão diz Roteamento, então a descrição da ferramenta, o texto de erro