Cómo uso agentes de código con IA en Adobe Commerce

Cada día de trabajo tengo Claude Code y Codex en marcha en una terminal junto al editor. La mayoría de las bases de código de mis clientes son de Adobe Commerce, así que aquí explico cómo funciona ese entorno en ellas, dónde ahorra tiempo y dónde sigo haciendo el trabajo a mano.

Está escrito para dos lectores. Uno es el responsable de la tienda que paga las horas de ingeniería y quiere saber qué cambia. El otro es el líder técnico que decide hasta dónde dejar entrar a los agentes en el repositorio.

Qué entiendo por «asistido por IA»

En mis proyectos, un agente no decide nada por su cuenta. Lee código, ejecuta comandos, propone cambios y escribe borradores. Reviso cada diff antes del commit, y nada llega a producción sin pasar los mismos controles que un cambio hecho por una persona.

El cambio útil es que las partes lentas y mecánicas del trabajo se acortan. Encontrar en qué punto un plugin intercepta un método, leer una semana de exception.log, revisar un módulo con el estándar de código y escribir el quinto test casi idéntico llevan ahora menos tiempo. Así, una parte mayor de las horas pagadas va a las decisiones que requieren experiencia con la plataforma.

Memoria del proyecto en un archivo por tienda

Cada tienda en la que trabajo tiene un CLAUDE.md en la raíz del repositorio. Claude Code lo carga en cada sesión, así que el agente empieza con lo que un ingeniero nuevo necesitaría en su primera semana:

• Edición de Adobe Commerce y versión de PHP, hosting (Adobe Commerce Cloud, Upsun o servidores propios) y cómo acceder a cada entorno.
• Qué módulos de terceros están parcheados y dónde están los parches.
• Los comandos que importan: bin/magento setup:di:compile, las suites de tests, los análisis estáticos, cómo limpiar solo las cachés necesarias.
• Las convenciones del proyecto: plugins antes que preferences, nada de SQL directo en controladores, solo esquema declarativo, dónde van los módulos propios.

Este archivo es la mejora más barata de todo el entorno. Sin él, el agente adivina las convenciones y produce código que funciona pero no encaja con la base de código. Con él, el primer borrador suele parecerse a lo que habría escrito el equipo.

Skills y slash commands para el trabajo repetido

El trabajo en Adobe Commerce se repite. Cada módulo nuevo necesita el mismo esqueleto, y cada resolver GraphQL necesita una entrada en el esquema, una clase resolver, la configuración de DI y un test. Cada actualización pasa por la misma checklist.

Claude Code me permite empaquetar cada una de estas tareas como una skill. Una skill es una carpeta con un SKILL.md que describe la tarea, más los scripts o archivos de referencia que necesite. Las skills se pueden versionar en el repositorio bajo .claude/skills/ para que todo el equipo las tenga. Cada una está disponible también como slash command. Las que más uso en proyectos Commerce:

• Esqueleto de módulo. Crea registration.php, module.xml, di.xml y la estructura de carpetas según las convenciones del proyecto.
• Comprobación previa a la actualización. Lista cada plugin, preference y parche que toca clases del core modificadas entre dos versiones, para que la estimación de la actualización parta de hechos.
• Pasada de revisión. Ejecuta PHP_CodeSniffer con el estándar de código de Magento y PHPStan, y resume los hallazgos por riesgo en lugar de por archivo.

Para tareas grandes uso subagentes. Cada uno trabaja en su propia ventana de contexto con su propia lista de herramientas. Un «explorador» de solo lectura puede mapear cómo está personalizado el checkout en decenas de módulos sin llenar la sesión principal de contenido de archivos. A la sesión principal solo llega su resumen.

Hooks que hacen cumplir las normas

El agente puede ignorar una instrucción de CLAUDE.md, pero no puede saltarse un hook. Un hook PreToolUse ejecuta un script antes de que el agente use una herramienta. Si el script termina con código 2, la llamada se bloquea y el agente ve el motivo.

En proyectos Commerce bloqueo la edición de archivos que nadie debería tocar en una rama de funcionalidad:

#!/usr/bin/env bash
# .claude/hooks/protect-paths.sh, registrado como hook PreToolUse para Edit y Write
file=$(jq -r '.tool_input.file_path // empty')
case "$file" in
  */vendor/*|*/app/etc/env.php|*/generated/*|*/pub/static/*)
    echo "Blocked: $file is generated, vendored or environment-specific." >&2
    exit 2 ;;
esac
exit 0

Lo combino con los hooks de pre-commit habituales de git, que comprueban el estándar de código y buscan secretos. Si el agente comete un error, se detecta antes de convertirse en commit.

Tickets y pull requests a través de MCP

El Model Context Protocol (MCP) conecta el agente con sistemas externos mediante pequeños servidores. Uso integraciones MCP con Atlassian (Jira y Confluence) y Bitbucket. En la práctica, puedo empezar una sesión con la clave de un ticket. El agente lee el ticket, la página de Confluence enlazada y el pull request abierto antes de mirar el código.

Sigo dos reglas. La primera es que los permisos son mínimos. El agente actúa con el acceso de mi cuenta y nada más, y apruebo yo cada acción que escribe en un sistema del cliente. La segunda es que la configuración MCP del proyecto está en .mcp.json dentro del repositorio, para que cualquiera del equipo pueda verla y revisarla.

Análisis de logs

Aquí el ahorro de tiempo es mayor y menos discutible. En Adobe Commerce, una incidencia en producción suele implicar var/log/exception.log, system.log, los logs del servidor web y, si el cliente lo tiene, New Relic o Datadog. En Adobe Commerce Cloud Pro los logs son por nodo, así que la misma incidencia está repartida en varios archivos.

Le doy al agente los archivos y una ventana de tiempo. Agrupa las trazas repetidas y separa el ruido (un bot que pide una URL eliminada) de la señal (un módulo de pago que agota el tiempo de espera bajo carga). Después señala las líneas de código implicadas. Yo verifico las dos o tres hipótesis que importan. Lo que antes era una tarde de grep y scroll ahora lleva una fracción de ese tiempo, y el resumen escrito va directo al ticket de la incidencia.

Revisión de código y refactorización

Uso agentes para hacer una primera pasada en cada pull request que me piden revisar. El agente busca plugins en métodos críticos, como el renderizado de precios, y controladores de admin sin comprobación de ACL. También busca observers que hacen trabajo que corresponde a un consumidor de cola, y cargas N+1 en colecciones. Marca candidatos; yo decido cuáles son reales.

El otro punto fuerte es la refactorización. Algunas refactorizaciones son mecánicas una vez decidido el diseño objetivo. Es el caso de dividir una clase helper sobredimensionada en servicios, sustituir llamadas a ObjectManager por inyección en el constructor o mover un cron antiguo a un consumidor de RabbitMQ. Yo decido el diseño y el agente hace la edición masiva. La suite de tests y una revisión confirman el resultado.

Dónde lo limito

Tarea	Papel del agente
Diseño de arquitectura e integraciones	Solo investigación; la decisión es mía
Estimaciones y hoja de ruta	Reúne datos; yo estimo
Lógica de pago, impuestos y checkout	Solo borradores, revisados línea a línea
Despliegues y cambios de datos en producción	Ninguno
Comunicación con el cliente	Ninguno

Los agentes hablan con seguridad incluso cuando se equivocan. En una plataforma tan grande como Adobe Commerce, una respuesta plausible sobre cómo se comporta una clase del core a menudo está desactualizada o es inventada. Todo lo que toca dinero, datos personales o el estado de producción lo verifico leyendo el código o ejecutándolo.

Qué significa para un comercio

Una parte mayor de las horas que pagas se dedica a decidir, y menos a buscar en el código y leer logs. Las estimaciones de actualización parten de una lista de conflictos reales en lugar de una suposición. Los informes de incidencias llegan antes y con pruebas, y la revisión de código cubre una parte mayor de cada cambio. Respondo de cada línea que llega a producción.

Si quieres este flujo de trabajo en tu proyecto, o que tu propio equipo lo adopte con seguridad, escríbeme.