Como dar contexto de negócio ao Claude Code

Pedes uma aplicação para organizar pedidos. O agente cria uma lista, um botão para aceitar e um calendário. Parece fazer sentido. Só depois percebes que, na tua operação, aceitar um orçamento ainda não permite reservar uma data. Falta confirmar outra condição que nunca explicaste.

A diferença está numa regra pequena, mas o resultado muda bastante. Um ecrã pode estar bem construído e representar mal o teu negócio. Por isso, antes de discutires cores ou funcionalidades, precisas de conseguir explicar quando um pedido muda de estado e quem tem autoridade para o fazer.

Este guia trabalha essa passagem com uma oficina fictícia de restauro de móveis. Os exemplos servem para aprender; não descrevem um cliente, uma aplicação implementada ou resultados obtidos. O método parte das aulas de Claude Code (vibe coding) do Laboratório: conhecer o processo, preservar decisões e conferir o que foi realmente feito.

Que contexto de negócio faz diferença numa tarefa concreta?

O contexto útil explica decisões que o agente não consegue retirar apenas do código. Inclui o objetivo comercial, o percurso atual, as regras de passagem entre etapas e as exceções relevantes. Seleciona o que influencia a tarefa em curso, com exemplos suficientes para distinguir uma interpretação correta de uma suposição plausível.

Na oficina do nosso exemplo, os pedidos chegam por um formulário existente. A equipa recebe fotografias, verifica se trabalha aquele tipo de peça e decide se precisa de uma avaliação presencial. Só depois prepara um orçamento. A pessoa pode aceitar a proposta, mas a reserva na agenda depende também da confirmação de um sinal.

Esta descrição já permite perceber várias coisas. Receber fotografias não equivale a aceitar o trabalho. O valor do orçamento não nasce de uma resposta automática. A agenda representa capacidade de execução, não apenas interesse comercial. Cada distinção evita um comportamento errado na aplicação que vais construir.

Começa por escolher a alteração. Neste caso, queremos um painel interno que mostre pedidos a aguardar informação e propostas aceites ainda sem sinal confirmado. Não precisamos de construir uma loja, substituir a faturação ou enviar mensagens aos clientes. Delimitar a tarefa ajuda a escolher o contexto necessário.

Pede ao agente que identifique onde o projeto atual já representa estas etapas. Pode existir um campo adequado, uma integração funcional ou um relatório que resolva parte do problema. Quando explicas o negócio sem mostrar o que existe, aumentas a probabilidade de receber uma solução paralela que depois tens de conciliar.

Se ainda estás a decidir o que construir, começa pelo briefing de uma aplicação com IA. Aqui vamos mais longe numa parte específica: fazer com que as decisões de negócio continuem disponíveis e sejam interpretadas corretamente durante o desenvolvimento.

Escolhe também quem esclarece cada dúvida. A pessoa que conhece o atendimento pode explicar os pedidos incompletos; a responsável pela oficina confirma a capacidade e as reservas. Uma resposta dada por quem não decide aquele assunto deve ficar identificada como informação por confirmar, por mais convincente que pareça.

Como transformar palavras habituais em definições utilizáveis?

Define os termos que mudam contagens, estados ou ações. Para cada palavra importante, escreve o significado no teu negócio, a condição que a torna verdadeira e um caso que fica de fora. Este pequeno glossário permite descobrir diferenças de interpretação antes de essas diferenças aparecerem num relatório ou numa automatização.

Pensa na palavra «aceite». Para quem atende, pode significar que o cliente respondeu favoravelmente. Para quem organiza a produção, pode querer dizer que a peça já tem uma data reservada. Se o painel usar a mesma palavra para ambas as situações, a equipa continuará a precisar de perguntar o que cada linha significa.

No exemplo, adotamos «proposta aceite» quando existe uma aceitação registada pelo cliente e «reserva confirmada» quando há também confirmação do sinal e disponibilidade validada. São escolhas fictícias para este exercício. Na tua empresa, deves usar as condições reais, mesmo que sejam diferentes ou exijam mais etapas.

O glossário pode começar com quatro entradas:

Acrescenta a origem de cada condição. A aceitação pode ser registada manualmente pela equipa, enquanto o sinal vem de uma conferência administrativa. Se a aplicação não tiver acesso a essa conferência, o agente precisa de saber que não pode inferir pagamento a partir de uma mensagem otimista.

Define igualmente as ausências. Um campo vazio pode significar «ainda não verificado», e isso é diferente de «não pago». Se juntares estes dois estados, o painel pode levar a equipa a contactar alguém que já pagou, apenas porque a confirmação ainda não foi registada.

Termina com uma pergunta de controlo: duas pessoas classificariam o mesmo pedido da mesma forma usando apenas estas definições? Se a resposta depender de explicações adicionais, acrescenta essas condições ao documento. O objetivo é reduzir a interpretação escondida, não criar uma lista extensa de termos que ninguém consulta.

Como separar factos, hipóteses e decisões em falta?

Marca a situação de cada informação antes de a entregar ao agente. Um facto confirmado tem uma fonte identificada; uma hipótese precisa de teste; uma decisão em falta exige uma escolha. Manter estas categorias visíveis impede que uma sugestão inicial se transforme, sem discussão, numa regra permanente da aplicação.

Imagina que alguém diz: «Normalmente, conseguimos tratar de três peças por semana.» Isso pode ser uma observação aproximada, depender do tipo de restauro ou referir apenas uma pessoa da equipa. Não chega para a aplicação passar a aceitar três reservas em qualquer semana do ano.

Regista a frase como hipótese e pergunta que casos a alteram. Uma cadeira com uma intervenção simples e uma cómoda com trabalho estrutural não consomem necessariamente a mesma capacidade. A informação necessária poderá ser uma estimativa por tipo de trabalho, validada pela oficina, em vez de um limite fixo por quantidade.

No documento, usa formulações que mostrem essa diferença. «Confirmado pela responsável: nenhuma data é reservada antes da conferência do sinal.» «Hipótese a testar: o painel deve ordenar primeiro os pedidos mais antigos.» «Por decidir: quem pode alterar uma reserva já confirmada?» Cada frase conduz a uma ação diferente.

A fonte também tem de ser adequada à pergunta. Uma página pública explica a oferta ao cliente, mas pode não conter o procedimento interno. Um procedimento antigo pode mostrar a origem de uma regra sem provar que continua em vigor. Indica a data e a pessoa responsável pela confirmação, sem expor dados desnecessários.

Quando encontrares duas versões incompatíveis, não peças ao agente que escolha a mais convincente. Expõe a contradição: um documento exige sinal, outro fala apenas em aceitação. A tarefa é identificar qual se aplica agora e atualizar a referência usada pelo projeto. A linguagem mais recente, por si só, não confirma a decisão.

Podes avançar nas partes independentes enquanto resolves essa dúvida. O painel pode ser desenhado com dados fictícios e os campos já acordados. A regra controversa fica pendente, sem ser escondida numa escolha técnica que mais tarde pareça ter sido aprovada por toda a equipa.

Onde guardar o contexto para não o repetir em cada conversa?

Guarda as orientações permanentes perto do projeto e mantém os detalhes do negócio em documentos identificáveis. O ficheiro de instruções deve indicar as regras essenciais e onde consultar o restante contexto. O pedido atual acrescenta o objetivo imediato, os exemplos relevantes e a forma de verificar a alteração que estás a pedir.

Em Claude Code, o ficheiro `CLAUDE.md` serve para instruções persistentes do projeto. A documentação oficial distingue essas instruções das notas de memória automática e recomenda conteúdo específico, conciso e coerente. Podes confirmar os ficheiros carregados através de `/context`, na área de memória. Consulta a documentação sobre memória e instruções para o comportamento da versão que utilizas.

Uma organização possível para a oficina seria ter um documento com o percurso dos pedidos, outro com definições e um registo de decisões. São nomes e separações sugeridos para este exemplo, sem obrigação de criar muitos ficheiros. Se três páginas simples resolverem o problema, não precisas de uma estrutura maior.

No `CLAUDE.md`, bastaria explicar a finalidade do projeto, identificar os documentos relevantes e fixar restrições que afetam trabalho recorrente. Por exemplo: manter o formulário atual, preservar as definições aprovadas e conferir os casos de aceitação antes de alterar o painel. O histórico completo de todas as conversas ficaria fora desse resumo.

Há uma diferença entre indicar um caminho para consulta e importar um documento. A sintaxe de importação com `@` carrega o conteúdo referenciado no contexto; não reduz o seu tamanho. Evita importar tudo por hábito. Seleciona o que precisa de estar disponível e pede a leitura dos detalhes específicos quando a tarefa o justificar.

O estado do trabalho também merece um lugar próprio. «Protótipo criado com dados fictícios» não deve aparecer como «painel operacional». Regista o que existe, o que foi verificado e o próximo passo. Assim, numa nova conversa, o agente tem uma descrição que pode comparar com os ficheiros reais.

Se ainda não organizaste a pasta e o primeiro ciclo de trabalho, segue o guia para começar um projeto com Claude Code. Ter contexto escrito ajuda, mas continua a ser necessário confirmar que estás no projeto certo e que as referências correspondem à versão atual.

Como formular um pedido que usa esse contexto?

Liga o pedido a uma decisão de negócio, identifica as fontes a consultar e descreve o resultado observável. Inclui as condições que devem permanecer iguais e os casos que a alteração precisa de tratar. Pede esclarecimento apenas sobre dúvidas que afetem a execução, para conseguires avançar sem voltar a discutir decisões já fechadas.

Um pedido para o nosso painel poderia ser: «Lê o percurso dos pedidos e o glossário aprovados. Acrescenta uma vista das propostas aceites cujo sinal ainda não está confirmado. Usa os dados fictícios desta pasta e mantém o formulário existente. Mostra separadamente os casos sem informação e os casos verificados como não pagos.»

Completa com o critério de conferência: «Uma proposta aceite sem conferência administrativa deve aparecer como confirmação em falta. Uma proposta com sinal confirmado deixa de aparecer nesta vista. A alteração não deve mudar reservas nem contactar clientes. Testa os exemplos indicados e mostra o resultado no painel.»

Este pedido não obriga a escrever código. Obriga-te a saber o que queres observar. Também deixa margem ao agente para encontrar a implementação adequada no projeto existente, sem lhe pedir que tome decisões comerciais ou invente uma fonte de informação que ainda não existe.

Antes da implementação, pede uma leitura breve das consequências: que definições vai usar, que ficheiros precisa de alterar e que dúvida impediria a validação. Se a resposta disser que vai criar um sistema de pagamentos, tens um sinal imediato de que o âmbito foi interpretado de forma errada.

Evita acrescentar cinco funcionalidades enquanto o primeiro resultado ainda está por conferir. Podes guardar novas ideias, mas mantém o pedido atual reconhecível. Quando cada correção altera também o objetivo, deixa de ser claro se a falha veio da interpretação inicial ou de uma decisão nova introduzida a meio.

A recomendação de dar critérios observáveis ao agente aparece nas boas práticas oficiais de Claude Code. A adaptação ao negócio é tua: em vez de pedir apenas um painel bonito, defines que pedidos devem aparecer, porquê e qual a diferença esperada quando os dados mudam.

Como conferir se o agente compreendeu as regras?

Usa casos pequenos com uma resposta esperada definida antes da execução. Inclui um caso normal, um caso incompleto e uma exceção que poderia levar a uma decisão errada. A explicação do agente ajuda a descobrir interpretações, mas a confirmação exige observar o comportamento produzido com esses mesmos dados de teste.

Prepara três pedidos fictícios. No primeiro, a proposta foi aceite e não há informação sobre o sinal. No segundo, a aceitação e o sinal estão confirmados, mas falta validar disponibilidade. No terceiro, todas as condições estão confirmadas. Não precisas de nomes, contactos ou pagamentos reais para testar esta distinção.

Escreve o esperado para cada caso. O primeiro precisa de conferência administrativa. O segundo não pode ter uma reserva confirmada só porque existe pagamento. O terceiro pode cumprir as condições para reserva, mas continua a ser necessário respeitar quem tem autorização para a efetuar no processo que definiste.

Repara no segundo caso: ele impede uma simplificação excessiva. Uma regra formulada apenas como «com sinal, reservar» continuaria errada quando não existe capacidade. Testar serve também para melhorares a tua própria explicação, não apenas para descobrires erros do agente.

Pede que o resultado mostre a razão da classificação. «Aguarda disponibilidade» permite conferir a condição em falta. Um rótulo genérico como «pendente» pode juntar situações que exigem intervenções diferentes. A informação útil para a equipa deve acompanhar a forma como o painel organiza o trabalho.

Depois altera um único dado e repete. Confirma o sinal no primeiro caso, mantendo a disponibilidade desconhecida. O resultado deve mudar apenas no que essa informação permite. Este teste ajuda a detetar regras que dependem de coincidências nos exemplos, como considerar qualquer pedido atualizado pronto para entrar na agenda.

Guarda os casos junto da decisão que verificam. Se alguém mudar a política de reservas, já sabes que exemplos precisam de revisão. Mantém a distinção entre um ensaio com dados fictícios e a validação da integração real: o primeiro prova a lógica testada, mas não demonstra que o sistema recebe corretamente a confirmação administrativa.

Que limites devem acompanhar o contexto do negócio?

Explica o que o agente pode alterar, que dados pode consultar e que efeitos externos estão autorizados. Estas condições devem corresponder à tarefa e às ferramentas disponíveis. Instruções escritas ajudam a orientar o trabalho, mas os acessos e as permissões precisam de ser configurados no ambiente onde o agente executa ações.

Na fase de protótipo da oficina, podemos autorizar alterações locais e testes com exemplos fictícios. Publicar o painel, alterar a agenda real ou enviar mensagens são operações diferentes. Se uma delas já estiver autorizada, regista o âmbito dessa autorização para evitar perguntas repetidas; se não estiver, não a deduzas do pedido de desenho.

A documentação de permissões de Claude Code distingue regras aplicadas pelo cliente das instruções presentes num pedido ou num `CLAUDE.md`. Uma frase sobre o negócio não concede nem revoga acesso técnico. Confere as permissões efetivas antes de ligares serviços que possam produzir alterações reais.

O contexto deve também limitar os dados usados. Para desenvolver a lógica do painel, bastam identificadores fictícios e estados relevantes. Não é necessário entregar toda a correspondência de um cliente, fotografias privadas da sua casa ou credenciais de acesso. Escolhe apenas a informação indispensável ao comportamento que estás a testar.

Quando precisares de consultar um serviço real, identifica a operação necessária. Ler o estado de um pedido é diferente de atualizar esse estado. Ter uma integração disponível não significa que todas as ações possíveis sejam adequadas ao trabalho atual. Esta distinção deve ficar clara tanto na instrução como na configuração.

Se o teu projeto inclui automatizações, este raciocínio continua no guia para desenhar uma automação antes de abrir o n8n. As regras comerciais precisam de acompanhar o percurso dos dados e os efeitos de cada etapa, independentemente da ferramenta escolhida para executar o processo.

Como manter o contexto correto quando o negócio muda?

Revê os documentos quando uma decisão operacional muda e associa cada alteração aos exemplos que a verificam. Guarda a data, o motivo e o impacto da decisão, retirando instruções incompatíveis da versão atual. Numa retoma, compara o estado escrito com o projeto existente antes de pedir ao agente que continue a construir.

Imagina que a oficina passa a admitir reservas provisórias durante um período definido. Essa mudança afeta o glossário, a apresentação do calendário e os casos de teste. Acrescentar uma frase à conversa não chega: as instruções anteriores continuam a dizer que só existem reservas depois de todas as confirmações.

Regista a nova decisão com o responsável e a condição exata. Depois identifica o que fica por implementar. O documento pode refletir a política aprovada enquanto a aplicação ainda usa a regra antiga; esse intervalo tem de estar visível para ninguém assumir que a atualização já chegou ao trabalho diário.

Numa nova sessão, pede ao agente que leia esse registo, confira a implementação e diga qual a próxima alteração necessária. Se o estado escrito estiver desatualizado, corrige-o com base no que verificaste. A memória de uma conversa anterior não substitui essa comparação.

No fim, o teu contexto deve permitir responder a três perguntas simples: o que significa cada estado, que evidência permite mudá-lo e quem pode executar essa mudança. Quando estas respostas estão claras, tens uma base concreta para pedir novas funcionalidades, rever o resultado e continuar o projeto sem reconstruir todas as decisões do início.

Como podes aprender a aplicar isto no Laboratório da IA?

No Laboratório da IA, podes aprender a trabalhar com Claude Code e outros agentes a partir de projetos concretos, relacionando contexto, planeamento, construção e revisão. As aulas semanais e os Zooms de acompanhamento semanais permitem aprofundar o método e trazer dúvidas sobre a aplicação ao teu próprio trabalho.

Começa por escolher uma regra que a tua equipa explica frequentemente e escreve dois casos que a distinguem. Esse exercício dá-te matéria concreta para evoluir o projeto com os conteúdos, replays e materiais do Lab. Podes conhecer o Laboratório da IA e ver o que está incluído no acesso.