Como escrever um único documento de contexto para Claude Code e Jev sem repetir explicação

Fala aí, beleza? Quem lê o documento de contexto é o Claude Code, NÃO o Jev, e entender isso muda o jeito de montar ele 🙂

Todo mundo que usa agente de código já passou por isso: sessão nova, e lá vai você explicar de novo onde fica cada pasta, qual comando roda o teste e por que a arquitetura é daquele jeito

Aí aparece o Jev e bate a vontade de mandar o mesmo textão pra ele também

Se liga na correção de premissa:

• O Claude Code lê o CLAUDE.md inteiro em toda sessão
• O Jev, modelo da TypeSafe AI em early access desde 15 de setembro de 2026, não lê documento de projeto: ele recebe um state e perguntas tipadas e devolve respostas estruturadas com probabilidade

Então o caminho é outro: um resumo curto que alimenta o Claude Code e que também registra as regras de COMO o seu código chama o Jev

Bora montar?

O que você precisa antes de escrever o documento de contexto?

Primeiro, o projeto aberto no terminal com o Claude Code rodando

Depois, a skill oficial da TypeSafe instalada, que são dois comandos no terminal:

claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai

E vale ter na cabeça os dois sistemas de memória do Claude Code:

• CLAUDE.md: escrito por você e carregado inteiro em toda sessão
• Auto memory (MEMORY.md): escrita pelo próprio Claude

Neste post a gente mexe só no primeiro, que é o que você controla

Um detalhe pra não criar expectativa errada: não existe configuração que transforme o Claude Code num agente movido a Jev

O Jev não substitui o LLM por trás do Claude Code. O uso é instalar a skill e pedir pro agente escrever código que chama o Jev, beleza?

Passo a passo: como montar um documento de contexto curto e reaproveitável

A ideia aqui é ter UM lugar com a explicação do projeto e o Claude Code puxando ela sozinho em toda sessão

1. Gerar a base com /init e enxugar

Numa sessão do Claude Code, roda:

/init

Ele gera um CLAUDE.md inicial do projeto

É um rascunho, não o documento final. Tu lê, corta o que é óbvio e deixa só o que alguém novo no projeto precisaria saber

O erro comum deste passo: aceitar o arquivo gerado sem cortar nada

Tudo que fica ali é carregado em TODA sessão, então cada linha sobrando vira custo de contexto fixo

2. Criar o AGENTS.md e importar no CLAUDE.md

Por que um AGENTS.md separado?

Porque a documentação de memória do Claude Code indica justamente esse padrão pra compartilhar contexto com outras ferramentas: o conteúdo mora no AGENTS.md e o CLAUDE.md só importa

No AGENTS.md entra o que vale pra qualquer pessoa no projeto: estrutura de pastas, comandos de build e teste, decisões de arquitetura, convenções de nomes e fluxos comuns

Um exemplo (os nomes e comandos são ilustrativos, troca pelos do seu projeto):

# AGENTS.md

## Estrutura de pastas
- src/api: rotas e handlers
- src/core: regras de negócio
- src/decisoes: código que monta o state e chama o Jev
- tests: testes automatizados

## Comandos
- Build: npm run build
- Testes: npm test

## Decisões de arquitetura
- src/core não importa nada de src/api
- Toda chamada externa passa por um módulo próprio

## Convenções de nomes
- Arquivos em kebab-case
- Funções de decisão começam com decide

## Fluxos comuns
- Nova rota: handler em src/api, regra em src/core, teste em tests

Aí o CLAUDE.md (em ./CLAUDE.md ou ./.claude/CLAUDE.md) fica assim:

@AGENTS.md

O @caminho é relativo ao arquivo que importa, então se o seu CLAUDE.md estiver dentro de .claude/, ajusta o caminho

O erro comum deste passo: duplicar o conteúdo nos dois arquivos

Aí tu edita um, esquece o outro e o agente recebe duas versões diferentes da mesma regra… e isso é pedir pra dar ruim

3. Escrever a seção ‘Integração com o Jev’ como decisões

Aqui mora o pulo do gato

O Jev não vai ler essa seção. Quem lê é o Claude Code, na hora de escrever o código que chama o Jev

Então nada de explicar o que é o Jev em três parágrafos: escreve DECISÕES que o agente consegue seguir

Antes, uma parada rápida: que perguntas tipadas são essas?

São três tipos documentados:

• Choice: escolhe entre opções nomeadas
• Score: usa uma rubrica ordenada e devolve uma nota ponderada
• Noul: sim ou não, devolve a probabilidade de ser verdade entre 0 e 1

Com isso, a seção fica mais ou menos assim:

## Integração com o Jev
- O Jev é chamado pelo nosso código, nunca é o modelo do agente
- Todo ponto de decisão usa um tipo de pergunta: Choice, Score ou Noul
- O state é filtrado no código antes do envio: só os campos que a pergunta precisa
- Limite por requisição: 64.000 tokens no total (state + todas as perguntas)
- Limite de 32.000 tokens para o state + a pergunta mais longa
- O Jev não devolve explicação: o código decide pela resposta tipada e pela probabilidade

Se ainda tá na dúvida sobre onde o Jev rende de verdade, vale resolver isso antes de espalhar ponto de decisão pelo projeto

O erro comum deste passo: tratar o Jev como chat ou esperar explicação dele

Ele não produz cadeia de raciocínio, explicação nem texto livre. Se o seu código depende de um ‘porque’ vindo do Jev, a arquitetura tá errada desde o início

4. Forçar a skill quando a tarefa envolver o Jev

O Claude Code carrega a skill da TypeSafe sozinho quando a tarefa parece relacionada

Mas quando tu quer garantir, dá pra forçar com o comando:

/typesafe:typesafe-ai

Ou escrevendo no prompt:

use the TypeSafe skill e crie a função decideReembolso com uma pergunta Noul

A skill entrega pro agente o contrato atual da API, os três tipos de pergunta e os padrões de design da TypeSafe

O erro comum deste passo: copiar o contrato da API pro documento de contexto

A skill já traz isso, e com o contrato atual. A cópia no seu arquivo só envelhece e ainda come contexto em toda sessão

5. Revisar o tamanho com /memory

De tempos em tempos, roda:

/memory

Ele abre os arquivos de memória pra edição

A meta da documentação oficial é ficar abaixo de 200 linhas por arquivo, porque arquivo maior consome mais contexto e reduz a aderência às instruções

Tome cuidado: isso é recomendação, não limite rígido. Passar disso não quebra nada, só piora o resultado aos pouquinhos

O erro comum deste passo: deixar o arquivo crescer a cada sessão

Cada ‘ah, deixa eu anotar isso aqui também’ parece inofensivo… até o documento virar um livro que ninguém revisa

O que deixar fora do documento para ele não virar outro consumidor de contexto

Essa é a parte que MAIS faz diferença

Um documento de contexto Claude Code que tenta guardar tudo acaba virando exatamente o problema que ele devia resolver

Resumo rápido do que sai e pra onde vai:

Instruções longas de uma área: .claude/rules/

Regra extensa que só importa pra uma parte do código (testes, migrations, uma pasta específica) não precisa estar no arquivo principal

Ela vai pra .claude/rules/ com escopo de caminho e só carrega quando o Claude trabalha com os arquivos correspondentes

Preferências pessoais: CLAUDE.local.md ou ~/.claude/CLAUDE.md

O seu jeito de gostar das coisas não é regra do projeto

O que é só seu vai pro CLAUDE.local.md (pessoal, no projeto) ou pro ~/.claude/CLAUDE.md (vale pro seu usuário em qualquer projeto)

Contrato da API da TypeSafe: já vem pela skill

Endpoint, formato de requisição, os três tipos de pergunta e os padrões de design: tudo isso a skill já entrega

No seu documento fica só o que é decisão SUA, tipo qual tipo de pergunta cada ponto do sistema usa

Detalhe de tarefa pontual: vai no prompt

Como uma tela específica deve ficar, qual bug corrigir hoje, qual campo novo criar… nada disso é contexto permanente

Vai no prompt da tarefa. Se for tela, dá pra descrever uma tela no prompt sem precisar de arquivo de design

Por que o documento de projeto não serve como state do Jev?

É tentador pensar: ‘já tenho o AGENTS.md prontinho, manda ele de state e pronto’

Não manda haha

Na API nativa, o state pode ser string ou texto estruturado (um registro JSON, por exemplo). Mas a orientação das docs de modelos da TypeSafe é clara: o state deve ter a evidência relevante pra pergunta, não toda informação que a aplicação tem

E o motivo é bem prático:

• Contexto irrelevante pode reduzir a precisão da resposta
• State menor é mais fácil de revisar
• Tem menos risco de vazar dado pessoal ou confidencial que nem tinha a ver com a pergunta
• Deixa o conjunto de avaliação mais estável

Ou seja: estrutura de pastas e comando de build não ajudam o Jev a decidir se um pedido de reembolso é legítimo 😛

O filtro acontece no código, e é exatamente isso que a seção de decisões do passo 3 manda o agente fazer

Próximo passo: escreva seu documento de contexto e teste na próxima sessão

Recapitulando:

Um AGENTS.md enxuto, importado no CLAUDE.md com @AGENTS.md, acaba com a repetição de explicação no Claude Code

A seção de decisões sobre o Jev faz o agente escrever código que filtra o state do jeito certo, sem tratar o Jev como chat

E o que é longo, pessoal ou pontual fica fora, cada um no seu lugar

O próximo passo é concreto:

1. Roda /init no seu projeto
2. Corta até ficar abaixo de 200 linhas
3. Instala a skill da TypeSafe com os dois comandos
4. Pede pro agente o primeiro ponto de decisão com uma pergunta Noul

Na sessão seguinte, repara quanta coisa tu deixou de explicar de novo =)

Até o próximo post!