Como criar instruções de projeto que um agente consegue seguir

Uma conversa pode começar bem e perder precisão quando o projeto cresce. O agente volta a sugerir uma tecnologia rejeitada, altera uma decisão aprovada ou considera concluído um trabalho que só foi testado localmente. As instruções de projeto ajudam-te a manter essas decisões disponíveis nas tarefas seguintes.

O trabalho começa por escolher o que merece ficar escrito. Um ficheiro útil permite ao agente perceber o projeto e agir com critérios claros. Também permite a outra pessoa rever o resultado. Neste guia vais preparar uma versão curta, testá-la e corrigir as ambiguidades que aparecerem.

Que informação deve ficar nas instruções permanentes?

Guarda as regras e decisões que continuam válidas entre tarefas: finalidade do projeto, localização da informação, convenções, serviços existentes e critérios de qualidade. Reserva o pedido da conversa para a alteração atual. Assim, evitas misturar o funcionamento permanente do projeto com uma lista de trabalho que ficará desatualizada rapidamente.

Imagina que tens uma página de serviços e queres acrescentar uma secção de perguntas frequentes. A identidade visual, o destino dos contactos e a língua são regras permanentes. As perguntas concretas que vais acrescentar pertencem ao pedido atual ou ao ficheiro de conteúdo dessa secção.

Escreve o que o agente não consegue deduzir com segurança. Pode descobrir que o projeto usa determinada biblioteca ao ler o código. Não consegue saber, sem contexto, que o cliente aprovou um texto e pediu para o preservar. Essa decisão merece ficar registada com o seu motivo.

Evita copiar toda a história do projeto. Uma conversa antiga pode conter hipóteses rejeitadas, alternativas e instruções que já foram substituídas. Se a colocares inteira no ficheiro, aumentas a possibilidade de uma decisão ultrapassada voltar a parecer válida. Regista a decisão atual e referencia o histórico quando ele for necessário.

A preparação fica mais simples depois de escreveres um briefing para a aplicação que vais construir com IA. O briefing define a necessidade. As instruções explicam como trabalhar no projeto respeitando o que já foi decidido.

Como transformas uma preferência numa regra verificável?

Escreve o comportamento esperado e a evidência que permite conferi-lo. Troca palavras vagas, como simples ou profissional, por escolhas observáveis no teu contexto. Quando uma regra admite exceções, explica quais são. Uma boa instrução reduz a necessidade de adivinhar sem impedir o agente de resolver os detalhes que lhe delegaste.

«Mantém o site organizado» deixa demasiado por definir. Podes escrever: «Os textos da página vivem nos ficheiros de conteúdo existentes; antes de criar um novo local, verifica a organização atual». A regra liga a intenção a uma ação concreta e permite rever a alteração depois.

Faz o mesmo com a qualidade visual. «Tem bom aspeto no telemóvel» pode tornar-se: «Confere a página numa largura de telemóvel; o texto deve ser legível, os botões utilizáveis e não deve existir deslocamento horizontal inesperado». Acrescenta a largura ou os dispositivos relevantes se já os definiste para o projeto.

Se uma exceção for frequente, documenta-a. Por exemplo, uma ligação de suporte pode ter um destino diferente do botão de compra. Uma regra que diga apenas «todos os botões vão para o checkout» entra em conflito com essa necessidade. Especifica o tipo de botão a que te referes.

Também podes pedir ao agente que reveja as instruções antes de trabalhar: «Identifica regras ambíguas e diz qual a interpretação que seguirias». Lê a resposta. Se a interpretação difere da tua intenção, corrige o ficheiro antes de acrescentares funcionalidades dependentes dessa regra.

Como defines os limites de autonomia do agente?

Descreve quais as ações autorizadas na tarefa e quais dependem de uma decisão adicional. Distingue leitura, edição local, publicação e efeitos em serviços externos. Preserva autorizações já dadas para o mesmo âmbito. Quando uma ação muda dados reais ou afeta outras pessoas, a regra deve indicar concretamente o limite aplicável.

Na preparação de uma página, podes autorizar a edição e a validação local, deixando a publicação para depois de reveres o resultado. Noutro projeto, podes autorizar desde logo a publicação após os testes definidos. São formas diferentes de trabalhar; as instruções devem refletir a que escolheste.

Evita uma regra que obrigue a pedir autorização para cada operação pequena e reversível. Isso pode impedir o agente de concluir o trabalho que já lhe entregaste. Define antes os pontos que mudam o impacto: publicar, enviar uma mensagem, alterar acessos, modificar pagamentos ou substituir dados de produção.

No conteúdo do Laboratório sobre planeamento com Claude Code, o método inclui inspecionar o projeto, preservar decisões e distinguir trabalho local de publicação. A adaptação editorial usada aqui acrescenta uma regra prática: se a publicação já está autorizada para a tarefa, não há motivo para repetir a pergunta por rotina.

As instruções escritas devem ser acompanhadas pelos controlos reais das ferramentas. Um texto a dizer «não acedas a esta conta» não substitui permissões adequadas. Dá ao agente apenas o acesso necessário para a fase em que está a trabalhar e mantém segredos fora dos ficheiros de instruções partilhados.

Que estrutura podes usar num primeiro ficheiro?

Começa por um ficheiro curto com finalidade, decisões preservadas, localização dos materiais, forma de trabalhar e validação. Usa exemplos do teu projeto para tornar as regras específicas. Não preenchas secções com obrigações que ainda não decidiste. Assinala as dúvidas que realmente impedem a tarefa atual e resolve-as antes de avançar.

Este exemplo é editorial e destina-se a uma página de serviços fictícia. Adapta os detalhes à tua realidade, em vez de o copiares como se servisse para qualquer aplicação.

Finalidade: ajudar o visitante a perceber o serviço e pedir uma conversa. Preserva a oferta e os textos aprovados. O contacto usa o destino já configurado no projeto. Escreve em português de Portugal e trata o leitor por tu. Antes de editar, consulta a organização atual dos conteúdos e dos componentes.

Podes acrescentar o bloco operacional:

Trabalha apenas na secção pedida e nas dependências necessárias para a fazer funcionar. Mantém as alterações alheias à tarefa. Confere o resultado em desktop e telemóvel, testa as ligações afetadas e comunica o que foi verificado. Nesta fase, prepara a alteração localmente; a publicação depende da autorização definida no pedido.

Repara no último ponto: a autorização tem de ser a verdadeira, não uma frase automática que contraria o trabalho acordado. Se já autorizaste publicar, ajusta o bloco. O objetivo do ficheiro é reduzir dúvidas, não introduzir bloqueios que não correspondem à tua forma de trabalhar.

Acrescenta os comandos reais de validação apenas depois de os confirmares no projeto. Não inventes um comando de testes porque aparece num modelo de instruções. Se ainda não existe, regista essa limitação e define uma verificação adequada ao tipo de alteração que vais pedir.

Onde colocas as instruções no Claude Code e no Codex?

Usa os ficheiros e as localizações documentados para a ferramenta e confirma o que foi carregado na sessão. No Codex, a referência habitual é AGENTS.md; no Claude Code, CLAUDE.md e o suporte atual de AGENTS.md têm regras próprias. A existência de um ficheiro na pasta não basta para provar que foi aplicado.

A documentação do Codex sobre AGENTS.md explica a combinação de orientação global com instruções do projeto e de diretórios mais específicos. Também descreve ficheiros de substituição e limites de carregamento. Antes de duplicares regras, verifica que ficheiros participam na tua sessão.

No Claude Code, a documentação de memória e instruções descreve CLAUDE.md e a leitura direta de AGENTS.md nas versões compatíveis. O comportamento depende da configuração e da presença de ficheiros CLAUDE.md aplicáveis. Não assumes que ambos são sempre lidos apenas porque os criaste lado a lado.

Pede ao agente que identifique os ficheiros de instruções que consultou e resuma as regras relevantes para a tarefa. Confere os caminhos. No Claude Code, a documentação também indica a consulta de contexto para verificar os ficheiros de memória carregados. Usa essa informação para detetar um arranque na pasta errada ou regras inesperadas.

Mantém uma fonte coerente para as decisões comuns. Se trabalhas com duas ferramentas, evita editar duas cópias independentes sem um processo de atualização. Antes de mudares a organização, guarda a versão anterior e verifica o comportamento em ambas. O artigo sobre Claude Code ou Codex ajuda-te a enquadrar essa escolha pelo trabalho que precisas de fazer.

Como testas se o agente está a seguir as regras?

Escolhe uma tarefa pequena que obrigue a aplicar duas ou três instruções importantes. Define antecipadamente o resultado esperado e observa as alterações produzidas. Confere os ficheiros, o comportamento e a explicação final. Uma resposta que repete as regras mostra compreensão aparente; a execução da tarefa permite avaliar se foram respeitadas.

No exemplo da página de serviços, pede para acrescentar uma pergunta frequente sem alterar a oferta. O resultado deve usar o local de conteúdo previsto, manter a língua e preservar o destino do contacto. Abre a página e testa a ligação. Compara também o que mudou no código.

Prepara um segundo caso com uma ambiguidade controlada. Podes pedir uma melhoria visual sem indicar uma nova cor, quando a paleta já está definida. Verifica se o agente respeita a identidade existente ou propõe uma mudança que precisa de decisão. A forma como trata esse caso revela se a regra está suficientemente clara.

A documentação de boas práticas do Claude Code recomenda dar formas de verificar o trabalho. Aplica essa ideia com critérios específicos do teu projeto: uma imagem esperada, uma ligação funcional, uma mensagem de erro ou um teste relevante. O critério deve mostrar utilidade, não apenas confirmar que o agente executou um comando.

Se uma verificação falhar, identifica a causa antes de acrescentares mais regras. O ficheiro pode não ter sido lido, a regra pode ser ambígua ou a implementação pode estar errada apesar de a instrução ser clara. Cada causa pede uma correção diferente. Um ficheiro maior não resolve automaticamente nenhuma delas.

Como corriges contradições e instruções desatualizadas?

Revê as regras quando uma decisão muda ou quando o mesmo erro se repete. Procura instruções que dizem coisas incompatíveis e substitui o estado antigo pelo atual. Mantém o motivo da alteração quando ele ajuda a decidir no futuro. Se precisares de preservar histórico, separa-o das regras que continuam em vigor.

Um caso comum é a publicação. O projeto começou apenas localmente, mas entretanto autorizaste colocar alterações no ar depois dos testes. Se mantiveres a proibição inicial sem indicar que foi substituída, o agente pode parar desnecessariamente. Atualiza o âmbito com uma frase inequívoca e uma data de decisão.

Outro caso é a arquitetura. Uma hipótese inicial previa guardar dados numa base de dados, mas a solução final passou a usar ficheiros. Retira instruções que mandam criar tabelas para tarefas que já não precisam delas. Preserva a razão da decisão se existir risco de a mesma proposta voltar a aparecer.

Ao reveres o ficheiro, faz três perguntas: esta regra ainda corresponde ao projeto, está no local certo e consigo verificar o seu cumprimento? Se a resposta for negativa, decide se a deves corrigir, mover ou retirar. Evita manter texto apenas porque foi escrito numa fase anterior.

Também verifica ligações para documentação e nomes de ficheiros. Uma instrução pode estar bem escrita e apontar para um local que já não existe. Quando mudares a estrutura do projeto, atualiza as referências afetadas para que a próxima sessão não comece por procurar materiais em caminhos antigos.

Como entregas contexto suficiente sem sobrecarregar a sessão?

Mantém nas instruções centrais aquilo que o agente precisa em quase todas as tarefas e indica onde consultar detalhes específicos. Organiza documentação longa por assunto. No pedido atual, identifica os materiais relevantes para a alteração. Esta seleção ajuda o agente a usar o contexto adequado sem tratar todos os ficheiros como igualmente importantes.

Para uma mudança de texto, os exemplos de voz e o ficheiro de conteúdo podem chegar. Para uma alteração de autenticação, precisas de documentação de permissões e de testes adequados. O contexto útil depende do impacto da tarefa. Não carregues documentos reservados que não contribuem para esse trabalho.

Pede uma leitura inicial delimitada: «Consulta as instruções e os ficheiros desta secção; resume o que vais preservar e indica a verificação que propões». Essa resposta permite-te detetar uma interpretação errada antes de o agente editar várias partes do projeto. Usa-a sobretudo quando a tarefa tem decisões que afetam outras áreas.

Para aprofundar esta preparação, lê como dar contexto de negócio ao Claude Code. As instruções permanentes funcionam melhor quando o agente também percebe quem usa o resultado, qual a necessidade e que decisões já estão fechadas.

O teu primeiro ficheiro fica pronto quando uma tarefa pequena é concluída respeitando as regras relevantes e quando consegues explicar a evidência dessa verificação. Depois melhora-o com base nos problemas reais que aparecerem. A utilidade está na precisão das decisões que mantém disponíveis ao longo do projeto.

Como podes aprender este método no Laboratório da IA?

No Laboratório da IA, podes trabalhar planeamento, contexto e validação em projetos com Claude Code e Codex. As aulas semanais e os Zooms de acompanhamento semanais permitem esclarecer dúvidas a partir de tarefas concretas. Traz um projeto pequeno, as decisões que queres preservar e uma alteração que consigas verificar no final.

Começa por escrever as regras que repetes com mais frequência. Testa-as numa tarefa delimitada e identifica o que ainda dá margem a interpretações erradas. Esse exercício ajuda-te a construir com mais clareza e a rever o trabalho do agente com critérios próprios.