hustyladislav/escrita-para-agentes

Referência para escrever qualquer documento consumido por um agente: uma skill, um AGENTS.md / CLAUDE.md, um documento alcançado por um ponteiro. A embalagem difere; a escrita não: as mesmas alavancas tornam cada um previsível, já que o agente adota o mesmo processo em cada execução, em vez de produzir a mesma saída.

Quando o documento que você está escrevendo é uma skill, leia SKILL-MECHANICS.md para frontmatter, escolha de invocação e skills roteadoras.

Ponteiros de contexto

Um ponteiro de contexto é uma referência mantida no contexto do agente que nomeia algum material fora do contexto e codifica a condição para alcançá-lo. A descrição de uma skill é um exemplo; uma linha em AGENTS.md nomeando um documento é o mesmo objeto. A redação do ponteiro, não seu alvo, decide quando o agente alcança o material, e quão confiavelmente. Um alvo obrigatório atrás de um ponteiro mal redigido é um bug de variância: primeiro refine a redação, e incorpore o material no documento principal apenas se o refinamento falhar.

Um ponteiro faz dois trabalhos: declarar o que é o material e listar os ramos que devem acionar seu acesso (um ramo é um caso distinto que o documento trata, então execuções diferentes percorrem caminhos diferentes). Cada palavra de um ponteiro sempre carregado custa em cada turno, portanto ele merece uma poda ainda mais rigorosa que o corpo:

• Coloque a palavra principal na frente: o ponteiro é onde ocorre o trabalho de acionamento.
• Um gatilho por ramo. Sinônimos que renomeiam um único ramo são um ramo escrito duas vezes; mescle-os e mantenha apenas ramos genuinamente distintos.
• Corte a identidade que o corpo já carrega.

As duas cargas

Cada documento e ponteiro que você adiciona gasta um de dois orçamentos:

• Carga de contexto é o custo do material sempre carregado na janela do agente: uma linha em AGENTS.md, uma descrição de skill, qualquer coisa sentada no contexto a cada turno, gastando tokens e atenção, quer dispare ou não.
• Carga cognitiva é o custo para o humano: quais documentos existem e quando recorrer a cada um. O humano é o índice. Não é um custo a minimizar: é o preço da agência humana; gaste-o onde o julgamento humano importa, remova-o onde não importa.

Material alcançado apenas através de um ponteiro escapa da carga de contexto ao custo da linha do próprio ponteiro; material sem nenhum ponteiro depende inteiramente da carga cognitiva.

Hierarquia da informação

Um documento é construído a partir de dois tipos de conteúdo: passos (as ações ordenadas que o agente executa) e referência (definições, regras, fatos consultados sob demanda). Os dois se misturam livremente: todos os passos (uma receita), toda referência (as regras de uma revisão, esta skill), ou ambos. A decisão central é onde cada peça se situa na hierarquia da informação, uma escada classificada pelo quão imediatamente o agente precisa do material:

1. Passo no arquivo é o nível primário: o que o agente faz, em ordem.
2. Referência no arquivo é consultada sob demanda. Frequentemente um conjunto legítimo de pares no mesmo nível (cada regra de uma revisão em um degrau), o que é um arranjo adequado, não um sinal de problema.
3. Referência divulgada é empurrada para um arquivo separado, alcançado por um ponteiro de contexto, carregado apenas quando o ponteiro dispara. Abrange desde um arquivo irmão na mesma pasta até referência totalmente externa que vive em qualquer lugar e qualquer documento pode apontar.

Empurrar material para baixo de menos infla o topo; empurrar demais esconde material que o agente realmente precisa. Essa tensão é toda a decisão.

Divulgação progressiva é o movimento para baixo na escada (para fora do arquivo principal e atrás de um ponteiro) para que o topo permaneça legível. Não é primariamente uma otimização de tokens: é como a hierarquia é protegida. A ramificação é o teste de divulgação mais limpo: incorpore o que cada ramo precisa e coloque atrás de um ponteiro o que apenas alguns ramos alcançam. Quando um documento tem passos, a referência no arquivo que deveria ser divulgada os enterra e torna a atenção a eles uma questão de sorte: uma alavanca de variância, não apenas uma de legibilidade.

Co-localização é o companheiro dentro do arquivo: onde a escada decide quão abaixo uma peça se senta, a co-localização decide o que se senta ao lado dela uma vez lá. Mantenha a definição, as regras e as ressalvas de um conceito sob um mesmo título, em vez de espalhadas, para que ler uma parte traga suas vizinhas junto. O teste: o documento deve ser lido como documentação escrita para o agente. Material agrupado lê-se assim; material espalhado não. (Distinto da duplicação: esta repete um significado em dois lugares; o espalhamento fragmenta um significado em muitos lugares.)

Espalhamento é o modo de falha aqui: um documento simplesmente longo demais, mesmo quando cada linha é viva e única. A atenção se dilui no excesso, e cada linha extra é mais uma para manter relevante. A cura é a escada: divulgue a referência atrás de ponteiros e divida por ramo ou sequência para que cada caminho carregue apenas o que precisa.

Passos e critérios de conclusão

Cada passo termina em um critério de conclusão, a condição que diz ao agente que o trabalho está feito. Duas propriedades o tornam uma alavanca:

• Clareza: o agente consegue distinguir feito de não feito? Um limite vago ("entendimento alcançado") convida à conclusão prematura: encerrar o passo antes de estar genuinamente concluído, com a atenção escorregando para estar concluído. Os passos visíveis ainda à frente (os passos pós-conclusão) fornecem a atração; a clareza do critério é a resistência. Defenda em ordem: primeiro refine o limite (local e barato); só se ele for irremediavelmente difuso e você observar a pressa, esconda os passos posteriores dividindo a sequência. Esconder só funciona através de uma fronteira de contexto real (uma transferência ou um despacho de subagente; uma chamada embutida deixa os passos posteriores no contexto e não limpa nada).
• Exigência: o quanto ele requer. "Cada modelo modificado contabilizado" força um trabalho minucioso onde "produzir uma lista de alterações" não força. A exigência impulsiona o trabalho de base (a investigação que o agente faz dentro do trabalho, latente na redação em vez de escrita como seu próprio passo), e não está limitada ao passo: "cada regra aplicada" vincula um corpo de referência plana da mesma forma que "cada passo concluído" vincula uma sequência, que é como um documento de pura referência ainda carrega uma barra de exaustividade.

Os critérios mais fortes são verificáveis e exaustivos.

Quando dividir

Dividir um documento em dois gasta uma das duas cargas, portanto divida apenas quando o corte o justificar:

• Por sequência: divida uma sequência de passos onde os passos pós-conclusão tentam o agente a apressar o passo anterior. Mantê-los fora de vista impulsiona mais trabalho de base na tarefa atual. Cuidado com o inverso: mesclar sequências expõe cada passo aos passos posteriores do que se segue, convidando à conclusão prematura.
• Por invocação, específico de skill: veja SKILL-MECHANICS.md.

Palavras principais

Uma palavra principal é um conceito compacto já existente no pré-treinamento do modelo com o qual o agente pensa ao executar o documento (lição, névoa da guerra, balas traçadoras). Repetida como um token, nunca como uma frase, ela acumula uma definição distribuída e ancora toda uma região de comportamento no menor número de tokens, recrutando conhecimentos prévios que o modelo já possui. Criar a sua própria funciona se você a definir claramente, mas uma palavra inventada não recruta conhecimentos prévios: você paga em tokens de definição o que uma palavra pré-treinada dá de graça; recorra primeiro a uma palavra existente.

Ela ancora duas vezes. No corpo, execução: o agente busca o mesmo comportamento toda vez que a palavra aparece, e dentro da referência plana ela foca a atenção em uma classe de coisa a procurar. Em um ponteiro, invocação: quando a mesma palavra vive em seus prompts, seus documentos e seu código, o agente liga essa linguagem compartilhada ao material e o alcança mais confiavelmente.

Caça oportunidades para refatorar com palavras principais. Uma tríade escrita em três lugares, um ponteiro gastando uma frase para apontar para uma ideia. Cada uma é uma passagem implorando para ser colapsada em um único token:

• "rápido, determinístico, baixa sobrecarga" → enxuto (um loop enxuto).
• "um loop em que você acredita" → vermelho, transformando um portal difuso em um estado binário observável (o loop fica vermelho no bug, ou não).

Você ganha duas vezes: menos tokens e um gancho mais afiado para o agente pendurar seu pensamento. Presuma que todo documento carrega reiterações que palavras principais aposentam. Vá encontrá-las.

Negação é o modo de falha ao lado desta alavanca: orientar por proibição arrasta o comportamento proibido para o contexto e o torna mais disponível, não menos. Não pense em um elefante, e o elefante é tudo o que existe; a negação é um modificador fraco que o conceito fortemente ativado sobrepuja, então a proibição meio que se lê como uma instrução para fazer a coisa. Solicite o positivo: declare o comportamento alvo ("escreva comentários de uma linha") para que o proibido nunca seja mencionado. Uma proibição merece seu lugar apenas como uma barreira de proteção rígida que você não consegue expressar positivamente; mesmo assim, emparelhe-a com o alvo positivo para que a atenção se fixe no que fazer.

Poda

• Mantenha cada significado em uma fonte única de verdade: um lugar autoritativo, para que mudar o comportamento seja uma edição em um lugar. Duplicação (o mesmo significado em mais de um lugar) custa manutenção e tokens, e infla a proeminência de um significado na escada além de seu posto real. (O inverso acidental de uma palavra principal, que repete um token de propósito, nunca o significado.)
• O ambiente também é uma fonte de verdade (scripts package.json, arquivos de configuração, a estrutura de diretórios, saída --help), e um documento que o reitera é um cache: uma cópia de uma consulta, que merece sua carga apenas quando a consulta é cara. Armazene em cache o que o agente não consegue encontrar olhando: a convenção não escrita, a razão por trás de uma escolha, a pegadinha que nenhuma configuração confessa. Deixe as consultas de um arquivo, um comando para o ambiente, onde elas não podem ficar desatualizadas.
• Verifique cada linha quanto à relevância: ela ainda diz respeito ao que o documento faz? Uma linha perde relevância por nunca dizer respeito à tarefa (mera exposição, ou um ramo que deveria ser divulgado) ou por ficar obsoleta à medida que o comportamento ou o mundo que descreve muda. Documentos mais curtos são mais fáceis de manter relevantes. Sem uma disciplina de poda, o destino padrão é o sedimento: camadas obsoletas que se depositam porque adicionar parece seguro e remover parece arriscado, até que você precise cavar através delas para encontrar o que ainda está vivo.
• Caça no-ops frase por frase: uma instrução que o modelo já obedece por padrão paga carga para não dizer nada. O teste (isso muda o comportamento versus o padrão?) é relativo ao modelo, não ao leitor: duas pessoas discordando sobre um no-op discordam sobre o padrão e resolvem executando o documento, não debatendo. Quando uma frase falha, delete a frase inteira em vez de cortar palavras dela. O teste também classifica palavras principais: uma palavra muito fraca para vencer o padrão (seja minucioso quando o agente já é mais ou menos minucioso) é um no-op, e a correção é uma palavra mais forte (implacável), não uma técnica diferente.