Cómo escribir un buen program.md: guía práctica para instrucciones de agentes IA

El autoresearch de Andrej Karpathy demostró que un archivo Markdown bien escrito puede dirigir agentes IA para hacer descubrimientos científicos reales de la noche a la mañana. Pero no todos los archivos program.md son iguales.

La calidad de tus instrucciones Markdown determina directamente la calidad de la salida del agente IA. Un program.md vago produce experimentos aleatorios y sin dirección. Uno preciso produce mejoras enfocadas que se acumulan.

Aquí está cómo escribir un program.md que realmente funcione.

La estructura de un buen program.md

Cada program.md efectivo necesita cinco secciones, ya sea que estés haciendo investigación de ML o cualquier otro trabajo dirigido por agentes.

1. Contexto: ¿qué necesita saber el agente?

El agente comienza con cero comprensión de tu proyecto. Tu primer trabajo es darle suficiente contexto para tomar decisiones inteligentes.

Qué incluir:

• Qué hace el proyecto
• Cómo es la base de código
• Archivos clave y sus propósitos
• Terminología específica del dominio
• Estado actual y problemas conocidos

Qué omitir:

• Información obvia que el LLM ya conoce
• Detalles de implementación que puede leer del código
• Historia que no afecta las decisiones actuales

2. Objetivos: ¿qué debe optimizar el agente?

Esta es la sección más crítica. El agente necesita un objetivo claro y medible.

En autoresearch, el objetivo es directo: reducir val_bpb (bits de validación por byte). El agente puede medir esto después de cada ejecución de entrenamiento de 5 minutos.

Para tus propios proyectos, define el éxito en términos que el agente pueda evaluar:

• “Reducir el tiempo de carga de página por debajo de 2 segundos”
• “Aumentar la cobertura de pruebas por encima del 80 %”
• “Reducir el tamaño del bundle al menos un 15 %”

Los objetivos vagos como “hacer el código mejor” producen resultados vagos. Los objetivos medibles producen mejoras enfocadas.

3. Restricciones: ¿qué nunca debe hacer el agente?

Las restricciones son tan importantes como los objetivos. Sin ellas, el agente podría encontrar soluciones creativas que no quieres — como eliminar todas las pruebas para “mejorar” la velocidad de compilación.

Restricciones comunes:

• No modificar archivos de prueba ni código de evaluación
• No cambiar la API pública
• No introducir nuevas dependencias
• No superar un presupuesto de memoria
• Mantener el código legible y mantenible

En autoresearch, la restricción clave es que solo train.py puede modificarse. El pipeline de datos, el código de evaluación y el conjunto de prueba están bloqueados. Esto evita que el agente manipule las métricas.

4. Estrategia: ¿cómo debe abordar el problema el agente?

Aquí brilla tu experiencia en el dominio. Sabes cosas que el agente no sabe — qué direcciones son prometedoras y cuáles son callejones sin salida.

Buenas instrucciones de estrategia:

• “Empezar con el ajuste de hiperparámetros antes que los cambios arquitectónicos”
• “Centrarse en el mecanismo de atención — la implementación actual puede ser subóptima”
• “Probar técnicas de regularización primero: dropout, weight decay, layer norm”
• “Evitar cambios que aumenten el tiempo de entrenamiento en más de un 10 %”

Malas instrucciones de estrategia:

• “Probar de todo” (demasiado vago)
• “Cambiar la tasa de aprendizaje a 0.001” (demasiado específico — estás micromanageando)

El punto óptimo es una guía direccional que permita al agente explorar dentro de límites productivos.

5. Evaluación: ¿cómo debe juzgar el éxito el agente?

El agente necesita saber cómo medir si sus cambios ayudaron. En autoresearch, esto está integrado en el bucle: si val_bpb mejora, conservar el cambio. Si no, revertir.

Para otros contextos, define tus criterios de evaluación:

• ¿Qué métricas importan?
• ¿Qué umbral cuenta como mejora?
• ¿Cómo debe manejar el agente los resultados ambiguos?
• ¿Cuándo debe el agente detenerse e informar?

Errores comunes

Ser demasiado vago

“Hacer el modelo mejor” no da ninguna dirección al agente. Sé específico sobre qué significa “mejor”, cómo medirlo, y qué enfoques probar primero.

Ser demasiado específico

“Cambiar la línea 47 para usar una tasa de aprendizaje de 3e-4” derrota el propósito del Agentic Engineering. Se supone que debes establecer la dirección, no dictar la implementación. Deja que el agente explore.

Olvidar las restricciones

Sin restricciones, los agentes encontrarán el camino de menor resistencia — que a menudo no es lo que quieres. Un agente al que se le dice “reducir el tiempo de entrenamiento” podría saltarse la mitad de los datos de entrenamiento si no lo prohíbes.

No iterar

Tu primer program.md no será perfecto. Observa lo que hace el agente, ve dónde se equivoca, y actualiza tus instrucciones. Los mejores archivos program.md evolucionan a lo largo de docenas de iteraciones.

El bucle de iteración

Escribir program.md no es un proceso de una sola vez. Es un bucle:

1. Escribir tu program.md inicial
2. Ejecutar el agente
3. Revisar lo que hizo el agente
4. Actualizar tus instrucciones según lo que funcionó y lo que no
5. Repetir

Cada iteración hace tus instrucciones más precisas. Después de algunos ciclos, tendrás un program.md que produce constantemente buenos resultados.

Esta es la habilidad central del Agentic Engineering: no escribir código, sino escribir instrucciones de agentes cada vez más efectivas mediante la iteración.

Construir tu biblioteca de referencia

Los mejores archivos program.md no surgen de la nada. Se construyen sobre un profundo conocimiento del dominio — documentación, artículos, mejores prácticas y ejemplos.

Cuando encuentres material de referencia útil en la web, guárdalo como Markdown. Luego, cuando escribas tu program.md, puedes incorporar contexto relevante, citar técnicas específicas y dar al agente el conocimiento de fondo que necesita.

Los investigadores que obtienen los mejores resultados del autoresearch no son solo buenos escritores. Son expertos del dominio con material de referencia bien organizado que pueden sintetizar en instrucciones claras para los agentes.

---

Save convierte cualquier página web a Markdown limpio — perfecto para construir la biblioteca de referencia que impulsa archivos program.md efectivos. Prueba Save gratis.