Começa pelo negócio e pelo resultado esperado
Explica o que o projeto faz, para quem existe e que resultado deve preservar. Esta abertura dá significado às instruções seguintes e ajuda a avaliar alterações propostas pelo agente. Usa informação concreta do negócio, evitando uma apresentação extensa da empresa que não muda a forma de executar o trabalho em causa.
Num exemplo hipotético, um portal interno pode existir para a equipa preparar propostas e obter aprovação antes de as enviar. Essa finalidade orienta permissões, estados e notificações. Escrever apenas que se trata de uma aplicação moderna com IA não explica quem a utiliza nem o que tem de acontecer para cumprir o objetivo.
Acrescenta o âmbito e o que ficou excluído. Se o portal não recebe pagamentos e não dá acesso aos clientes nesta fase, regista essas decisões. O agente pode sugerir evoluções, mas a documentação deve distinguir a necessidade atual de funcionalidades que pareceriam interessantes num produto mais amplo.
A preparação do plano antes de desenvolver uma aplicação fornece o conteúdo de base. O ficheiro de instruções não precisa de repetir todo o plano: pode resumir os pontos estáveis e indicar onde consultar requisitos detalhados. Assim, orienta a execução sem criar duas descrições extensas que serão difíceis de manter coerentes.
Para preparar o próximo passo, consulta Desenvolver aplicações com IA.
Escreve limites que possam ser aplicados a uma tarefa
Transforma preferências e restrições em instruções suficientemente concretas para orientar uma escolha. Indica que ações exigem aprovação e quais as decisões que não devem ser reabertas sem motivo. Uma regra útil permite perceber o que o agente deve fazer numa situação real, em vez de apenas declarar uma intenção genérica de qualidade.
No meu projeto, registar o uso de português de Portugal e a distinção entre sugestões do assistente e decisões confirmadas ajuda a orientar a colaboração. São instruções que continuam relevantes quando muda a tarefa. Não é necessário reconstruir a conversa em que cada uma surgiu para perceber como devem ser aplicadas.
Num projeto de negócio, podes precisar de explicitar que preparar uma mensagem não autoriza enviá-la ou que alterar condições comerciais exige decisão do responsável. A redação deve dizer qual é o limite e a quem cabe decidir. Evita frases vagas que deixam o agente escolher sozinho o que considera demasiado importante para executar.
Estas regras escritas precisam de corresponder aos acessos e controlos da aplicação. Um documento que proíbe consultar certos dados não substitui limitar esse acesso tecnicamente. Guarda nas instruções o comportamento esperado e as referências necessárias, mantendo credenciais e informação confidencial fora dos documentos que circulam com o projeto.
Regista decisões estáveis e aponta para o detalhe
Conserva no ficheiro as decisões que continuam a condicionar trabalho futuro e remete o detalhe para documentos próprios. Uma escolha de idioma, aprovação ou identidade visual pode merecer presença permanente; o resultado de uma execução específica pode ficar no histórico. O critério é a utilidade para orientar a próxima tarefa relevante.
Se a empresa usa uma determinada identidade visual, indica a referência aprovada e onde estão os materiais originais. Não basta pedir um aspeto consistente sem mostrar com o que deve ser consistente. Também não precisas de incorporar todas as imagens e cada discussão de design dentro do documento principal para preservar essa decisão.
A forma de selecionar contexto para a IA ajuda a escolher o nível de detalhe. Uma regra curta pode apontar para uma especificação extensa, desde que a referência seja clara e acessível. O agente deve conseguir saber quando precisa de consultar esse detalhe e que documento representa a decisão em vigor.
Explica o motivo quando ele evita uma interpretação errada. Por exemplo, preservar um endereço antigo porque ainda é usado em materiais distribuídos é uma restrição diferente de manter todos os endereços por hábito. O contexto da decisão ajuda a avaliar uma futura alteração sem converter a regra numa proibição sem sentido.
Inclui a forma de trabalhar e de verificar
Indica como encontrar o projeto, executar as verificações pertinentes e apresentar os resultados de uma alteração. Adapta o detalhe à equipa e ao ambiente real, mantendo instruções que alguém consiga confirmar. O objetivo é tornar o trabalho verificável, sem confundir uma lista de testes sugeridos com evidência de que esses testes foram executados.
Num projeto de software, pode fazer sentido apontar para os comandos de validação existentes e explicar que alterações exigem testes de permissões ou revisão de interface. Se não sabes quais são os comandos, pede ao agente que os identifique no projeto e confirme antes de os registar. Copiar uma lista genérica pode criar instruções impossíveis de cumprir.
Define também como deve ser descrita a conclusão: o que mudou, o que foi verificado e que limitação permanece. Distingue uma pré-visualização local de uma versão colocada online e uma ação tentada de uma ação confirmada. Estes detalhes tornam o estado compreensível para a pessoa que vai decidir o próximo passo.
A preparação da primeira sessão de trabalho ajuda a identificar referências de ambiente e acesso que merecem ficar documentadas. Guarda onde encontrar informação e quem a pode disponibilizar, sem copiar segredos. A instrução deve facilitar trabalho autorizado e permitir reconhecer quando falta uma condição necessária para o realizar.
Mantém uma referência principal e confirma a leitura
Escolhe uma fonte principal para as instruções do projeto e mantém coerentes os ficheiros usados pelas diferentes ferramentas. Confirma o comportamento de leitura no ambiente instalado, em vez de assumir equivalência entre nomes. Revê as regras quando mudam decisões ou processos, retirando contradições da versão ativa e preservando o histórico onde for útil.
CLAUDE.md e AGENTS.md são nomes usados em contextos de instruções para agentes, mas não deves concluir que todos os produtos os carregam da mesma maneira. Localização, configuração e suporte podem variar. Antes de depender de uma regra, confirma que o agente recebeu o documento relevante e compreendeu como se aplica à tarefa.
Se manténs versões para ferramentas diferentes, evita editá-las independentemente sem uma referência comum. Uma mudança de aprovação num ficheiro e a regra antiga noutro pode produzir comportamentos incompatíveis no mesmo projeto. A forma técnica de partilhar instruções deve ser escolhida e testada para o ambiente utilizado, sem pressupor compatibilidade automática.
Por fim, lê o documento como alguém que acabou de chegar ao projeto. Deve ser possível perceber o objetivo, os limites, as decisões em vigor e onde verificar o trabalho. Quando o ficheiro passa a exigir a leitura de toda a história para descobrir essas respostas, é altura de o reorganizar e devolver o detalhe aos registos próprios.