Prompting: escribir instrucciones que un modelo pueda seguir
Un prompt es la especificación de una tarea para alguien que no estuvo en la reunión. Esta página reúne las técnicas que más cambian el resultado y muestra cómo las aplica este repo en sus archivos de instrucciones, sus skills y sus briefings a subagentes.
Anatomía de un prompt
Un modelo de lenguaje no conoce tu proyecto, tu equipo ni lo que decidiste ayer. Todo lo que necesita para hacer bien la tarea tiene que estar en el texto que recibe, o en archivos que ese texto le diga que lea. Por eso conviene pensar el prompt en partes. No todas aparecen siempre, pero cuando falta una suele notarse en la respuesta.
Instrucciones claras y restricciones
La prueba más útil es la del colega nuevo: si le dieras el mismo texto a una persona competente que no conoce el proyecto, podría hacer la tarea sin preguntarte nada? Si la respuesta es no, al modelo le falta lo mismo que a esa persona.
Las instrucciones funcionan mejor cuando dicen qué resultado esperas y cómo
sabrás que está bien. «Revisa este test» deja al modelo eligiendo el alcance. «Revisa si
este test comprueba el caso de sesión expirada y dime qué assertion falta» tiene un criterio
de éxito. Explica también el porqué de una regla: un modelo que sabe que las credenciales
van en .env para que no terminen en un commit generaliza mejor que uno que solo
leyó «no hardcodees contraseñas».
Las restricciones marcan los bordes: qué archivos no tocar, qué herramientas usar, qué idioma. Formúlalas en positivo cuando puedas («responde en español») y reserva las prohibiciones para lo que tiene costo real si se rompe. Una lista de veinte «NUNCA» en mayúsculas diluye las dos que importan.
Few-shot contra zero-shot
- Zero-shot
- Solo instrucciones, sin ejemplos. Alcanza para tareas comunes con una salida obvia.
- Few-shot
- Instrucciones más dos a cinco pares de entrada y salida. Sirve cuando el formato, el tono o el criterio son difíciles de describir con palabras.
Los ejemplos pesan más que las instrucciones: el modelo tiende a copiar su largo, su estructura y hasta sus errores. Por eso tienen que ser variados (un caso feliz, uno con error, uno en el límite) y consistentes con lo que pides en el texto. Si el ejemplo dice una cosa y la instrucción otra, casi siempre gana el ejemplo. En QA esto aparece al pedir test cases con un formato fijo: dos casos bien escritos enseñan más que un párrafo describiendo columnas.
Chain of thought: cuándo sí y cuándo no
Pedirle al modelo que razone paso a paso antes de responder mejora los resultados en tareas de varios pasos: cálculos, decisiones con varias condiciones que interactúan, diagnóstico de una falla a partir de un log. El trabajo intermedio queda escrito y el modelo lo usa para llegar a la conclusión. También te deja auditar cómo llegó ahí.
| Pide razonamiento | No hace falta |
|---|---|
| Clasificar un defecto según varias reglas (severidad, etapa del feature) | Extraer un campo de un JSON |
| Decidir qué técnica de diseño de pruebas aplica a un criterio | Traducir o reformatear un texto |
| Encontrar la causa de un test intermitente | Responder con una etiqueta de una lista cerrada |
En tareas simples el razonamiento suma latencia y tokens sin mejorar nada. Muchos modelos actuales ya razonan internamente por su cuenta; en ese caso una instrucción general («piensa bien el problema antes de responder») suele rendir más que dictarle los pasos uno por uno.
Formato de salida
Si otra herramienta o persona va a consumir la respuesta, pide la forma exacta: un objeto
JSON con campos nombrados, una tabla con columnas fijas, un bloque de código sin prosa
alrededor. Separar las partes del prompt con encabezados o etiquetas
(<contexto>,
<tarea>) ayuda al modelo a distinguir los datos de las instrucciones,
sobre todo cuando pegas documentos largos. Y el formato de la salida tiende a imitar al del
prompt: un prompt lleno de viñetas produce respuestas en viñetas.
Prompts como código versionado
Un prompt que se usa más de una vez es código. Vive en un archivo, pasa por control de versiones y cambia con commits que explican el motivo. Así puedes responder qué instrucción tenía el agente cuando produjo un resultado raro, y volver atrás si una edición empeoró las cosas.
-
Escribe
La instrucción vive en un archivo del repo, no en el historial de un chat.
-
Prueba
Casos con prompts de entrada y el comportamiento esperado, igual que un test.
-
Valida
Un linter comprueba lo que se puede comprobar sin el modelo: referencias, estructura, variables.
-
Revisa y versiona
El cambio entra con un commit y se puede revertir.
Sin ese ciclo, cada mejora es anecdótica. Con él, un cambio de redacción se trata como cualquier otro cambio de comportamiento.
Así lo hace este repo
Casi todo lo que el agente sabe de este proyecto está escrito en archivos versionados. Estas son las piezas y la técnica que aplica cada una.
| Pieza | Dónde | Técnica |
|---|---|---|
| Archivo de instrucciones |
AGENTS.md (Claude Code lo lee a través de CLAUDE.md, que
solo contiene @AGENTS.md)
|
Rol, reglas y restricciones que se cargan en cada sesión; el detalle de cada tema
está en .agents/instructions/ y se lee cuando el router lo nombra
|
| Skills |
.agents/skills/sprint-testing/SKILL.md,
.agents/skills/test-automation/SKILL.md
|
Instrucciones por tarea que se cargan solo cuando hacen falta |
| Briefing a subagentes | .agents/skills/agentic-qa-core/references/briefing-template.md |
Plantilla fija con formato de salida obligatorio |
| Variables y pseudocódigo | .agents/README.md, .agents/project.yaml |
Separar la instrucción de los datos del proyecto |
| Evals de activación | .agents/skills/sprint-testing/evals/evals.json |
Casos de prueba del propio prompt |
Skills: la descripción decide cuándo se cargan
Cada SKILL.md abre con un frontmatter YAML. El campo
description es lo que el agente lee para decidir si la skill aplica, así que
funciona como un prompt de clasificación. La de sprint-testing dice qué hace,
enumera frases disparadoras después de Triggers on: («test this ticket»,
«retest this bug») y termina con Do NOT use for:, que manda la documentación en
TMS a test-documentation y la automatización a test-automation.
Los contraejemplos son tan explícitos como los ejemplos.
Algunas skills agregan compact_rules: reglas cortas que
scripts/build-skill-registry.ts copia sin cambios a
.agents/skills/REGISTRY.md (se regenera con
bun run skills:registry). Es la versión resumida de la skill para cuando un
subagente necesita las convenciones sin leer el archivo completo.
El briefing de 7 componentes
Cuando el agente principal delega trabajo, el briefing tiene siete partes fijas: objetivo en
una oración, documentos de contexto con rutas absolutas, estándares del proyecto sacados de
REGISTRY.md, skills a cargar, instrucciones numeradas, formato del reporte y
reglas. Es la anatomía del diagrama de arriba convertida en plantilla. La plantilla pide que
el reporte sea un JSON con campos nombrados o una lista con encabezados, y desaconseja la
prosa libre, porque el orquestador tiene que leer y combinar varios reportes.
Pseudocódigo y variables
Las skills no escriben el comando concreto de Jira ni la URL del entorno. Escriben
[ISSUE_TRACKER_TOOL] o [AUTOMATION_TOOL], y la sección 6
(.agents/instructions/agent-tool-resolution.md) resuelve cada etiqueta a una
herramienta (/acli, /playwright-cli) con su alternativa. Los
valores del proyecto usan {{PROJECT_KEY}} o {{WEB_URL}}, que salen
de .agents/project.yaml; los de sesión usan
<<ISSUE_KEY>>. La misma skill sirve en cualquier proyecto, y
bun run vars:check falla si una skill referencia una variable que no está
declarada.
Probar los prompts
Las skills con carpeta evals/ traen prompts de ejemplo, el comportamiento
esperado y una polaridad (positive si la skill debería activarse,
negative si no). bun run skills:evals valida la estructura de esos
casos. Todavía no ejecuta un modelo, así que confirma que los casos están bien formados, no
que la skill se active de verdad; el propio script lo aclara en su cabecera.
Hay además un hook, .agents/hooks/personality-reinject.mjs, que en cada turno
compara el pedido con el router de AGENTS.md y agrega una línea
ROUTE: read <archivo> por cada sección de
.agents/instructions/ que el pedido necesita y la sesión todavía no leyó, con
un tope de pocas por pedido (las demás quedan en una línea opcional). Es la respuesta del
repo a un problema conocido: una tabla que el modelo tiene que acordarse de consultar pierde
peso a medida que la conversación crece, y una línea escrita en el turno no. El detalle de
ese tema está en Contexto.
Errores comunes
- Asumir contexto compartido. «Arregla lo de ayer» no significa nada para una sesión nueva.
- Ejemplos que contradicen la instrucción. El modelo copia el ejemplo.
- Gritar todo. Si diez reglas están en mayúsculas, ninguna sobresale, y el modelo puede aplicarlas con un celo que no querías.
- Pedir razonamiento paso a paso para extraer un dato. Pagas latencia y no ganas precisión.
- Dejar el formato de salida abierto cuando un script va a leer la respuesta.
- Editar un prompt compartido sin probarlo. Un cambio que mejora un caso puede romper otros tres; los evals existen para verlo antes.
- Pegar el mismo bloque de instrucciones en varios archivos. Cuando cambie, solo vas a actualizar una copia.
Para profundizar
- Prompt engineering overview (Anthropic). Empieza por definir criterios de éxito y evals antes de tocar el prompt.
- Prompt engineering (OpenAI). Guía de la API con estrategias de instrucciones, ejemplos y formato.
- Prompt design strategies (Google, Gemini API). Instrucciones claras, few-shot y uso de delimitadores.
- Language Models are Few-Shot Learners (Brown et al., 2020). El paper que popularizó el aprendizaje con ejemplos dentro del prompt.
- Chain-of-Thought Prompting Elicits Reasoning in Large Language Models (Wei et al., 2022). Ejemplos con pasos intermedios en tareas de razonamiento.
- Large Language Models are Zero-Shot Reasoners (Kojima et al., 2022). Razonamiento paso a paso sin ejemplos.