Archspec investigate: como LLMs detectam conflitos entre serviços antes da escrita do código

Um desenvolvedor verificou se uma LLM consegue detectar conflitos entre serviços na etapa de planejamento — antes da primeira linha de código. A ferramenta é archspec com contratos legíveis por máquina `SERVICE_MAP.yaml`, o recurso é a reatribuição automática de tarefas após recusa de um freelancer.

Onde LLM perde contexto entre serviços

Na primeira parte do ciclo, o autor documentou um problema estrutural do desenvolvimento assistido por LLM em sistemas de microsserviços. Cada serviço individualmente, o modelo descreve perfeitamente — mas quando uma funcionalidade passa por múltiplos serviços, o plano desmorona. A razão: as regras nas fronteiras entre serviços — status permitidos, ordem de chamadas, restrições nas transições — não estão gravadas em um único lugar.

Cada serviço é documentado localmente, em isolamento. A LLM vê cada fragmento separadamente, mas não vê o sistema como um todo. Os acordos entre serviços permanecem implícitos, e o modelo os ignora.

A funcionalidade "reatribuição de tarefas após recusa do freelancer" é um bom teste precisamente porque afeta múltiplos serviços de uma vez: fila de tarefas, notificações, cobrança, perfis de executores. Um erro em qualquer transição quebra todo o fluxo. Foi nesta funcionalidade que o plano falhou em alinhar pela primeira vez.

Contratos em vez de Markdown em forma livre

A segunda parte do ciclo apresentou archspec — uma ferramenta que gera um arquivo `SERVICE_MAP.yaml` para cada serviço. Isto não é documentação em forma livre para humanos com descrições narrativas, mas um contrato legível por máquina: restrições explícitas, transições permitidas entre estados, dependências entre serviços e requisitos de dados em cada transição. A diferença é fundamental. Markdown em forma livre é texto que uma LLM interpreta com suposições. `SERVICE_MAP.yaml` é dados estruturados que um modelo analisa deterministicamente. Não há espaço para "alucinações" sobre acordos implícitos. Elementos-chave do contrato:

• Formatos explícitos de entrada e saída para cada serviço
• Transições permitidas entre status de objetos de negócio
• Campos obrigatórios para chamadas entre serviços
• Restrições de lógica de negócio nas fronteiras de serviços

O que /archspec:investigate mostrou

As condições do teste são rígidas: o mesmo prompt, o mesmo modelo (Claude Sonnet 4.6), a mesma funcionalidade. A única diferença — contratos legíveis por máquina em cima de `SERVICE_MAP.yaml` em vez de texto em forma livre.

"O mesmo prompt, o mesmo modelo.

A questão é: o plano conseguirá detectar esses erros entre serviços antes do código ser escrito," — o autor formula a essência do experimento.

Com contratos, o modelo detectou conflitos entre serviços já na etapa de planejamento — exatamente os que pela primeira vez surgiram apenas após o código ser escrito. Formalizar fronteiras deu à LLM contexto estruturado suficiente para transições corretas entre serviços antes da primeira linha de implementação ser escrita. Mas a ferramenta tinha limitações. Archspec investigate funciona exatamente tão bem quanto os próprios contratos são precisos. Se `SERVICE_MAP.yaml` ficou para trás do código real — o modelo planeja a partir de um mapa desatualizado e erra novamente. A implementação em si também foi separadamente verificada contra o plano final: lá também foram encontrados pontos onde o código "saiu" do pretendido — e isto é uma parte honesta da pesquisa.

O que isto significa

Desenvolvimento orientado a especificações com LLM em microsserviços funciona — mas requer contratos explícitos legíveis por máquina. Sem eles, o modelo estruturalmente perde contexto entre serviços: isto não é uma questão de qualidade de prompt ou poder do modelo. Archspec é uma forma prática de fixar este contexto, a ferramenta está disponível no GitHub. A principal limitação: manter `SERVICE_MAP.yaml` atualizado requer esforço manual — este é um passo separado que precisa ser incorporado ao processo de desenvolvimento. Sem contratos atualizados, a ferramenta cria falsa confiança em vez de ajuda real.