Ruta práctica de ingeniería de AI Agents: cómo aprender Codex, Claude Code, MCP y Skills

Aprender AI Agents se vuelve confuso si empiezas por los nombres de los productos.

Codex, Claude Code, Cursor, Gemini CLI, MCP, Skills, Hooks, permisos, sandboxes, memoria a largo plazo y flujos multiagente parecen importantes, pero no resuelven el mismo problema.

La ruta más estable empieza con preguntas de ingeniería: qué debe hacer el agente, qué archivos puede leer o modificar, cómo se valida el resultado y dónde debe detenerse cuando aparece riesgo.

Resumen

La práctica de ingeniería con AI Agents puede aprenderse en siete capas:

• Definición de tareas.
• Contexto del repositorio.
• Ejecución de comandos y validación.
• Acceso a herramientas mediante MCP.
• Flujos reutilizables con Skills, Hooks y reglas del proyecto.
• Permisos, sandbox y auditoría.
• Operación en equipo con PR, CI, rollback y control de costes.

No empieces buscando automatización total.

Primero haz que el agente termine tareas pequeñas de forma fiable dentro de un repositorio. Después añade herramientas. Solo al final tiene sentido hablar de tareas largas o varios agentes.

Para empezar, lee cómo usar Codex en VS Code, luego flujos de revisión con Claude Code y Codex, y más tarde convierte prompts repetidos en Codex Skills.

Para quién es esta ruta

Está pensada para desarrolladores que ya programan y quieren que un agente ayude a corregir bugs, añadir pruebas, revisar dependencias y actualizar documentación.

También sirve a equipos pequeños que quieren procesos repetibles en lugar de trucos personales de prompting.

Si mantienes un blog, una herramienta interna, una CLI, un sitio de documentación o automatizaciones recurrentes, esta ruta ayuda a convertir publicación, traducción, despliegue, reportes y revisiones SEO en procesos controlables.

No está pensada para automatización de producción sin supervisión desde el primer día.

Cuando una tarea toca datos privados, pagos, permisos de cuenta, producción o seguridad, la prioridad debe ser control y trazabilidad.

Capa 1: convertir trabajo en tareas ejecutables

Un agente suele fallar no porque la tarea sea difícil, sino porque el objetivo es ambiguo.

Una buena petición debe decir:

• Qué cambiar.
• Qué no cambiar.
• Cómo validar.
• Cuándo detenerse.
• Qué incluir en el reporte final.

Mal ejemplo:

1

Optimiza este proyecto.

Mejor ejemplo:

1
2
3
4
5

Lee src/auth y tests/auth.
Corrige la inconsistencia del mensaje de error después de un fallo de login.
No cambies el database schema.
Después ejecuta las pruebas relacionadas con auth.
Si faltan dependencias, informa qué falta y no saltes la validación.

En esta capa no necesitas MCP ni un sistema grande de Skills. Necesitas límites de tarea.

Capa 2: separar Codex y Claude Code

Codex funciona bien dentro de un repositorio: leer archivos, modificar código, ejecutar comandos y explicar fallos de pruebas.

Claude Code suele ser cómodo para trabajo largo en terminal, razonamiento con mucho contexto y discusión de diseño.

Cursor es útil para autocompletado, edición local e interacción dentro del IDE.

Si trabajas en VS Code, Codex es un buen primer paso. Si trabajas en terminal, Claude Code puede ser más natural.

Capa 3: dar el contexto correcto

No intentes resolver todo metiendo más texto en el prompt.

Separa el contexto en cuatro tipos:

• Reglas estables: estructura, comandos de prueba, directorios prohibidos y despliegue.
• Contexto de la tarea: logs, pasos de reproducción y archivos relacionados.
• Índice de código: funciones, rutas, dependencias, llamadas y cambios recientes.
• Memoria histórica: decisiones, problemas conocidos y migraciones.

Las reglas estables van en AGENTS.md, CLAUDE.md o documentación.

El contexto de la tarea va en la petición actual.

La estructura del código puede ir a code-review-graph, Serena o codebase-memory-mcp.

Las decisiones históricas caben mejor en ADR, issues o notas cortas.

Para comparar opciones, lee herramientas de memoria de código para AI Agents.

Capa 4: crear un bucle de validación

Sin validación, el agente solo produce texto plausible.

Necesitas validación estática, validación de comportamiento y revisión humana.

1
2
3

git status --short
rg -n "TODO|FIXME" src tests
npm test -- --runInBand

1
2

python -m pytest tests/auth -q
python -m ruff check src tests

Cuanto más claro sea el comando de validación, menos espacio hay para excusas.

Capa 5: añadir MCP solo cuando hacen falta herramientas

MCP resuelve acceso a herramientas: navegador, documentación, índices de código, bases de datos, archivos Office y sistemas internos.

Empieza con herramientas de solo lectura.

Después añade escrituras de bajo riesgo, como borradores o archivos temporales.

Deja para el final despliegues, escrituras en base de datos, APIs externas y correo.

MCP ayuda cuando el agente no encuentra archivos, debe consultar documentación oficial, validar una página en navegador, leer Word/Excel/PDF o usar un protocolo común para varias herramientas.

No arregla tareas mal definidas, proyectos sin pruebas ni permisos ambiguos.

Capa 6: convertir repetición en Skills

Skills guardan la forma de hacer una tarea repetida.

No son una mejora del modelo.

Sirven para crear artículos Hugo, sincronizar traducciones, desplegar, respetar cooldown SEO, transcribir vídeos o generar reportes con formato fijo.

No escribas una Skill para una tarea única.

Tampoco escribas Skills antes de haber probado el flujo manualmente.

Empieza con reglas pequeñas que eviten errores fijos y ajusta después de usos reales.

Capa 7: hacer recuperables las tareas largas

Las tareas largas se interrumpen.

Guarda objetivo actual, pasos completados, pasos pendientes, rutas importantes, comandos ejecutados, resultados de validación, riesgos abiertos y siguiente punto de entrada.

Para más detalle, lee cómo recuperar tareas largas interrumpidas.

Límites de seguridad

Cuando un agente puede ejecutar comandos, el riesgo no es solo una respuesta incorrecta.

Puede editar archivos, tocar secretos, llamar servicios externos o escribir datos sensibles en logs.

En local, revisa git status --short, evita comandos destructivos automáticos, no borres directorios desconocidos, no pongas secretos en prompts ni logs, y conserva aprobación humana para producción.

En equipo, usa tokens de mínimo privilegio, limita ramas, expón solo los secrets necesarios en CI, conserva revisión humana de PR y audita logs del agente.

Practicar con un proyecto real

Elige un proyecto pequeño y seguro: blog personal, repositorio de prueba, script interno, sitio de documentación o CLI.

Debe tener Git, entrada clara, al menos un comando de validación, alcance limitado, sin secretos y una forma de volver atrás.

Primero pide al agente que solo lea y explique entrada, validación y archivos relacionados.

Luego deja que cambie una cosa pequeña y reporte qué cambió, por qué, qué no cambió y cómo verificó.

Solo después añade navegador, búsqueda documental o índice de código.

Plan de 30 días

Semana 1: usa una sola herramienta. Lee un módulo, corrige un bug pequeño, añade una prueba, actualiza documentación y escribe una plantilla de tarea.

Semana 2: mejora el contexto. Crea un AGENTS.md corto, compara Codex y Claude Code, prueba code-review-graph, revisa un diff y registra errores.

Semana 3: añade MCP con cuidado. Empieza con lectura, valida una página con navegador, usa un índice de código y escribe reglas de permisos.

Semana 4: convierte procesos en Skills. Crea una Skill, ejecútala en una tarea real, añade manejo de fallos, diseña una plantilla de PR, conecta una comprobación segura en CI y practica rollback.

Cómo medir el progreso

No midas solo si la respuesta suena bien.

Mide duración de tareas, tiempo de revisión humana, número de archivos editados, tasa de pruebas correctas en el primer intento, retrabajo, fallos por contexto, permisos, herramientas o capacidad del modelo.

La buena señal es que el alcance se vuelve más claro, la validación más estable, las reglas más cortas y las Skills menos numerosas pero más precisas.

Orden de lectura

• Codex en VS Code
• Cómo escribir Codex Skills
• Recuperar tareas largas de AI Agents
• Revisión de código con Claude Code y Codex
• Cómo usar code-review-graph
• API local LLM para Codex

Ruta final

La ingeniería de AI Agents no empieza buscando el modelo más fuerte.

Empieza haciendo que una tarea pequeña termine de forma fiable.

Aprende tarea, contexto, validación, MCP, Skills, permisos, CI y costes en ese orden.

Cuando cada capa tiene cierre, Codex, Claude Code, MCP y Skills dejan de ser nombres sueltos y se convierten en un sistema de trabajo.