Mi agent.md para mejorar la calidad del código asistido por LLM
Los desarrolladores están debatiendo cuán útiles son los archivos dedicados “AGENTS.md” para orientar a los modelos de lenguaje grandes al generar código, en comparación con depender de linters, documentos existentes de CONTRIBUTING/CODING_STANDARDS y directrices más simples y de alto nivel. Muchos se quejan de que los modelos producen en exceso comentarios de poco valor y correcciones de estilo verbosas, argumentando que las comprobaciones mecánicas y las reglas concisas, formuladas en positivo, funcionan mejor que archivos largos y detallados de instrucciones para agentes que pueden diluir el contexto o quedar obsoletos a medida que mejoran los modelos. Otros siguen encontrando valor en prompts mínimos para agentes que codifican normas de flujo de trabajo (como TDD o limitar ediciones no relacionadas) y restricciones de voz/estilo, pero ven configuraciones por proyecto y evolutivas como más efectivas que conjuntos de reglas universales.
Rol y diseño de AGENTS.md
- Muchos ven AGENTS.md como algo útil pero muy personal: distintas personas, proyectos y modelos tienen distintos modos de fallo, así que una plantilla compartida es solo un punto de partida.
- Algunos sostienen que gran parte del contenido del artículo es CS genérico o ya “conocido” por los modelos modernos, por lo que reglas extra pueden aportar poco o incluso perjudicar.
- Otros sienten que AGENTS.md es una “fea tirita” que se queda obsoleta con los modelos nuevos, a menudo se ignora y puede envenenar el razonamiento cuando las reglas se malinterpretan.
- Alternativa: mantener las reglas del proyecto en CONTRIBUTING/CODING_STANDARDS y que el harness o las skills las descubran según sea necesario.
Linters vs instrucciones del agente
- Tema fuerte: hacer cumplir las reglas mecánicas/de estilo con linters, hooks de pre-commit y CI, no mediante agentes no deterministas.
- Ejemplos: llaves en
ifde una sola línea, no ternarios anidados, no comentarios, formato, números mágicos. - Algunos usan un LLM como CI/revisor para detectar patrones/comentarios prohibidos, haciendo que “los robots peleen con los robots”.
Comentarios y documentación
- Frustración generalizada con el exceso de comentarios: los agentes generan comentarios verbosos de “qué hace esto”, a menudo más largos que el código.
- Muchos intentan prohibir por completo los comentarios o permitir solo comentarios de “por qué/contexto”; el “qué” debería ser evidente por sí mismo en el código.
- Preocupaciones: los comentarios se quedan obsoletos, engañan a humanos y a futuros agentes, y contaminan el contexto.
- Una minoría defiende los comentarios como resúmenes de funciones grandes/feas o lugares con complejidad oculta; algunos ocultan los comentarios mediante el plegado del editor.
Seguimiento de instrucciones y estrategia de prompt
- Los usuarios reportan resultados mixtos con reglas como “nunca añadas comentarios”; los modelos más nuevos y grandes obedecen mejor, otros las ignoran.
- Discusión sobre la formulación “haz” frente a “no hagas”: las instrucciones positivas pueden persistir mejor que las prohibiciones, pero algunas restricciones (p. ej., “nunca comentarios”) son difíciles de expresar sin “no”.
- Un AGENTS.md largo y denso puede sufrir dilución del contexto por “lost in the middle”; varios prefieren reglas núcleo breves, o archivos de reglas modulares que el agente selecciona por tarea.
Preferencias de estilo, arquitectura y flujo de trabajo
- Fuertes desacuerdos sobre mandatos de estilo: nombres de funciones cortos frente a largos, llaves siempre frente a minimalismo, enums frente a booleanos, funciones pequeñas extraídas frente a otras más grandes.
- Algunos enfatizan el contexto arquitectónico y el “por qué” en AGENTS.md por encima de las reglas a nivel de línea.
- Flujos de trabajo mencionados: generación en varias pasadas con auto-revisión, reglas de estilo convergentes (éxito/progreso/parada honesta), prompting centrado en TDD y límites estrictos para que los agentes no toquen código no relacionado.