Documentación pensada para agentes en paquetes npm
El 7 de marzo publiqué en el subreddit de Codex una pregunta sobre si ya existen prácticas consolidadas para explicar a los agentes cómo debe usarse un paquete, ya sea en Maven, Composer, npm u otros entornos parecidos.
No hubo respuestas de fondo. Al menos a mí me quedó la impresión de que todavía no existe una práctica común en este terreno. Así que terminé armando mi propio enfoque junto con GPT.
Como experimento, organicé para @teqfw/di una interfaz compacta para agentes en forma de
ai/AGENTS.md y varios archivos breves, cada uno centrado en un tema. La idea es sencilla:
README.md queda para las personas, mientras que AGENTS.md y los documentos
cercanos le dan al agente una visión concentrada de cómo se usa el paquete.
Hilo original en Reddit: Agent-friendly documentation for npm packages. Resultado del experimento en el repositorio: teqfw/di: ai/AGENTS.md.
Al final, la documentación de di quedó en seis archivos y 4,164K tokens en total, incluido el
AGENTS.md índice. Podría haberse quedado en un único documento, pero la dividí por temas a
propósito para que el agente lea el contexto paso a paso.
Por ahora me parece un patrón que funciona: un archivo de entrada pequeño, luego una ruta de lectura guiada y, solo después, el detalle más fino. Seguiré viendo qué tan estable resulta este enfoque en la práctica.