Un buen prompt para un agente de programación con IA dice cuatro cosas: qué quieres, por dónde empezar, qué no debe cambiar y cómo saber que ha funcionado. La mayoría de los malos resultados vienen de omitir una de ellas, no de elegir mal las palabras. El agente puede leer tu código, ejecutar comandos y editar archivos, así que la función del prompt es orientar ese trabajo en la dirección correcta y darle una meta.
Esta guía muestra prompts malos y buenos lado a lado y luego cubre el contexto, los planes, la división del trabajo, la verificación y dónde guardar los prompts que reutilizas. Los ejemplos usan Claude Code y Codex CLI, pero los hábitos sirven para Gemini CLI y cualquier otro agente de programación.
Por qué escribir prompts para un agente es distinto que para un chatbot
Un chatbot solo tiene tu mensaje. Un agente de programación tiene todo tu repositorio, una shell y un ciclo: lee archivos, hace un cambio, ejecuta algo, mira el resultado y vuelve a intentarlo. Eso cambia lo que necesita hacer un prompt:
- No hace falta pegar código. Señala los archivos y deja que el agente los lea.
- Sí hace falta poner límites. Un agente que puede editar cualquier cosa puede editar cosas que no pretendías.
- Necesitas una regla para parar. Sin ella, el agente decide por su cuenta cuándo el trabajo es suficientemente bueno, y su listón puede no ser el tuyo.
Cada archivo extra que lee el agente también llena su ventana de contexto. Un prompt enfocado mantiene al agente enfocado y la sesión más barata.
Prompt malo vs prompt bueno
Este es un primer intento típico:
fix the login bugEl agente tiene que adivinar qué bug, dónde está y qué significa “arreglado”. Puede cambiar el archivo equivocado, reescribir una función que estaba bien o “arreglar” el síntoma capturando el error.
Esta es la misma petición escrita para un agente:
Users with an email that has uppercase letters can't log in: the API returns
401 even with the right password. Signup stores emails as typed; login looks
them up as typed too, so "Ana@x.com" and "ana@x.com" don't match.
Start in src/auth/login.ts and src/auth/signup.ts.
Normalize emails to lowercase on both signup and login. Don't change the
database schema in this task, and don't touch the session code.
Done when: a new test in tests/auth.test.ts logs in with "Ana@X.com" after
signing up with "ana@x.com", and `pnpm test` passes. Show me the diff.Es más largo, pero cada línea le ahorra al agente una suposición. Esto es lo que hace cada parte:
| Parte | Ejemplo | Por qué ayuda |
|---|---|---|
| Síntoma | “devuelve 401 incluso con la contraseña correcta” | El agente sabe qué reproducir |
| Causa, si la conoces | “guarda los emails tal como se escriben” | Se ahorra una búsqueda larga |
| Archivos de partida | src/auth/login.ts | Menos lectura, menos suposiciones erróneas |
| Restricciones | “no cambies el esquema de la base de datos” | Mantiene el cambio pequeño y seguro |
| Criterios de terminado | un test concreto más pnpm test | Una meta que el agente puede comprobar |
No siempre conoces la causa. No pasa nada: dilo y pide al agente que la encuentre antes de arreglarla. “Averigua por qué pasa X y explícamelo antes de cambiar nada” es un prompt potente por sí solo.
Da contexto, no redacciones
El contexto más útil es concreto y comprobable. Más o menos por orden de valor:
- Rutas de archivos y símbolos.
src/billing/invoice.ts,calculateTax(). En Claude Code y Codex puedes escribir@para elegir un archivo y adjuntarlo. - Salida de errores. Pega el stack trace exacto o la salida del test que falla, no un resumen.
- Restricciones. Librerías que usas o no usas, carpetas que no se tocan, APIs que deben seguir siendo compatibles hacia atrás.
- Ejemplos en el código. “Sigue el patrón de
src/routes/users.ts” es mejor que un párrafo describiendo el patrón. - El porqué. Una frase sobre el objetivo de cara al usuario ayuda al agente a tomar decisiones razonables que no detallaste.
Qué dejar fuera: la larga historia del proyecto, tus opiniones sobre código no relacionado e instrucciones que valen para todas las tareas. Estas últimas van en un archivo del proyecto, como verás más abajo.
Las capturas de pantalla ayudan en el trabajo de interfaz. Claude Code y Codex aceptan imágenes; Codex también admite codex --image path/to/file.png en la línea de comandos.
Pide primero un plan
Para todo lo que sea más grande que un arreglo pequeño, separa pensar de hacer. Pide al agente que lea el código y proponga un plan, revísalo y luego deja que lo implemente.
- Claude Code: pulsa Shift+Tab hasta que la barra de estado muestre el modo plan, escribe
/planantes de un único prompt o arranca conclaude --permission-mode plan. En modo plan, Claude lee y propone, pero no edita. El modo plan de Claude Code cubre los detalles. - Codex CLI:
/planpide a Codex que planifique antes de implementar. También puedes iniciar una sesión de solo lectura poniendo/permissionsen Read Only. - Cualquier agente: dilo con palabras: “No edites nada todavía. Lee los archivos relevantes y dame un plan numerado con los archivos que vas a cambiar.”
Un prompt de planificación que funciona bien:
We need to add CSV export to the reports page.
Don't write code yet. Read src/reports/ and the existing PDF export in
src/export/pdf.ts, then give me:
1. the files you will add or change,
2. how the CSV is built and streamed,
3. what you'll test,
4. anything you're unsure about.Leer el plan lleva un minuto y detecta los errores caros: la carpeta equivocada, una dependencia nueva que no quieres, una migración que no esperabas. Si el plan está mal, corrígelo con palabras sencillas (“usa el helper toRows() que ya existe en lugar de un parser nuevo”) y pide un plan revisado.
Divide las tareas grandes en pasos
Los agentes rinden mejor en tareas que podrías revisar de una sentada. Un prompt como “construye el sistema de facturación” produce un diff enorme, difícil de comprobar y difícil de deshacer. Divídelo:
Step 1 of 4: add the Invoice model and migration only.
No API routes or UI yet. Run the migration on the dev database and the
model tests, then stop and show me the diff.Luego el paso 2 es la API, el paso 3 la interfaz y el paso 4 los emails. Después de cada paso revisas, haces commit y empiezas el siguiente. Dos hábitos hacen que esto funcione:
- Haz commit entre pasos. Un commit limpio es un punto de control. Si el paso 3 sale mal, vuelves al final del paso 2 en lugar de desenredar un diff mezclado. Deshacer cambios de Claude Code repasa las opciones.
- Contexto nuevo para trabajo no relacionado. Usa
/clearen Claude Code o/newen Codex cuando cambies de tema. El contexto viejo cuesta tokens y arrastra al agente hacia la tarea anterior.
Los pasos independientes también pueden ejecutarse en paralelo, cada agente en su propio git worktree para que no se pisen los archivos.
Dile al agente cómo verificar
“Haz que funcione” deja que el agente decida qué significa funcionar. Una instrucción de verificación te devuelve esa decisión. Las buenas son comandos con un resultado claro:
Done when:
- `pnpm test tests/export.test.ts` passes, including a new test for an
empty report,
- `pnpm typecheck` has no errors,
- GET /reports/42/export.csv returns a header row and one row per entry.
Paste the command output at the end.Algunos patrones que suben el listón:
- Primero el test. “Escribe un test que reproduzca el bug, ejecútalo y muéstrame que falla. Luego arregla el código hasta que pase.” Así se demuestra que el test cubre de verdad el bug. Más en escribir tests unitarios con IA.
- Pide pruebas, no afirmaciones. “Pega la salida” es más difícil de falsear que “confirma que funciona”.
- Nombra lo que no debe romperse. “Los tests existentes en
tests/auth/deben seguir pasando.” - Prohíbe los atajos. “No te saltes ni borres tests, y no añadas casts a
anypara silenciar errores de tipos.” Los agentes presionados para que una comprobación pase a veces toman estos caminos.
Después lee el diff. Un segundo modelo que revise el cambio detecta mucho; consulta revisión de código con IA.
Prompts que salen mal, y cómo arreglarlos
| Prompt | Lo que suele pasar | Mejor |
|---|---|---|
| “Limpia este archivo” | Reescritura grande, funciones renombradas, imports rotos en otros sitios | “Extrae el parseo de parse.ts a su propia función; no cambies la API pública” |
| “Añade tests” | Tests superficiales que comprueban que el código hace lo que hace | “Añade tests para entrada vacía, un archivo de 10 MB y una cabecera mal formada; cada uno debe fallar si quito la comprobación de la línea 40” |
| “Hazlo más rápido” | Microoptimizaciones al azar | “El endpoint /search tarda 2 s con 10k filas. Perfílalo, dime dónde se va el tiempo y luego propón un arreglo” |
| “Usa buenas prácticas” | Lo que el modelo considere mejor esta vez | Nombra la práctica: “usa el patrón repository de src/db/users.ts” |
| Una lista de diez arreglos sin relación | A medio hacer, contexto lleno en el sexto | Una tarea por prompt, o diez tareas en una cola |
Haz los prompts reutilizables
Si escribes la misma instrucción en cada sesión, sácala de tus prompts.
Reglas del proyecto: CLAUDE.md, AGENTS.md, GEMINI.md
Cada agente lee un archivo de instrucciones del proyecto al empezar una sesión: CLAUDE.md en Claude Code, AGENTS.md en Codex (y varios agentes más), GEMINI.md en Gemini CLI. Pon ahí comandos y convenciones, breves y concretos:
## Commands
- Test: pnpm test (run before saying a task is done)
- Typecheck: pnpm typecheck
## Rules
- Don't edit files in src/generated.
- Don't add dependencies without asking.
- New API routes need a test in tests/routes/.Ahora “ejecuta los tests antes de decir que has terminado” forma parte de cada prompt sin que lo escribas. /init en Claude Code, Codex y Gemini CLI genera un primer borrador. CLAUDE.md y AGENTS.md explica cómo mantener un único conjunto de reglas para varios agentes.
Flujos repetidos: skills y comandos personalizados
Para una tarea que repites de vez en cuando, como una release, una migración o una lista de revisión, escríbela una vez como skill o comando personalizado y llámala por su nombre.
Claude Code usa skills: una carpeta con un archivo SKILL.md, en .claude/skills/<nombre>/ para el proyecto o en ~/.claude/skills/<nombre>/ para ti. El nombre de la carpeta se convierte en un comando, y $ARGUMENTS recibe lo que escribas después:
---
name: fix-issue
description: Use when the user asks to fix a GitHub issue by number.
---
Fix GitHub issue $ARGUMENTS.
1. Read the issue with `gh issue view $ARGUMENTS`.
2. Write a failing test that reproduces it.
3. Fix the code until the test passes, then run `pnpm test`.
4. Summarize the change in two sentences.Ahora /fix-issue 123 ejecuta todo el prompt. Los archivos Markdown antiguos en .claude/commands/ siguen funcionando igual, pero la documentación de Anthropic recomienda skills para el trabajo nuevo porque la carpeta de una skill también puede contener scripts y archivos de referencia. Claude también carga una skill por su cuenta cuando tu petición coincide con su descripción. Más en skills de Claude Code.
Codex lee skills de .agents/skills en un proyecto y de ~/.codex/skills para ti, con el mismo formato SKILL.md.
Gemini CLI usa comandos personalizados en TOML en .gemini/commands/ (proyecto) o ~/.gemini/commands/ (usuario). {{args}} se sustituye por lo que escribes después del comando, y las subcarpetas se convierten en espacios de nombres, así que git/commit.toml es /git:commit:
description = "Fix a GitHub issue by number"
prompt = """
Fix GitHub issue {{args}}. Write a failing test first,
then fix the code and run the test suite.
"""Una buena regla general: las reglas que siempre se aplican van en el archivo del proyecto, los flujos que usas a veces van en skills, y el prompt solo lleva lo específico de la tarea de hoy.
Una plantilla de prompt para copiar
Goal: <one sentence, user-facing>
Context: <symptom, error output, what you already know>
Start in: <files or folders>
Constraints: <what must not change, libraries to use or avoid>
Plan first: <yes/no — if yes, don't edit until I approve>
Done when: <commands that must pass, behaviour to show>
Report: <diff, command output, open questions>No hace falta cada línea cada vez. Para corregir una errata basta con “Goal”. Para una funcionalidad nueva, rellénalas todas.
Prompts para agentes en AgentVera
AgentVera es una app de escritorio para macOS, Windows y Linux que ejecuta Claude Code, Codex, Gemini CLI y otros agentes CLI uno al lado de otro en terminales reales. Los prompts son los mismos; algunas funciones se encargan de las partes repetitivas:
- Verify: los criterios de terminado que escribes en tu mensaje se extraen como criterios de aceptación. Cuando el agente termina su turno, un verificador independiente lee el diff, ejecuta los comandos de test permitidos y marca cada criterio como superado o fallido, con pruebas. No puede editar archivos. Verify está en los planes Pro y Team.
- Revisión de código: cuando termina un turno, un segundo modelo de Claude revisa lo que escribió el agente, y los hallazgos pueden volver directamente al agente.
- Enviar al agente: envía un error de la terminal, un diff, un log o una línea de código a un agente con ⌘⇧L en lugar de copiarlo y pegarlo en tu prompt.
- Galería de skills: crea, edita y activa o desactiva skills de Claude Code y Codex en una sola lista, e instala skills compartidas tras un análisis de seguridad.
- Workspace: una cuadrícula de agentes por proyecto, para que cada paso en que dividas el trabajo tenga su propio agente y worktree.
Descarga AgentVera y prueba tu próximo prompt con estas funciones al lado.
Para terminar
Escribe los prompts como un ticket para un compañero capaz que acaba de llegar: el objetivo, dónde mirar, qué no tocar y cómo vas a juzgar el resultado. Pide un plan cuando la tarea sea grande, divídela en pasos que puedas revisar y da siempre un comando que demuestre que está terminada. Lleva lo que repites a CLAUDE.md, AGENTS.md o una skill. Los mismos hábitos importan todavía más cuando el agente toca una base de datos; escribir SQL y migraciones con IA los aplica a esquemas y migraciones.