Intensivo Grátis 21–22/11Intensivo gratuito de 2 dias em Vibecoding (21–22/11 às 16:00 MSK) · Turma 3 começa 23/11Inscrever-se grátis →Turma 3 (23/11)
LançamentoAPI / Produto · Pronto p/ usoHabr AI→ original

A estrutura de Claude Code funcionava para um só, mas quebrou para os colegas: 5 passos rumo à portabilidade

A estrutura (harness) reúne skills, conexões MCP, subagentes e verificações ao redor de um agente de IA como o Claude Code. Para o autor, da Directum, ela funcionou um ano sem falhas, mas quebrou na mão dos colegas: os scripts ainda tinham caminhos da máquina dele, e numa VM limpa não havia Python nem Node.js. Ele descreveu cinco passos para se tirar da equação: os caminhos agora partem da raiz do repositório, e o instalador verifica o ambiente por conta própria. A conclusão: teste a instalação numa máquina limpa antes de chamar o primeiro colega.

Processado por IA de Habr AI; editado por Hamidun News
A estrutura de Claude Code funcionava para um só, mas quebrou para os colegas: 5 passos rumo à portabilidade
Fonte: Habr AI. Colagem: Hamidun News.
Ouvir artigo
Ficha técnica e números-chave
ParâmetroDados
Fonte originalHabr AI ↗
Editor-chefe
Dado-chave #1O ciclo "revisão — correção" é limitado a três tentativas; depois disso, entra um humano
Dado-chave #2Para as tarefas do autor, a assinatura sai bem mais em conta que os tokens da API, e não é preciso servidor
Dado-chave #3Evals — cenários de verificação — detectam skills quebradas após ajustes

Muita gente já montou uma estrutura pessoal em volta de um agente de IA: assistiu a vídeos curtos, juntou skills, conectou MCP e acabou com um posto de trabalho "estruturado". A estrutura, ou harness, é tudo o que cerca o modelo: ferramentas, instruções, base de conhecimento, subagentes e verificações. Enquanto há um único usuário, ela funciona.

O autor desta análise, especialista da Directum em promoção da plataforma Directum RX, descobriu o que acontece depois. Sua estrutura rodou um ano sem falhas, mas bastou entregá-la aos colegas para ela quebrar: a peça central era o próprio autor, e não dá para instalar o autor por meio de um instalador. A seguir, ele descreve cinco passos para se tirar da equação.

Parte das soluções já funciona, parte ainda está em ajuste, e ele mesmo classifica o texto como experiência pessoal, e não como manual para montar uma equipe de IA.

O que exatamente foi repassado

O autor recebe requisitos de clientes e precisa mostrar rapidamente, num protótipo, como implementá-los na plataforma. O ambiente de desenvolvimento do Directum RX (Development Studio) tem uma API JSON-RPC, conectada ao Claude Code via MCP. O agente cria entidades, propriedades e esqueletos de métodos pelo mesmo mecanismo que o desenvolvedor usa na janela do ambiente e, depois, escreve a lógica de negócio em C#. Os pacotes são publicados no ambiente de testes pelo utilitário padrão Deployment Tool, e o resultado é verificado pela API e pela interface web.

O trabalho é dividido entre subagentes: o product owner prepara os requisitos e os critérios de aceitação, o arquiteto projeta a solução, o desenvolvedor escreve código e testes, o testador verifica os cenários, e três revisores analisam em paralelo o código, a segurança e a aderência à arquitetura. Os artefatos de cada etapa ficam na pasta .pipeline, e as transições são controladas por um script: ele confere os resultados obrigatórios e salva o estado, de modo que, após uma pausa, o coordenador retoma do mesmo ponto.

Há dois ciclos de "verificar — corrigir": um para o projeto da solução e outro para o código. Cada um tem limite de três tentativas. Sem limite, os subagentes podem passar muito tempo, empolgados, corrigindo uns aos outros e queimando os limites da assinatura. Se a terceira tentativa falha, o coordenador chama um humano e salva a descrição do bug, os resultados das verificações e o histórico das tentativas.

Servidor compartilhado ou instalação local

O autor avaliou duas opções. A primeira é um serviço compartilhado com sandboxes (por exemplo, GoClaw ou OpenHands): o usuário recebe um ambiente pré-configurado com a versão necessária do produto. Para uma equipe com um único ambiente, isso é conveniente. Mas a estrutura deveria ser usada por várias equipes, com produtos, versões da plataforma e conjuntos de soluções diferentes. Não dá para montar um único ambiente para todos, e manter várias variantes exigiria uma equipe dedicada.

Por isso, a escolha foi a instalação local: cada pessoa clona a estrutura de um repositório próprio no GitLab interno e trabalha com a própria assinatura. Para as tarefas do autor, a assinatura sai bem mais em conta que pagar tokens pela API, e não é preciso subir um serviço compartilhado desde o primeiro dia. As equipes são conectadas aos poucos, observando se a estrutura ajuda. O preço da escolha é que dependências, caminhos, acessos e versões de ferramentas variam de uma máquina para outra.

O que é comum, o que é do projeto e o que é pessoal ficam em lugares separados. As regras gerais vão para o repositório da estrutura, os requisitos do projeto ficam junto do código dele, e as configurações e acessos pessoais permanecem locais, fora do Git. Enquanto só o autor usava a estrutura, os scripts tinham caminhos da máquina dele fixados no código. Agora a estrutura procura seus arquivos a partir da raiz do repositório, e o instalador lê de um arquivo de configuração os caminhos do Development Studio e do Deployment Tool.

As atualizações chegam por um hook do Claude Code, isto é, um script executado no início da sessão. Ele percebe uma nova versão, sugere puxar as mudanças, atualiza as dependências e confere se as ferramentas iniciam. As configurações locais são preservadas, os conflitos com ajustes feitos pelas equipes são exibidos, e é possível voltar para a versão anterior.

Primeira execução numa máquina limpa

O hook não foi a primeira coisa a surgir. Antes, o autor subiu uma VM limpa, clonou o repositório e iniciou o agente. Os erros apareceram antes da primeira tarefa útil: faltavam dependências que ele havia instalado na própria máquina há muito tempo e esquecido. Uma ferramenta precisa de Python, outra de Node.js, e uma terceira não tinha bibliotecas. No começo, o próprio agente ajudava na configuração, mas às vezes a preparação consumia todo o limite da janela de cinco horas do Claude.

Agora o novo participante executa o instalador: ele verifica o ambiente, instala as dependências e configura os servidores MCP. Uma instalação interrompida pode ser repetida, e as etapas já concluídas são puladas. Se o mesmo erro se repete com várias pessoas, a solução é incorporada ao instalador.

Ele leva em conta o sistema operacional, o SGBD e a versão da plataforma. Por exemplo, a plataforma funciona tanto com PostgreSQL quanto com MSSQL, mas os utilitários do autor baseados em psql não estão disponíveis com MSSQL, e o instalador avisa sobre isso. As ferramentas são testadas justamente a partir do Claude Code, porque funcionar no terminal e estar acessível ao agente são coisas diferentes.

E, como o Bash rodava de forma instável sob antivírus no Windows, os pontos de entrada dos scripts foram migrados para Node.js.

Para que os ajustes das equipes não quebrem o comportamento do agente, são executados evals — cenários de verificação com critérios de sucesso definidos de antemão. Digamos que alguém adaptou uma skill básica ao seu projeto e ela deixou de fazer a verificação obrigatória antes de concluir a tarefa: esse cenário aponta a regressão. Em compensação, os evals cobrem apenas os casos descritos neles.

O que fazer na prática

Uma estrutura para uma pessoa e uma estrutura para uma equipe diferem não pelo conjunto de ferramentas, mas por quanto da estrutura depende do autor. Se você pretende compartilhar uma estrutura de agente, teste a instalação numa VM limpa, elimine os caminhos absolutos, separe o que é comum, do projeto e pessoal, defina um limite de tentativas para os ciclos de correção e crie evals para as skills principais. Ressalva: é a experiência de um engenheiro numa empresa, e para outras plataformas as soluções terão de ser escolhidas de novo.

História

Perguntas frequentes sobre a notícia

O que exatamente foi repassado?

O autor recebe requisitos de clientes e precisa mostrar rapidamente, num protótipo, como implementá-los na plataforma. O ambiente de desenvolvimento do Directum RX (Development Studio) tem uma API JSON-RPC, conectada ao Claude Code via MCP. O agente cria entidades, propriedades e esqueletos de métodos pelo mesmo mecanismo que o desenvolvedor usa na janela do ambiente e, depois, escreve a lógica de negócio em C#.

O que se sabe sobre Servidor compartilhado ou instalação local?

O autor avaliou duas opções. A primeira é um serviço compartilhado com sandboxes (por exemplo, GoClaw ou OpenHands): o usuário recebe um ambiente pré-configurado com a versão necessária do produto. Para uma equipe com um único ambiente, isso é conveniente. Mas a estrutura deveria ser usada por várias equipes, com produtos, versões da plataforma e conjuntos de soluções diferentes. Não dá para montar um único ambiente para todos, e manter várias variantes exigiria uma equipe dedicada.

O que se sabe sobre Primeira execução numa máquina limpa?

O hook não foi a primeira coisa a surgir. Antes, o autor subiu uma VM limpa, clonou o repositório e iniciou o agente. Os erros apareceram antes da primeira tarefa útil: faltavam dependências que ele havia instalado na própria máquina há muito tempo e esquecido. Uma ferramenta precisa de Python, outra de Node.js, e uma terceira não tinha bibliotecas. No começo, o próprio agente ajudava na configuração, mas às vezes a preparação consumia todo o limite da janela de cinco horas do Claude.

ZK
Zhemal Khamidun — CPO da Alpina Digital, gerente de produto do AlpinaGPT. Cria produtos de IA desde 2019. O Hamidun News é um projeto pessoal que virou um agregador em produção com mais de 6.000 leitores.
✦ Hands-On AI Engineering · Hamidun Academy

Build & Ship Production AI Agents Without Boilerplate Code

Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.

Start 72h Free Trial →Vibe-Coding Intensive
O que você acha?
Carregando comentários…