# Cómo escribir prompts para agentes de programación con IA URL: https://agentvera.dev/es/blog/prompts-for-ai-coding-agents/ · Publicado: 2026-10-27 Cómo escribir prompts para agentes de programación con IA: ejemplos malos y buenos, archivos y restricciones, pedir un plan, dividir tareas, verificar y reutilizar. **En resumen:** - Un buen prompt para un agente de programación indica el objetivo, los archivos por los que empezar, las restricciones y cómo comprobar el resultado. Los prompts vagos dan código vago. - Para todo lo que sea más grande que un arreglo pequeño, pide primero un plan, divide el trabajo en pasos que puedas revisar y dile al agente qué comando demuestra que ha terminado. - Las reglas que repites van en CLAUDE.md, AGENTS.md o GEMINI.md; los flujos que repites se convierten en skills o comandos personalizados, así cada prompt puede ser breve. **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](/es/glossary/coding-agent/ "Qué es un 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](/es/glossary/context-window/ "Qué es la 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: ```text fix the login bug ``` El 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: ```text 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: 1. **Rutas de archivos y símbolos.** `src/billing/invoice.ts`, `calculateTax()`. En Claude Code y Codex puedes escribir `@` para elegir un archivo y adjuntarlo. 2. **Salida de errores.** Pega el stack trace exacto o la salida del test que falla, no un resumen. 3. **Restricciones.** Librerías que usas o no usas, carpetas que no se tocan, APIs que deben seguir siendo compatibles hacia atrás. 4. **Ejemplos en el código.** “Sigue el patrón de `src/routes/users.ts`” es mejor que un párrafo describiendo el patrón. 5. **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 `/plan` antes de un único prompt o arranca con `claude --permission-mode plan`. En modo plan, Claude lee y propone, pero no edita. [El modo plan de Claude Code](/es/blog/claude-code-plan-mode/ "Modo plan de Claude Code") cubre los detalles. - **Codex CLI:** `/plan` pide a Codex que planifique antes de implementar. También puedes iniciar una sesión de solo lectura poniendo `/permissions` en 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: ```text 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: ```text 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](/es/blog/undo-claude-code-changes/ "Deshacer cambios de Claude Code") repasa las opciones. - **Contexto nuevo para trabajo no relacionado.** Usa `/clear` en Claude Code o `/new` en 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](/es/blog/git-worktree-parallel-agents/ "Git worktrees para agentes en paralelo") 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: ```text 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](/es/blog/write-unit-tests-with-ai/ "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 `any` para 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](/es/blog/ai-code-review/ "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: ```markdown ## 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](/es/blog/claude-md-agents-md/ "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//` para el proyecto o en `~/.claude/skills//` para ti. El nombre de la carpeta se convierte en un comando, y `$ARGUMENTS` recibe lo que escribas después: ```markdown --- 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](/es/blog/claude-code-skills/ "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`: ```toml 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 ```text Goal: Context: Start in: Constraints: Plan first: Done when: Report: ``` 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](/es/features/verify/ "Verify de AgentVera"):** 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](/es/features/code-review/ "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](/es/features/send-to-agent/ "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](/es/features/skill-gallery/ "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](/es/features/workspace/ "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](/es/download/ "Descargar 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](/es/blog/write-sql-with-ai/ "Escribir SQL con IA") los aplica a esquemas y migraciones. ## Preguntas frecuentes **¿Qué longitud debe tener un prompt para un agente de programación?** La necesaria para indicar el objetivo, los archivos de partida, las restricciones y los criterios de terminado, y nada más. Para un arreglo pequeño son dos o tres líneas. Para una funcionalidad suele ser un párrafo corto más una lista. El contexto que vale para todas las tareas va en CLAUDE.md o AGENTS.md, no en cada prompt. **¿Debo pedirle al agente un plan antes de que escriba código?** Sí, para todo lo que toque más de un par de archivos o que no puedas describir con precisión. En Claude Code usa el modo plan (Shift+Tab o /plan) y en Codex usa /plan. Lee el plan, corrígelo y luego deja que el agente lo implemente. Para un arreglo de una línea, un plan sobra. **¿Ayudan a los agentes trucos como “eres un ingeniero sénior”?** Mucho menos que la información concreta. Una línea de rol cuesta poco, pero el agente gana mucho más con el archivo por el que empezar, el comando que ejecuta los tests y el comportamiento que esperas. Gasta tus palabras en hechos sobre la tarea. **¿Dónde guardo los prompts que uso una y otra vez?** Las reglas del proyecto van en CLAUDE.md (Claude Code), AGENTS.md (Codex y otros agentes) o GEMINI.md (Gemini CLI). Los flujos repetidos se convierten en skills: .claude/skills//SKILL.md en Claude Code, .agents/skills en Codex. Gemini CLI usa comandos personalizados en TOML en .gemini/commands. **¿Cómo evito que un agente diga que una tarea está terminada cuando no lo está?** Dale una comprobación que deba ejecutar, como un comando de tests, una build o una petición curl, y pídele que pegue la salida. Pide un test nuevo que falle antes del cambio y pase después. Luego revisa tú el diff o haz que lo revise un segundo agente. --- **Sobre AgentVera.** AgentVera es una app de escritorio para macOS, Windows y Linux, desarrollada por Solviera Teknoloji. Ejecuta 18 agentes de programación con IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) en paralelo, por proyecto, en terminales reales con las instalaciones y sesiones de CLI del propio usuario. El plan gratuito tiene agentes ilimitados. Descargar: https://agentvera.dev/es/download/ · Precios: https://agentvera.dev/es/pricing/