Você pede à inteligência artificial que revise uma rotina de importação. Acrescenta as regras de negócio, explica como executar os testes, cola uma página de documentação e lembra que ela não deve gravar no banco. Na revisão seguinte, monta quase a mesma mensagem. Depois de algumas semanas, existem versões diferentes dessas orientações, e ninguém sabe qual delas continua válida.
O problema não começa na falta de um arquivo especial. Começa quando informações com funções diferentes são tratadas como se fossem uma única mensagem. Um pedido descreve o trabalho de agora; uma regra orienta o projeto; um documento fornece evidência; um procedimento organiza uma tarefa repetível. Separar essas funções ajuda tanto o leitor humano quanto o assistente que recebe o contexto.
Este artigo abre a série sobre instruções para IA, do Markdown às skills. Vamos construir essas distinções usando uma manutenção Delphi fictícia, mostrar onde cada informação pode ficar e propor um exercício de organização. Não é preciso conhecer agentes ou formatos de arquivos para acompanhar. Os exemplos são propostas didáticas, não resultados medidos de uma integração.
Quando a dificuldade é transformar uma intenção em regras e critérios verificáveis, SDD em Delphi oferece um aprofundamento em especificações, contratos e rastreabilidade. Consulte o sumário e a degustação gratuita para avaliar esse percurso. Para estudar as camadas de contexto, ferramentas e operação ao redor do modelo, a leitura complementar é IA Além da Conversa.
Antes do arquivo, identifique a função da informação
Um pedido, também chamado de prompt, é a mensagem que apresenta uma necessidade ao assistente. Nesta série, usaremos a palavra pedido quando estivermos falando da tarefa concreta. “Revise a alteração que rejeita linhas sem código do produto” é um pedido delimitado. Ele deve informar o objetivo, o material disponível e o tipo de entrega esperado.
Uma instrução estabelece como agir. Pode valer apenas para aquele pedido, como não alterar arquivos durante uma análise, ou representar uma orientação recorrente do projeto, como preservar contratos públicos. A duração e o alcance precisam ficar claros: uma exceção solicitada numa investigação não deveria se tornar silenciosamente a regra de todas as manutenções seguintes.
Uma referência é um material usado para consultar fatos, regras ou definições. Pode ser a especificação da importação, a documentação de uma biblioteca ou um exemplo aprovado. Seu conteúdo precisa ser interpretado dentro do escopo da tarefa. Uma frase imperativa citada num manual não recebe automaticamente autoridade para comandar o assistente ou liberar uma ação.
Uma skill, termo que pode ser entendido como habilidade reutilizável, reúne orientações para conduzir um tipo de trabalho. No Codex, a documentação de skills descreve um diretório com SKILL.md e recursos opcionais, como referências e scripts. Isso não a torna um novo modelo treinado: trata-se de instruções e recursos que a ferramenta disponibiliza ao assistente.
Essas quatro funções podem participar da mesma tarefa. A escolha não é entre usar somente um pedido ou somente uma skill. O pedido seleciona o trabalho, as regras delimitam o comportamento, as referências sustentam a análise e o procedimento organiza a execução. O desafio é evitar que uma dessas peças tente substituir todas as outras.
Markdown organiza o texto, mas não define sua autoridade
Markdown é uma forma de escrever documentos de texto usando marcações simples para títulos, listas, links e outros elementos. A extensão .md costuma identificar arquivos nesse formato. Você pode ler o conteúdo num editor comum e também apresentá-lo com formatação. No próximo capítulo, vamos escrever um documento completo sem pressupor familiaridade com essa sintaxe.
Salvar uma mensagem como orientacoes.md não faz com que qualquer ferramenta passe a lê-la automaticamente. É preciso conhecer o mecanismo de carregamento: o arquivo foi anexado, solicitado no pedido, recuperado por uma busca ou reconhecido por uma convenção da aplicação? Sem essa ligação, você organizou um documento, mas ainda não demonstrou que ele participa do trabalho.
No caso específico do Codex, a documentação de AGENTS.md descreve a descoberta de orientações globais e de projeto. A ferramenta combina arquivos ao longo do caminho até o diretório de trabalho, com regras próprias de precedência. Isso é comportamento documentado desse produto, não uma propriedade universal de qualquer arquivo Markdown.
Convém separar também “ser lido” de “ser cumprido corretamente”. Um documento pode entrar no contexto e ainda conter uma regra ambígua, um comando desatualizado ou uma condição impossível de verificar. A revisão precisa observar o trabalho produzido, não apenas perguntar se o assistente reconhece o nome do arquivo. O texto é uma parte do processo, não sua certificação.
Um projeto Delphi visto por quatro ângulos
Imagine um importador de pedidos em um sistema empresarial. Antes de gravar dados, ele mostra uma prévia das linhas recebidas. A mudança proposta deve rejeitar linhas cujo código do produto esteja vazio e explicar o motivo ao usuário. O exemplo é fictício: não presume uma biblioteca, um banco ou uma versão específica do Delphi.
O pedido desta manutenção deve indicar qual alteração será revisada e o resultado esperado. Em vez de “melhore a importação”, podemos solicitar uma análise do comportamento das linhas inválidas, dos casos de fronteira e dos testes disponíveis. Se a intenção é apenas revisar, é importante dizer que a entrega será um relatório, não uma implementação.
As regras permanentes do projeto pertencem a outro nível. Por exemplo: não alterar a assinatura pública do serviço sem discutir o impacto; não usar dados reais de clientes nos testes; não apresentar uma compilação como executada quando ela não ocorreu. Elas continuam relevantes em outras manutenções, embora sua redação precise acompanhar a realidade da equipe.
A referência descreve o que a importação deve fazer. Nesse exemplo, ela pode registrar quais campos são obrigatórios, como uma rejeição aparece na prévia e quando a gravação é permitida. A regra de negócio precisa ter uma fonte reconhecida e uma versão identificável. Repeti-la em vários lugares aumenta o trabalho de manter essas cópias coerentes.
O procedimento reutilizável orienta a revisão: localizar o contrato, comparar a mudança com os critérios, examinar os testes e registrar lacunas. Ele não deve inventar a regra do produto ausente. A skill explica como trabalhar com a especificação fornecida; se essa especificação não existe ou é contraditória, o resultado útil pode ser apontar a pendência, não preencher o vazio por conta própria.
Como escolher onde guardar cada parte
Figura ilustrativa gerada por IA. Síntese autoral das funções discutidas no artigo, apoiada na documentação de AGENTS.md e skills da OpenAI; não representa uma interface nem um diagrama oficial.
Uma pergunta prática é: essa informação vale somente para a tarefa atual? O identificador da alteração, o arquivo recebido e a solicitação de produzir um relatório são bons candidatos ao pedido. Guardá-los como instruções permanentes poderia levar o assistente a perseguir uma demanda antiga numa conversa nova.
Se a informação vale para muitas tarefas dentro do mesmo projeto, considere uma orientação de projeto. Isso inclui acordos de revisão e a localização dos comandos de teste, desde que sejam reais e estejam atualizados. Prefira indicar onde encontrar detalhes a copiar um manual inteiro. O arquivo principal deve ajudar a escolher o caminho relevante, não exigir tudo em toda tarefa.
Se o conteúdo explica o domínio ou comprova uma afirmação, trate-o como referência. Uma política de importação pode ser necessária numa revisão desse módulo e dispensável numa correção de legenda. Essa seleção é parte da engenharia de contexto: preparar a informação necessária ao trabalho, não simplesmente acumular texto.
Se a tarefa se repete e já possui um método razoavelmente conhecido, uma skill pode ajudar a manter o procedimento. A documentação oficial descreve acionamento explícito e seleção pela descrição da habilidade. Por isso, a descrição precisa delimitar quando usar e quando não usar. Uma rotina destinada a revisar alterações não deveria se apresentar como uma solução para todo assunto relacionado a Delphi.
Essa distribuição é uma recomendação de organização, não uma obrigação de criar quatro arquivos para qualquer pedido. Num projeto pequeno, uma mensagem bem delimitada e uma referência confiável podem bastar. O critério é reduzir ambiguidade e facilitar manutenção, não atingir uma quantidade de documentos.
Um exercício que cabe na próxima revisão
Pegue uma tarefa recente, sem dados confidenciais, e escreva cinco ou seis frases que você daria ao assistente. Não se preocupe inicialmente com formato. Depois, identifique a função de cada frase e pergunte se ela continuará verdadeira na próxima tarefa. O exercício pode ser feito manualmente; não exige instalar uma skill.
Considere este conjunto ilustrativo:
- Revise a alteração que rejeita produto sem código na prévia.
- Entregue um relatório com problema, evidência e recomendação; não altere arquivos.
- Preserve os contratos públicos do projeto.
- Consulte a especificação vigente para saber quais campos são obrigatórios.
- Compare cada critério com os testes disponíveis e informe o que não foi executado.
As duas primeiras frases formam o pedido atual. A terceira pode ser uma orientação recorrente. A quarta aponta uma referência cujo conteúdo ainda precisa ser localizado e conferido. A quinta descreve parte de um procedimento que talvez mereça virar skill se a equipe repetir esse trabalho. Nenhuma delas, isoladamente, comprova que a mudança funciona.
Ao reorganizar, confira se cada responsabilidade possui um lugar reconhecido. Se a especificação disser que espaços em branco contam como ausência, essa decisão deve ser ligada à fonte do domínio. Não deixe a interpretação escondida num exemplo de prompt, enquanto o documento principal diz apenas “vazio”. Casos aparentemente pequenos revelam onde o entendimento ainda está incompleto.
Depois, faça uma revisão humana do resultado esperado. O relatório deveria permitir localizar a evidência de uma conclusão e diferenciar um teste executado de uma sugestão de teste. Se faltou ambiente de compilação, essa limitação precisa aparecer. Um procedimento que termina com “está tudo certo” sem mostrar o que foi conferido apenas padroniza uma afirmação fraca.
O que essas peças não substituem
Uma instrução para não gravar no banco não equivale a uma permissão de acesso tecnicamente restrita. É necessário distinguir orientação textual, capacidade da ferramenta e autorização da pessoa ou organização. Se a tarefa é somente análise, oferecer acesso de escrita sem necessidade cria uma responsabilidade que o documento não elimina.
Da mesma forma, uma referência não deve ganhar autoridade porque está bem formatada. Documentos recebidos de terceiros podem conter texto que tenta alterar a tarefa. Nesta série, trataremos material consultado como fonte a analisar, não como autorização automática para executar comandos, enviar dados ou instalar componentes. O acesso precisa permanecer proporcional ao trabalho.
O artigo introdutório sobre AGENTS.md, instruções e skills apresenta esse mapa dentro de um projeto. Aqui, começamos antes da estrutura de pastas: pela classificação da informação. Os próximos capítulos vão construir os arquivos e examinar seu uso, mantendo explícita a diferença entre exemplo ilustrativo e execução comprovada.
Também não é necessário transformar toda preferência em regra. Uma instrução só deve permanecer se ainda tiver finalidade, escopo e uma forma de conferência. Quando o processo muda, revise o documento. Caso contrário, a biblioteca de orientações passa a preservar o histórico dos problemas, em vez de ajudar a equipe a resolver o trabalho presente.
Conclusão
Antes de escolher um nome de arquivo, decida a função da informação. O pedido descreve a tarefa; a instrução orienta o comportamento; a referência sustenta o entendimento; a skill organiza um procedimento repetível. Markdown pode apresentar todas essas peças, mas não decide sozinho como elas serão carregadas, interpretadas ou verificadas.
A próxima ação útil é pequena: reorganize uma revisão real, identifique as fontes das regras e defina uma entrega que mostre evidências e limitações. Quando essa dificuldade se repetir, SDD em Delphi aprofunda a ligação entre especificação, implementação e testes. A degustação permite conhecer o método antes de escolher a edição, sem confundir uma leitura complementar com garantia de qualidade.
Referências
OPENAI. Build skills. ChatGPT Learn, [s. d.]. Disponível em: https://learn.chatgpt.com/docs/build-skills. Acesso em: 4 out. 2026.
OPENAI. Custom instructions with AGENTS.md. ChatGPT Learn, [s. d.]. Disponível em: https://learn.chatgpt.com/docs/agent-configuration/agents-md. Acesso em: 4 out. 2026.
SILVEIRA, Régys Borges da. AGENTS.md, instruções e skills: como orientar uma IA dentro do projeto. regys.com.br, publicação agendada para 20 out. 2026. Disponível em: https://regys.com.br/agents-md-instrucoes-e-skills-como-orientar-uma-ia-dentro-do-projeto/. Acesso em: 4 out. 2026. Consulta ao rascunho.
SILVEIRA, Régys Borges da. Engenharia de contexto: por que um bom prompt não basta para programar com IA. regys.com.br, publicação agendada para 19 out. 2026. Disponível em: https://regys.com.br/engenharia-de-contexto-por-que-um-bom-prompt-nao-basta-para-programar-com-ia/. Acesso em: 4 out. 2026. Consulta ao rascunho.
SILVEIRA, Régys Borges da. IA Além da Conversa. Livros de Régys Borges da Silveira, [s. d.]. Disponível em: https://livros.regys.com.br/ia-alem-da-conversa. Acesso em: 4 out. 2026.
SILVEIRA, Régys Borges da. SDD em Delphi. Livros de Régys Borges da Silveira, [s. d.]. Disponível em: https://livros.regys.com.br/sdd-em-delphi. Acesso em: 4 out. 2026.
0 comentário(s)