Mi agent.md para mejorar la calidad del código asistido por LLM
My agent.md to improve LLM-assisted code quality
Fabien Sanglard, tras una primera experiencia decepcionante con LLMs en 2025, descubrió en 2026 que con el archivo agent.md podía afinar el estilo de código generado por herramientas como Antigravity y Claude Code. Su archivo, que comparte como punto de partida, incluye reglas como evitar números mágicos, usar nombres de funciones cortos y seguir las 7 reglas para commits. Aunque mejora la calidad, advierte que no es una bala mágica: los LLMs alucinan y requieren supervisión. También aborda la dilución de contexto y sugiere mantener el contexto corto o pedir recargar agent.md.
No es una bala mágica que me permita evitar leer el código: los LLMs alucinan constantemente y no se puede confiar en ellos.
- OptionOfT
Un montón de estas cosas deberían aplicarse con linting, para que la gente que aún escribe código a mano reciba el mismo tipo de feedback, p. ej. Usar siempre {}, incluso en un "if" de una línea. Y mantener los nombres de funciones cortos. Menos de 30 caracteres.
Y esta de aquí es un patrón que crea mucho desgaste:
- Añade un comentario pequeño y conciso para explicar qué hace el bloque y por qué. Usa ejemplos cuando sea posible. Propón dibujos ASCII para explicar sistemas completos.
El qué _es_ el código.
- fergie
¿Habría alguna desventaja en simplemente tener todo lo relacionado con el estilo de código en un archivo CONTRIBUTING.md y lo de "cómo hablar conmigo" en un archivo AGENTS.md, ya que el estilo de código también aplica a contribuciones humanas? Del mismo modo, ¿no es lo de "cómo hablar conmigo" algo personal y por tanto no debería estar en un repositorio?
- andai
> - Mantener los nombres de funciones cortos. Menos de 30 caracteres.
Recientemente le pedí a GPT que portara un juego de navegador a Rust. Voluntariamente soltó esta joya:
draw_image_with_html_image_element_and_sw_and_sh_and_dx_and_dy_and_dw_and_dh(...)
Pensé que estaba fumando algo bueno, pero resultó que ese es el nombre real de la función.
https://docs.rs/web-sys/latest/web_sys/struct.CanvasRenderin...
- jurf
Eso es mucho contexto para tan poco contenido. Normalmente empiezo con algo así:
- Preferir documentación como código
- Comentar el porqué, no el qué
- Documentar APIs públicas
- La legibilidad es primordial
Eso normalmente me lleva al 80%; el resto lo cubre el linter.
Lo que más echo en falta es que explique demasiado el estado anterior, especialmente al hacer ediciones a planes, pero aún no he encontrado una buena redacción para eso.
- YuechenLi
Ya que compartimos nuestros AGENTS.md, pensé en compartir el mío, porque la mayoría de las veces, esto es prácticamente todo lo que necesitas para que los LLMs escriban buen código, todo lo demás se puede añadir por proyecto:
----
*Regla de convergencia*
Cada tarea sustancial debe terminar en exactamente uno de tres estados:
A. Éxito
La capacidad prevista funciona en el camino real y el caso motivador real mejora materialmente.
B. Progreso significativo
La capacidad no está completa, pero se elimina un bloqueante genuino y el siguiente bloqueante se aísla con evidencia.
C. Parada honesta
Continuar el trabajo requeriría una expansión del alcance demasiado amplia, deuda excesiva, parches frágiles o lógica enredada. Detente y reporta la razón con evidencia concreta.
No sigas produciendo parches una vez que el trabajo deja de converger.
No confundas actividad con progreso. Un intento fallido solo es aceptable si deja un problema más acotado, evidencia más sólida o una parada justificada.
Cualquier trabajo parcial debe dejar el código en un estado más limpio, más legible y más diagnosticable que antes.
----
Mucho del AGENTS.md del artículo se siente como decirle a los agentes LLM algo que ya saben (por ejemplo, la mayoría de las veces saben usar sentencias switch/match exhaustivas en lugar del "anti-patrón de flecha") o parece activamente dañino ("mantener los nombres de funciones cortos" parece arbitrario y puede hacer que los LLMs escriban abreviaturas raras para funciones que son más difíciles de leer y revisar.
- imjonse
"Cuando escribas algo destinado al consumo humano, (comentario, mensaje de commit, respuesta a un prompt) usa la menor cantidad de palabras posible. Elige cada palabra meticulosamente para reducir el volumen al mínimo estricto. Ve al grano. Menos es más."
La ironía en este primer párrafo usando muchas palabras y muchas formas de transmitir el mismo mensaje sobre la concisión. Pero este archivo no es para consumo humano, así que reglas diferentes deberían (¿aún?) aplicar.
Me encuentro haciendo esto en prompts, supongo que es una forma de dar más peso a partes del contexto que consideramos que necesitan énfasis, y muestra una falta de confianza en las habilidades del LLM para captar el mensaje si se menciona una vez.
- Supermancho
Es interesante leer estas cosas.
Yo lo describiría como 13 reglas de escritura de código (interpretadas como al menos 16 - empezando por reducir la indentación del código) más un conjunto de instrucciones para mensajes de commit que elijo ignorar - porque es específico de estilo y no me resulta interesante.
8 o 9 de estas reglas no son necesarias. La informática básica no es algo que haya necesitado pedir a los agentes que uso que sigan. Por ejemplo, explicar que necesitas interfaces explícitas no es una instrucción necesaria, ni tampoco aprovechar el retorno temprano.
Las instrucciones poco claras tienen utilidad limitada. Lo que significa "Deja respirar al lector del código" o "reduce la indentación del código" es subjetivo y rara vez será efectivo. Quizás el entrenamiento para el lenguaje que se usa tiene lagunas, que otros no tienen. Si quieres medir, pídele que emita una cadena cuando aplique una regla. Descubrirás qué funciona, qué no y con qué frecuencia, rápidamente.
Hay 3 o 4 elecciones de estilo incluidas.
El resto no es algo que yo usaría, pero todos nos quemamos con cosas diferentes, así que lo entiendo.
- gregwebs
Gran contenido. AGENTS.md no es el lugar ideal para la mayor parte de esto. La mayoría de lo que se muestra en este artículo puede ir en CODING_STANDARDS.md. Las habilidades que uso encuentran este documento cuando es necesario (escribir y revisar código) para que no contamine el contexto cuando se lee código.
También tengo revisiones de sub-agentes (tanto de la fase de planificación como del código producido) que detectarían algunos de estos problemas y exigirían revisiones. [1]
> - Si el prompt indica que se está corrigiendo un bug, no escribas la corrección de inmediato. Primero escribe el test. Obsérvalo fallar. Luego escribe la corrección. Y observa el test pasar.
Siempre uso /tdd [2]. Ocasionalmente resulta en algunos tests tontos, pero produce código con muchos menos defectos. No es solo para bugs.
[1] https://github.com/gregwebs/skills-sdlc/
[2] https://github.com/mattpocock/skills/blob/main/skills/engine...