Escrevendo para agentes
O leitor de qualquer coisa que você escrever com este skill é um agente que tem apenas o texto. Ele não viu a conversa, não pode perguntar o que você quis dizer e agirá com base no que as palavras dizem, literalmente e com esforço total. A maioria das falhas vem da lacuna entre o que você sabe e o que foi parar na página. Portanto, trabalhe a partir da posição do leitor: antes de escrever, defina onde o trabalho termina, em que situação o leitor está e de que material ele precisa; então escreva em palavras que o leitor possa usar sem você.
Dois tipos de entrada
Um pedido bruto ("escreva um briefing para que um agente corrija o teste de login instável"): colete os fatos da conversa e do workspace, depois rascunhe do zero.
Um prompt existente: mantenha-o. Faça o menor conjunto de edições que corrija o que está realmente errado, mantenha sua estrutura e redação onde funcionam e não adicione nenhum requisito que seu autor não tenha declarado. Uma reescrita completa esconde qual mudança importou e descarta silenciosamente a intenção que o autor tinha. Os padrões abaixo ainda se aplicam: se o prompt não tiver uma frase de papel, um exemplo ou uma verificação final, adicione-os. Sempre que você adicionar algo, seja um desses ou uma regra que feche uma lacuna real, liste-o ao entregar.
Se um fato que apenas o usuário conhece mudaria o que o leitor entrega ou o que ele pode fazer, pergunte antes de escrever: algumas perguntas no máximo, cada uma com sua resposta recomendada. Caso contrário, escolha um padrão sensato e liste-o como uma suposição.
Antes de escrever
Onde o trabalho termina
Declare o objetivo, por que ele importa (quem usa o resultado e para quê), o que conta como concluído e o que deve ser devolvido. Descreva o destino, não a rota: dê o resultado, os critérios de sucesso e as restrições, e deixe o leitor escolher o caminho. Os modelos atuais planejam melhor do que uma sequência que você prescreve, e uma etapa que você adivinhou errado ainda será executada. Liste etapas apenas onde a ordem em si é um requisito, como uma migração que deve ser executada antes de uma implantação.
Antes: 1. Abra refresh.ts. 2. Envolva refresh() em try/catch. 3. Tente novamente três vezes. 4. Execute os testes.
Depois: Quando uma sessão expirar, o cliente deve renovar o token silenciosamente para que o usuário permaneça logado. Concluído quando o novo caso de timeout em tests/auth/refresh.test.ts passar e nenhum teste existente falhar. Mantenha a API pública de AuthClient inalterada, porque três outros pacotes a chamam.
Transforme adjetivos de qualidade em barreiras que o leitor possa aplicar. "Completo", "conciso" e "apenas os importantes" são aplicados literal e imprevisivelmente: um revisor instruído a relatar apenas problemas importantes encontrará os menores e ficará em silêncio sobre eles. Nomeie o limite, ou nomeie o que manter e o que cortar. Se uma etapa posterior filtrar os resultados, peça tudo.
Antes: Revise cuidadosamente e relate apenas problemas importantes.
Depois: Relate todos os problemas que encontrar, incluindo aqueles dos quais não tem certeza, e marque cada um como "quebra comportamento" ou "apenas estilo". Uma etapa posterior faz a filtragem.
Em que situação o leitor está
Quando o texto atribui uma tarefa (um briefing, prompt de sistema, issue, plano ou handoff), comece com uma frase de papel: quem é o leitor, sua função nesta tarefa e a situação em que se encontra. "Você é o revisor de código para este pull request, que você não escreveu; a equipe planeja mesclá-lo hoje." O papel define a perspectiva do leitor e pelo que ele é responsável. Descrições de uma ferramenta ou skill não têm papel; elas dizem o que a coisa faz e quando usá-la.
Em seguida, diga ao leitor o que ele não pode ver de onde está: se alguém pode responder perguntas durante a tarefa ou se ela é executada sem supervisão; quem mais trabalha nos mesmos arquivos ou sistemas; se suas alterações são revisadas ou reversíveis; se ele deve avaliar ou alterar coisas; e o que ele pode fazer sem perguntar, incluindo se ele pode delegar ainda mais. Nomeie as situações específicas que justificam parar para relatar. "Pergunte se não tiver certeza" deixa o leitor adivinhando, e ele acaba perguntando sobre tudo ou nada.
Você opera sem supervisão; ninguém pode responder perguntas até você terminar. Pare e relate apenas se a correção excluir dados ou tocar em código fora de src/auth/. Outro agente está editando docs/ ao mesmo tempo, então deixe esse diretório em paz e não reverta alterações que você não fez.
De que material o leitor precisa
Para cada fonte, dê sua localização e o que extrair dela. Aponte para o que o leitor pode abrir por si mesmo (caminhos de arquivo, comandos, URLs que ele pode acessar) em vez de parafrasear, para que leia a coisa real. Escreva por extenso tudo que existe apenas em seu contexto: decisões tomadas na conversa, as próprias palavras do usuário sobre um requisito, resultados de comandos que você executou, abordagens já descartadas e por quê.
Antes: Veja docs/ e nossa discussão anterior.
Depois: Leia a seção "Reembolsos" de docs/billing.md para a regra de arredondamento. Um requisito não está em nenhum arquivo; as palavras do usuário foram: "reembolsos parciais nunca devem exceder o valor original da cobrança, mesmo após conversão de moeda".
Ao incluir logs, texto do usuário ou saída de outro agente, coloque-os em um bloco claramente marcado e diga que é material para trabalhar, não instruções. Mantenha suas próprias instruções fora de tais blocos, porque texto entre aspas ou blocos de dados é comumente tratado como conteúdo sem autoridade.
Escrevendo
Use as palavras do leitor, não as suas. Enquanto trabalhava, você cunhou rótulos ("opção B", "o caminho preguiçoso", "o problema P2") e abreviações ("→ contenção de bloqueio") que não significam nada para o leitor. Substitua cada um pelo que representa, defina termos técnicos reais uma vez e escreva como se estivesse explicando do zero. Ao descrever trabalho realizado anteriormente, diga quem o fez, para que o leitor não acredite que realizou essas ações por conta própria.
Antes: Opção B descartada (→ contenção de bloqueio); continuar com lazy-init, cuidado com a armadilha P2.
Depois: A sessão anterior descartou a reconstrução do pool de conexões a cada requisição: sob carga, a latência p95 subiu de 80 ms para 400 ms devido à contenção de bloqueio. A abordagem atual cria o pool no primeiro uso. Um problema conhecido permanece: ...
Dê a cada regra sua razão em uma oração ("…porque um script analisa este campo"). A razão permite que o leitor lide com casos que você não listou e mostra até onde a regra se estende. Pule-a apenas quando qualquer modelo capaz já souber o motivo ou o contexto o tornar óbvio.
Declare cada regra uma vez, no lugar a que pertence. A repetição não adiciona peso; faz o leitor aplicar a regra em excesso (linhas repetidas de "pergunte primeiro" transformam-se em paradas em etapas seguras), e as cópias divergem ao longo das edições. Pelo mesmo motivo, use uma linguagem simples: sem maiúsculas, IMPORTANTE ou pressão como "isso é crítico" ou "não seja preguiçoso". Mantenha palavras absolutas como 'nunca' e 'sempre' para invariantes reais, como limites de segurança e ações irreversíveis.
Não prescreva como pensar. Deixe de fora "pense passo a passo" e solicitações para escrever o raciocínio na resposta ou em tags; os modelos atuais raciocinam por conta própria, e alguns recusam solicitações para transcrever seu raciocínio. Se você precisar ver o porquê, peça uma breve explicação ou a evidência de suporte, como referências de arquivo:linha ou saída de comando.
Ao corrigir uma falha conhecida, escreva o princípio por trás dela com sua razão, não uma proibição do único caso que você viu. Uma lista de proibições cobre apenas o que lista; um princípio cobre os casos vizinhos também.
Antes: Não use Object.create(). Não use proto.
Depois: Prefira composição explícita à manipulação de protótipos, porque revisores aqui favorecem código que se lê de cima para baixo.
Escreva em parágrafos. Use listas apenas para itens que são verdadeiramente paralelos ou sequenciais: campos, etapas ordenadas, verificações independentes. Marcadores removem os 'porque' e 'a menos que' que conectam instruções, e os leitores tendem a espelhar o formato que recebem.
Inclua um exemplo curto do que o leitor deve produzir, marcado como exemplo; ele transmite forma, tom e nível de detalhe melhor do que um parágrafo de descrição. Omita-o apenas quando a saída esperada for inequívoca apenas pelas palavras, como um único comando para executar.
Termine um texto de atribuição de tarefa com uma verificação que o leitor executa antes de relatar a conclusão: o comando ou teste que prova o resultado quando um existe, caso contrário, os critérios de conclusão para revisitar. Peça que ele declare claramente qualquer coisa que não pôde verificar.
Entregar
Entregue o texto finalizado, pronto para colar ou já escrito em seu arquivo, no idioma do prompt existente ou naquele que o usuário solicitar. Fora dele, liste em algumas linhas as suposições que você fez e que o usuário pode querer alterar. Mantenha suas anotações de design fora do texto em si.
Antes de entregar, leia o rascunho como o leitor o faria: capaz, mas tendo apenas esta página. Onde quer que ele tivesse que adivinhar o que você quis dizer, corrija a página.