panbergco/agent-cli-writer

Escritor de CLI para agentes

Un agente busca el comando, no el manual. Una regla que vive solo en un documento se sigue cuando el agente la lee. Las mediciones detrás de esto están en references/evidence.md.

La regla: cada regla de la herramienta es declarada por la herramienta, en el momento en que se aplica. Lo que imprime, lo que rechaza y lo que facilita son el manual.

Lo que un agente hace con una herramienta

• Busca el comando primero; abre el manual solo cuando no está seguro, y a menudo está seguro y equivocado.
• Lee para confirmar un plan ya hecho: busca sintaxis, no reglas.
• Olvida todo entre sesiones y aprende la herramienta de nuevo cada vez.
• Envía varias llamadas a la vez.
• Paga de nuevo por cada carácter que la herramienta imprimió, en cada solicitud posterior.
• No puede esperar de forma barata: consulta o espera, y cada consulta es una solicitud paga.
• Hace lo que dice la respuesta que tiene delante, de manera más confiable que lo que un documento dijo antes.

Método

Doce verificaciones, cada una con cómo verificarla. tool es un comando inventado.

1. Enseñar en el punto de uso. La respuesta de un comando dice lo que cuesta la ruta recién tomada, y nombra la mejor ruta.

   $ tool machine new
   created m-41 (se detiene sola en 60 min)
   nota: el trabajo iniciado a mano en esta máquina no guarda registro de ejecución.
         para un trabajo que necesites seguir: tool job start --from <dir> -- <cmd>
   

   Verificar: cada verbo con un uso incorrecto conocido lo dice en su propia salida.
2. Un rechazo es una lección. Decir qué se rechazó, por qué, y el comando exacto siguiente con los argumentos del llamante ya completados. Dar cada problema en una sola respuesta. Nunca salir con código distinto de cero sin palabras. Un error de uso imprime la forma correcta de ese único subcomando.

   tool: rechazado: `job wait j-7` detendría este turno hasta 40 min.
         siguiente: tool job show j-7          (cómo está ahora)
                    tool job start … --notify  (que te avisen cuando termine)
   

   Verificar: ninguna ruta de salida sin un mensaje; cada rechazo lleva un siguiente:.
3. Llevar el manual dentro de la herramienta. tool rules imprime las reglas de funcionamiento completas, terminando con un código de versión. Los verbos que un agente maneja manualmente rechazan a un llamante no interactivo que no haya establecido el código actual (TOOL_RULES=<código>), en una línea. Los verbos que son la interfaz de la máquina permanecen abiertos. El código cambia cuando las reglas cambian. Verificar: un agente nuevo al que solo se le da el nombre del comando tiene las reglas en su contexto antes de su primera llamada que crea, cambia o elimina algo.
4. Hacer que el camino correcto sea el camino fácil. Antes de escribir "prefiere X", haz que X haga todo el trabajo: tomar la entrada que los agentes realmente tienen, devolver de inmediato, mantener un registro. Los agentes evitan un comando recomendado que bloquea, pierde el historial o no puede tomar su entrada. Indicar consecuencias, no preferencias: "Y no guarda registro" funciona donde "prefiere X" no. Verificar: por cada "prefiere" en la documentación, nombrar lo que el camino evitado ofrece que al preferido le falta, y cerrar esa brecha.
5. Un comando responde "¿dónde estoy y por qué?". tool status, en pocas líneas: qué es mío, qué está en ejecución, cómo terminó lo último y por qué, qué hacer a continuación. Que los agentes lean directamente el almacenamiento o registros de la herramienta significa que a status le falta un hecho. Verificar: contar esas lecturas en transcripciones reales; las tres preguntas más comunes deben estar en status.
6. Trabajo largo: iniciar, devolver, informar. Aproximadamente más de un minuto: start devuelve un identificador de inmediato; show <handle> da la línea de tiempo, código de salida y últimas líneas, incluso después de que el trabajador haya desaparecido o el llamante haya muerto; el final se entrega al llamante con resultado y razón. Un mensaje califica solo cuando lleva algo nuevo sobre lo que el agente pueda actuar ahora: ningún "continúa" periódico. Verificar: nada bloquea más de 60 segundos por defecto; cada trabajo tiene un registro y un aviso de finalización con resultado, razón y siguiente paso.
7. Imprimir poco. La salida por defecto cabe en una pantalla: aproximadamente 40 líneas o 2,000 caracteres. Más va a un archivo cuya ruta se imprime, o detrás de --full. Sin pancartas, sin animación de progreso; instrucciones permanentes una vez por sesión. La salida que se corta lo dice y dice dónde está el resto. Verificar: medir los caracteres devueltos por comando durante una semana real y dar un presupuesto a los tres totales más grandes.
8. Dos lectores: una persona y un programa. Texto en una terminal. Si se canaliza, o con --json: solo líneas JSON, nombres de campo estables, un resumen final. El código de salida es el resultado: 0 para hecho, y códigos separados para rechazado, uso incorrecto, tiempo de espera agotado, nunca ejecutado. Diagnósticos en la salida de error estándar. Verificar: tool <verbo> | cat se analiza; --help lista cada código de salida.
9. Seguro de repetir, seguro de inmediato. Ejecutar un comando dos veces no hace la cosa dos veces, o dice que ya se hizo. Dos llamadas en el mismo momento de un mismo agente no pierden las escrituras del otro: bloquear, o rechazar la segunda con palabras. Los verbos destructivos necesitan un flag explícito y ofrecen --dry-run. Verificar: una prueba ejecuta cada verbo de escritura dos veces a la vez.
10. Acotar y dejar un registro. Límites de tiempo por defecto; lo que la herramienta crea caduca por sí solo; list muestra los sobrantes; cleanup elimina lo que este llamante hizo; el costo de una cosa es un comando. Cada acción se registra con quién, cuándo y la compilación de la herramienta; tool version la nombra. Verificar: matar al llamante a mitad de ejecución; nada se ejecuta sin límite, y el registro dice lo que pasó.
11. Un nombre para una cosa. El mismo sustantivo en el comando, su salida, sus errores y su documentación; un verbo para una acción a través de los sustantivos. Los flags desconocidos y argumentos extra se rechazan, nunca se ignoran. Verificar: listar los sustantivos que la herramienta imprime; cada concepto tiene exactamente uno.
12. Los secretos se quedan fuera. Nunca en una línea de comando, nunca en eco, nunca en un registro: desde un archivo, entrada estándar o el entorno, enmascarados en la salida.

Escribir el manual de la herramienta

El manual explica; la herramienta impone. Nada vinculante vive solo en él.

• Descripción: qué hace la herramienta y cuándo cargarla, en las palabras que una tarea usaría, nombrando los verbos.
• Orden: las reglas vinculantes primero, cada una con su consecuencia; luego una tabla breve de objetivo y comando; luego fallos y qué hacer.
• Tamaño: como máximo 150 líneas, ninguna línea de más de 100 caracteres. Los agentes imprimen archivos con líneas largas cortadas y pierden el final de cada fila de tabla ancha.
• Tablas: nada vinculante dentro de una celda de tabla.

Probarlo en un agente nuevo

Una sesión nueva que nunca ha visto la herramienta ni su manual, recibe una tarea real y el nombre del comando:

1. Registrar cada llamada, su salida y su código de salida.
2. Contar: búsquedas de ayuda, llamadas fallidas, repeticiones de una llamada fallida, consultas, lecturas directas de almacenamiento o registros, caracteres devueltos.
3. Cada conteo superior a cero es un defecto de la herramienta, no del agente. Corregir el mensaje o la ruta, luego ejecutar de nuevo en otra sesión nueva.
4. Ejecutar una vez más con el manual cargado: nada puede empeorar, y el manual no puede contradecir a la herramienta.

Terminado cuando un agente nuevo completa la tarea sin búsqueda de ayuda, sin llamada fallida de la que tuviera que adivinar la salida, sin consulta ni lectura directa de almacenamiento.

Modos de fallo

Regla solo en manual (la herramienta nunca la indica) · Fallo mudo (salida distinta de cero, sin palabras) · Por qué sin siguiente (una razón y ningún comando) · Descarga de ayuda completa · Preferido pero peor (la ruta recomendada carece de lo que la otra tiene) · Brecha de estado (los agentes leen el almacenamiento) · Bloqueador (un comando detiene el turno) · Fastidio (un mensaje periódico sin nada nuevo) · Aviso de ir a mirar (dice que algo pasó, no qué) · Muro de texto · Corte silencioso · Escritura perdida (dos llamadas a la vez, un resultado) · Dos nombres · Sobrantes (nada caduca).