Barncore/prompting-agents

Promptando agentes

O leitor é um modelo capaz, sem nenhum do seu contexto. Diga o que deve ser verdade ao final e por que, e deixe-o planejar o caminho: uma rota escrita para um trabalho que o modelo pode planejar é seguida fielmente, incluindo os passos errados. A embalagem difere — resumo, transferência, skill — a escrita, não.

O núcleo

O que colocar. O teste da linha: o leitor poderia derivar isso da tarefa e de seu treinamento? Fatos que ele não pode consultar, as convenções do usuário, contratos, restrições rígidas e critérios de conclusão falham no teste e permanecem. Rotas para trabalho planejável passam e vão embora. Uma lista de verificação de critérios é um estado final; uma lista de verificação de passos é uma rota.

Autocontido. Uma sessão nova lê apenas o prompt e o disco. Cada mensagem carrega o conjunto completo de regras vigentes com as alterações aplicadas no local — nunca "como antes, mais estas alterações" — e cada documento reafirma cada regra vigente da qual depende, nunca "como no pai".

O porquê, declarado positivamente. O modelo generaliza a partir de razões, então cada regra carrega a sua própria ("uma linha contínua por parágrafo, porque a caixa de chat trata uma quebra de linha como intencional"). Declare o comportamento alvo; uma proibição arrasta o comportamento proibido para o contexto e o torna mais disponível, portanto mantenha uma apenas como uma barreira de segurança rígida, emparelhada com o alvo positivo. Linguagem de pressão (DEVE, CRÍTICO, caixa alta) aciona excessivamente em modelos atuais; escreva "use X quando…".

Palavras-chave, um lugar, sem no-ops. Uma palavra que o modelo já possui (recibos, névoa da guerra, ciclo apertado) supera uma frase; o termo do próprio usuário supera ambos. Cada significado vive em um lugar. Uma frase que o leitor obedece por padrão paga custo para não dizer nada: delete a frase, não palavras dela.

Anatomia do prompt

1. Intenção — o objetivo maior, a quem serve, o que a saída permite; o modelo a gasta nas microdecisões que o prompt nunca alcança.
2. Estado final — o que existe quando terminado, com quais propriedades, e o que o usuário pode fazer agora. Verificável e exaustivo: "cada arquivo modificado contabilizado" força trabalho que "produza uma lista de alterações" não força. O formato da entrega vive aqui; é uma propriedade, não um procedimento.
3. Restrições rígidas — os invioláveis: fontes somente leitura, orçamentos, terminologia, proveniência. As restrições declaradas pelo usuário, como declaradas — nunca seus próprios padrões de economia.
4. Pontos de verificação — o único lugar onde a prescrição ainda pertence: quando pausar para o humano (uma ação destrutiva ou irreversível, uma mudança real de escopo, entrada que só eles possuem) e o que está fora do escopo.
5. Cláusula de liberdade — licença para reestruturar e contestar. Em ambiguidade, tome decisões rotineiras e declare a suposição; pergunte quando a resposta puder evitar um problema posterior, como leituras que levam a trabalho materialmente diferente ou uma escolha cara de desfazer. O usuário acolhe essas perguntas. Em uma execução não supervisionada, a pergunta se torna uma regra com um padrão seguro aplicado, e o trabalho continua.
6. Comprovações — em todo resumo: antes de relatar conclusão, audite cada afirmação contra um artefato desta sessão e diga claramente o que não foi verificado; isso quase elimina relatórios de status inventados.

Passos ordenados ganham um lugar onde a ordem importa (uma migração, um protocolo de segurança) ou onde um passo pulado é a falha; lá, uma lista de verificação que o leitor copia e marca supera a prosa.

Antes de enviar

Algum procedimento numerado poderia se tornar uma frase de estado final? Cada linha restante é uma restrição, ponto de verificação, regra de verificação ou especificação de entrega? Alguma frase permite que o leitor pare, desacelere ou reduza o escopo por um motivo que o usuário não declarou? O leitor precisaria ter estado nesta conversa para agir com base nela?

Ramificações

• Mensagem única para um leitor que você pode modelar (despacho de subagente, prompt para outra sessão, transferência, mensagem para uma IA externa) → references/briefs.md
• Resumo para uma execução não supervisionada, seus memorandos de ponto de verificação e decisões, sequenciamento sob uma janela de fechamento → references/autonomous-runs.md
• Documento durável (skill, CLAUDE.md, documento de referência) e quando entregar uma construção de skill ao skill-creator da Anthropic → references/skills-and-docs.md
• Escolher o modelo ou nível de esforço do leitor, ou escrever para Haiku ou Fable em vez de Opus → references/models.md