Los agentes de programación no son un autocompletado. Herramientas como Claude Code, OpenAI Codex, el agente de Copilot o el modo agente de Cursor leen tu repositorio, editan decenas de archivos, ejecutan comandos, revisan la salida y lo vuelven a intentar. Bien usados, convierten una tarea de media jornada en una revisión de veinte minutos. Mal usados, generan diffs enormes que parecen razonables y rompen cosas de formas que nadie detecta hasta producción. Esta guía reúne las prácticas que, según mi experiencia y las recomendaciones publicadas por los propios fabricantes, separan un resultado del otro.

Cómo funciona realmente un agente de programación

Por dentro, todos los agentes de programación son el mismo bucle: el modelo recibe una tarea y contexto, decide una acción (leer un archivo, buscar, editar, ejecutar un comando), el entorno la ejecuta y el resultado vuelve al contexto. El bucle continúa hasta que el modelo decide que ha terminado o alcanza un límite. Es el patrón de "agente" descrito en Building effective agents de Anthropic y formalizado en investigaciones como ReAct.

De ahí se derivan dos consecuencias:

  1. El agente solo sabe lo que hay en su ventana de contexto. No "recuerda" tus convenciones a menos que estén escritas en algún sitio que lea.
  2. El agente es tan bueno como su feedback. Si puede ejecutar tests, un comprobador de tipos y un linter, puede corregir sus propios errores. Si no puede, adivina.

La investigación sobre SWE-agent mostró que el diseño de la interfaz agente-ordenador —cómo se muestran los archivos, cómo se aplican las ediciones, qué devuelven los comandos— influye mucho en la tasa de éxito sobre issues reales de GitHub (Yang et al., 2024). La mayoría de las prácticas siguientes consisten en mejorar esa interfaz para tu repositorio.

Práctica 1: escribe un archivo de instrucciones del proyecto

Todo agente serio admite un archivo de instrucciones a nivel de repositorio que se carga en el contexto al inicio de cada sesión: CLAUDE.md para Claude Code, AGENTS.md para Codex y otras herramientas, .github/copilot-instructions.md para Copilot. Mantenlo corto, concreto y actualizado.

# CLAUDE.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 3000)
- Tests: `pnpm test` (Vitest, ~20 s). Single file: `pnpm test path/to/file.test.ts`
- Types: `pnpm tsc --noEmit` — must pass before you say you're done
- Lint: `pnpm lint --fix`

## Architecture
- Next.js App Router in `app/`, shared UI in `components/`, domain logic in `lib/`
- Server-only code imports "server-only"; never import it from client components
- All money values are integers in minor units (cents)

## Rules
- Do not edit generated files in `lib/api/generated/`
- Do not add dependencies without asking
- Prefer small commits with conventional commit messages

Qué incluir: comandos, la arquitectura en pocas líneas, convenciones no obvias y reglas tajantes de "nunca". Qué no incluir: consejos genéricos que el modelo ya sigue ("escribe código limpio"), guías de estilo largas que el linter ya impone, ni secretos. Las buenas prácticas de Claude Code de Anthropic recomiendan iterar este archivo como si fuera un prompt: cuando el agente repite un error, añade una línea que lo evite.

Práctica 2: explora, planifica y después ejecuta

El fallo más común es dejar que el agente empiece a editar de inmediato. Para cualquier cosa mayor que un arreglo en un solo archivo, divide la sesión en fases:

  1. Explorar. "Lee el módulo de pagos y los tests de reembolsos. No escribas código todavía. Resume cómo fluyen los reembolsos por el sistema."
  2. Planificar. "Propón un plan para admitir reembolsos parciales. Enumera los archivos que vas a cambiar y los tests que vas a añadir." Revisa el plan. Corrige aquí los malentendidos: es diez veces más barato que corregir código.
  3. Ejecutar. "Implementa el paso 1 del plan. Ejecuta los tests después de cada paso."
  4. Verificar y hacer commit. "Ejecuta toda la batería de tests, el comprobador de tipos y el linter. Resume qué ha cambiado y qué has verificado."

Muchas herramientas tienen un modo de planificación que impide editar hasta que lo apruebes. Úsalo. En tareas complejas, pide al agente que escriba el plan en un archivo (docs/plans/partial-refunds.md): sobrevive a los reinicios de contexto y sirve también como documentación.

Práctica 3: dale al agente una forma de verificar su trabajo

Los agentes rinden muchísimo mejor cuando pueden comprobar los resultados por sí mismos. En concreto:

  • Tests rápidos. Asegúrate de que una ejecución de tests acotada tarde segundos. Si la batería completa es lenta, documenta cómo ejecutar un solo archivo o test.
  • Test primero para el comportamiento nuevo. Pide al agente que escriba tests que fallen, que confirme que fallan, que haga commit y que después implemente hasta que pasen. Así se evita el fallo clásico en el que el agente "arregla" el test para que coincida con el código defectuoso.
  • Comprobador de tipos y linter como parte de la definición de terminado.
  • Feedback visual para la interfaz. En frontend, una herramienta de automatización del navegador o una captura de pantalla permiten al agente comparar su resultado con el diseño.
  • Scripts de reproducción para bugs. "Escribe un script que reproduzca el bug, confirma que falla y después arréglalo."

Profundizo en la generación de tests en tests unitarios generados con IA.

Práctica 4: gestiona el contexto de forma deliberada

Las sesiones largas se degradan. El contexto se llena de contenidos de archivos desactualizados, intentos fallidos y salida de herramientas, y la atención del modelo a las primeras instrucciones disminuye. Hábitos prácticos:

  • Una tarea por sesión. Limpia el contexto entre tareas no relacionadas.
  • Señala los archivos explícitamente en lugar de pedirle al agente que "eche un vistazo".
  • Usa subagentes para investigar. Muchas herramientas pueden lanzar un subagente con un contexto limpio para investigar una pregunta y devolver solo la conclusión (subagentes de Claude Code). Así el contexto principal se mantiene enfocado.
  • Compacta o resume cuando una sesión se alarga y reinicia desde el archivo de plan si baja la calidad.

Los principios de fondo están en context engineering para agentes de IA.

Práctica 5: configura los permisos que darías a un contratista nuevo

Un agente con acceso a la shell puede hacer todo lo que puede hacer tu cuenta de usuario. Configura los permisos explícitamente:

Acción Valor por defecto recomendado
Leer archivos del repositorio Permitir
Editar archivos del repositorio Permitir, revisar el diff
Ejecutar tests, linters, comprobador de tipos Permitir
Instalar dependencias Preguntar
git commit Permitir en ramas de feature
git push, abrir PR Preguntar
Llamadas de red, curl, CLIs de la nube Preguntar o denegar
Clientes de base de datos, scripts de despliegue Denegar
Leer .env, ~/.ssh, archivos de credenciales Denegar

Ejecuta los agentes en un contenedor o una VM de desarrollo cuando trabajen sin supervisión, sobre todo en modos "YOLO" que se saltan las confirmaciones. Recuerda que el agente puede leer contenido no confiable —texto de issues, páginas web, READMEs de dependencias— que contenga instrucciones. Eso es prompt injection, y las defensas son de arquitectura; consulta seguridad de agentes de IA.

Los hooks son otra palanca: scripts deterministas que se ejecutan antes o después de las llamadas a herramientas, por ejemplo para pasar el formateador tras cada edición o bloquear escrituras en rutas protegidas (hooks de Claude Code). Los hooks imponen reglas que el modelo podría olvidar.

Práctica 6: mantén los diffs revisables

El agente escribe código más rápido de lo que tú puedes revisarlo. Protege tu capacidad de revisión:

  • Acota las tareas. "Añade reembolsos parciales a la API" es mejor que "mejora el módulo de pagos".
  • Pide commits pequeños y separados lógicamente. Los renombrados mecánicos en un commit, los cambios de comportamiento en otro.
  • Prohíbe las refactorizaciones de paso en el archivo de instrucciones: "No refactorices código no relacionado con la tarea."
  • Revisa como si lo hubiera escrito una persona. Lee cada línea de los cambios no mecánicos. Comprueba el manejo de errores, los casos límite y si los tests prueban realmente el comportamiento.
  • Pide al agente que revise su propio diff con un contexto limpio antes de hacerlo tú. Detecta un número sorprendente de problemas; consulta revisión de código con IA.

Práctica 7: conoce dónde tienen dificultades los agentes

Los agentes son excelentes en trabajo bien especificado y verificable: migraciones, añadir endpoints que siguen patrones existentes, escribir tests, arreglar builds rotos, explicar código desconocido. Tienen dificultades con:

  • Requisitos ambiguos. Elegirán una interpretación y la defenderán con seguridad.
  • Decisiones de diseño transversales. Elegir una arquitectura exige compromisos que solo tú conoces.
  • Problemas de concurrencia y rendimiento que necesitan mediciones, no razonamiento.
  • Archivos enormes y código generado que no caben cómodamente en el contexto.
  • Tareas sin feedback, como código que solo se ejecuta en producción.

En estos casos, usa el agente como asistente de investigación —"encuentra todos los sitios donde bloqueamos esta tabla"— y deja las decisiones en manos humanas.

Práctica 8: ejecuta agentes en paralelo, con cuidado

Cuando un equipo confía en su flujo de trabajo, los agentes en paralelo resultan atractivos: varias sesiones trabajando en tareas independientes en worktrees de Git o sandboxes en la nube separados. Funciona cuando las tareas son realmente independientes y cada una tiene su propia verificación. Falla cuando los agentes tocan los mismos archivos o cuando las revisiones se acumulan. Empieza con dos sesiones en paralelo, no con diez. Para agentes en segundo plano lanzados desde issues o CI, consulta agentes de IA en CI/CD.

Una plantilla de sesión

Task: Support partial refunds for card payments (issue #482).

Context:
- Refund logic: lib/payments/refunds.ts, tests in lib/payments/__tests__/
- Provider API docs: docs/providers/stripe-refunds.md
- Constraint: amounts are integers in minor units

Process:
1. Read the files above and summarise the current refund flow. Stop.
2. After my approval, write failing tests for partial refunds. Stop.
3. Implement until tests pass. Run `pnpm test lib/payments` and `pnpm tsc --noEmit`.
4. Summarise changes and anything you were unsure about.

Preguntas frecuentes

¿Deberían usar agentes los perfiles junior? Sí, con barandillas: deben ser capaces de explicar cada cambio en la revisión. Los agentes son grandes tutores cuando se les pregunta "por qué", y malos cuando solo se usan para producir resultados.

¿Cómo evitamos que el agente cambie los tests para que pasen? Haz commit de los tests primero, indica en el archivo de instrucciones que los tests son la especificación y revisa los diffs de tests por separado.

¿Qué modelo debería usar el agente? El más capaz para planificar y para cambios complejos; uno más rápido y barato para ediciones mecánicas si la herramienta permite cambiarlo. Consulta cómo elegir un LLM.

¿Es seguro dejar que un agente trabaje sin supervisión? Solo en un entorno aislado sin credenciales de producción, en una rama y con el resultado pasando por la revisión habitual.

Fuentes

  1. Anthropic. Claude Code best practices for agentic coding.
  2. Anthropic. Building effective agents.
  3. Yang et al. (2024). SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering.
  4. Yao et al. (2022). ReAct: Synergizing Reasoning and Acting in Language Models.
  5. Anthropic. Documentación de Claude Code: subagentes y hooks.
  6. AGENTS.md — un formato abierto para guiar a los agentes de programación.