panbergco/agent-cli-writer

Escritor de CLI para Agentes

Um agente estende a mão para o comando, não para o manual. Uma regra que vive apenas em um documento é seguida quando o agente acontece de lê-la. As medições por trás disso estão em references/evidence.md.

A regra: toda regra da ferramenta é declarada pela ferramenta, no momento em que se aplica. O que ela imprime, o que recusa e o que torna fácil são o manual.

O que um agente faz com uma ferramenta

• Estende a mão para o comando primeiro; abre o manual apenas quando está inseguro, e muitas vezes está seguro e errado.
• Lê para confirmar um plano já feito: procura por sintaxe, não por regras.
• Esquece tudo entre sessões e aprende a ferramenta novamente a cada vez.
• Envia várias chamadas de uma só vez.
• Paga novamente por cada caractere que a ferramenta imprimiu, em cada requisição posterior.
• Não consegue esperar de forma barata: faz polling ou dorme, e cada polling é uma requisição paga.
• Faz o que a resposta à sua frente diz, com mais confiabilidade do que o que um documento disse antes.

Método

Doze verificações, cada uma com como verificá-la. tool é um comando fictício.

1. Ensine no ponto de uso. A resposta para um comando diz o que o caminho recém-percorrido custa e nomeia o caminho melhor.

   $ tool machine new
   criado m-41 (para sozinho em 60 min)
   nota: trabalho iniciado manualmente nesta máquina não mantém registro de execução.
         para um trabalho que você precisa acompanhar:  tool job start --from <dir> -- <cmd>
   

   Verifique: todo verbo com um uso sabidamente errado diz isso em sua própria saída.
2. Uma recusa é uma lição. Diga o que foi recusado, por quê, e o próximo comando exato com os próprios argumentos do chamador preenchidos. Dê todos os problemas em uma única resposta. Nunca saia com código diferente de zero sem palavras. Um erro de uso imprime a forma correta daquele subcomando apenas.

   tool: recusado: `job wait j-7` reteria esta rodada por até 40 min.
         próximo:  tool job show j-7          (como está agora)
                    tool job start … --notify  (seja avisado quando terminar)
   

   Verifique: nenhum caminho de saída sem mensagem; toda recusa carrega um próximo:.
3. Carregue o manual na ferramenta. tool rules imprime as regras operacionais por completo, terminando com um código de versão. Verbos que um agente opera manualmente recusam um chamador não interativo que não tenha definido o código atual (TOOL_RULES=<código>), em uma linha. Verbos que são a interface da máquina permanecem abertos. O código muda quando as regras mudam. Verifique: um agente novo, recebendo apenas o nome do comando, tem as regras em seu contexto antes de sua primeira chamada que cria, altera ou exclui algo.
4. Torne o caminho certo o caminho fácil. Antes de escrever "prefira X", faça X fazer o trabalho completo: aceite a entrada que os agentes realmente têm, retorne imediatamente, mantenha um registro. Agentes contornam um comando recomendado que bloqueia, perde histórico ou não consegue aceitar sua entrada. Declare consequências, não preferências: "Y não mantém registro" funciona onde "prefira X" não funciona. Verifique: para cada "prefira" na documentação, nomeie o que o caminho evitado oferece que o preferido não oferece, e feche essa lacuna.
5. Um comando responde "onde estou e por quê". tool status, em poucas linhas: o que é meu, o que está em execução, como a última coisa terminou e por quê, o que fazer a seguir. Agentes lendo o armazenamento ou logs da ferramenta diretamente significa que status está faltando um fato. Verifique: conte essas leituras em transcrições reais; as três perguntas mais comuns pertencem ao status.
6. Trabalho longo: iniciar, retornar, avisar. Em cerca de um minuto: start retorna um handle imediatamente; show <handle> fornece linha do tempo, código de saída e últimas linhas, também depois que o worker se foi ou o chamador morreu; o fim é entregue ao chamador com resultado e motivo. Uma mensagem se qualifica apenas quando carrega algo novo sobre o qual o agente possa agir agora: sem "continue assim" periódico. Verifique: nada bloqueia por mais de 60 segundos por padrão; todo trabalho tem um registro e um aviso de fim com resultado, motivo e próximo passo.
7. Imprima pouco. A saída padrão cabe em uma tela: cerca de 40 linhas ou 2.000 caracteres. Mais vai para um arquivo cujo caminho é impresso, ou atrás de --full. Sem banners, sem animação de progresso; instruções permanentes uma vez por sessão. Saída que é cortada diz isso e diz onde está o resto. Verifique: meça caracteres retornados por comando durante uma semana real e dê um orçamento para os três maiores totais.
8. Dois leitores: uma pessoa e um programa. Texto em um terminal. Pipeado, ou com --json: apenas linhas JSON, nomes de campo estáveis, um resumo final. O código de saída é o resultado: 0 concluído, e códigos separados para recusado, uso incorreto, tempo limite excedido, nunca executado. Diagnósticos na saída de erro padrão. Verifique: tool <verbo> | cat analisa; --help lista todos os códigos de saída.
9. Seguro para repetir, seguro de imediato. Executar um comando duas vezes não faz a coisa duas vezes, ou diz que já foi feito. Duas chamadas simultâneas de um agente não perdem as escritas uma da outra: bloqueie, ou recuse a segunda com palavras. Verbos destrutivos precisam de uma flag explícita e oferecem --dry-run. Verifique: um teste executa todo verbo de escrita duas vezes ao mesmo tempo.
10. Limite e deixe registro. Limites de tempo padrão; o que a ferramenta cria expira por conta própria; list mostra sobras; cleanup remove o que este chamador fez; o custo de uma coisa é um comando. Toda ação é registrada com quem, quando e a versão da ferramenta; tool version a nomeia. Verifique: mate o chamador no meio da execução; nada executa sem limites, e o registro diz o que aconteceu.
11. Um nome para uma coisa. O mesmo substantivo no comando, em sua saída, em seus erros e em sua documentação; um verbo para uma ação entre substantivos. Flags desconhecidas e argumentos extras são recusados, nunca ignorados. Verifique: liste os substantivos que a ferramenta imprime; cada conceito tem exatamente um.
12. Segredos ficam de fora. Nunca na linha de comando, nunca ecoados, nunca em um registro: de um arquivo, entrada padrão ou ambiente, mascarados na saída.

Escrevendo o manual da ferramenta

O manual explica; a ferramenta impõe. Nada vinculante vive apenas nele.

• Descrição: o que a ferramenta faz e quando carregá-la, nas palavras que uma tarefa usaria, nomeando os verbos.
• Ordem: as regras vinculantes primeiro, cada uma com sua consequência; depois uma tabela curta de objetivo e comando; depois falha e o que fazer.
• Tamanho: no máximo 150 linhas, nenhuma linha com mais de 100 caracteres. Agentes imprimem arquivos com linhas longas cortadas e perdem o final de cada linha de tabela larga.
• Tabelas: nada vinculante dentro de uma célula de tabela.

Prove em um agente novo

Uma nova sessão que nunca viu a ferramenta ou seu manual, recebendo uma tarefa real e o nome do comando:

1. Registre cada chamada, sua saída e seu código de saída.
2. Conte: consultas de ajuda, chamadas com falha, repetições de uma chamada com falha, polls, leituras diretas de armazenamento ou logs, caracteres retornados.
3. Toda contagem acima de zero é um defeito da ferramenta, não do agente. Corrija a mensagem ou o caminho, então execute novamente em outra sessão nova.
4. Execute mais uma vez com o manual carregado: nada pode piorar, e o manual não pode contradizer a ferramenta.

Concluído quando um agente novo termina a tarefa sem consulta de ajuda, sem chamada com falha da qual teve que adivinhar a saída, sem poll e sem leitura direta de armazenamento.

Modos de falha

Regra apenas no manual (a ferramenta nunca a declara) · Falha muda (saída não zero, sem palavras) · Porquê sem próximo (uma razão e nenhum comando) · Despejo de ajuda inteira · Preferido mas pior (o caminho recomendado falta com o que o outro tem) · Lacuna de status (agentes leem o armazenamento) · Bloqueador (um comando retém a rodada) · Encheção (uma mensagem periódica sem nada novo) · Aviso de olhar (diz que algo aconteceu, não o quê) · Parede de texto · Corte silencioso · Escrita perdida (duas chamadas ao mesmo tempo, um resultado) · Dois nomes · Sobras (nada expira).