AGENTS.md + Claude Skills + ganchos de proyecto: haciendo que los agentes de IA sigan tu arquitectura
La adopción de agentes de inteligencia artificial en el ciclo de desarrollo de software promete acelerar la escritura de código, pero introduce un desafío recurrente: los modelos generativos desconocen la arquitectura específica de cada proyecto. Sin guías explícitas, un asistente como Claude o Cursor puede importar módulos de infraestructura en capas de dominio, llamar a repositorios desde casos de uso o ignorar el patrón Unit of Work. Para equipos que construyen aplicaciones a medida con enfoques como Domain-Driven Design, esta falta de contexto se traduce en re-prompting constante y en una pérdida de las ventajas de la automatización. La solución pasa por combinar tres elementos: archivos de instrucciones estandarizados (AGENTS.md, CLAUDE.md), habilidades reutilizables (skills) y ganchos de proyecto que se ejecuten de forma determinista. Los primeros actúan como memoria persistente del agente, definiendo reglas como «no salvar entidades en el caso de uso» o «los agregados deben registrar eventos automáticamente». Las skills son fragmentos markdown con frontmatter que el LLM puede cargar bajo demanda, explicando por ejemplo cómo funciona el patrón de registro de eventos en una misma transacción. Los ganchos, por su parte, son scripts Node.js puros que se disparan antes de cada escritura o en el pre-commit, validando que el código generado cumpla con las restricciones arquitectónicas. Esta doble capa (instrucciones blandas + validaciones duras) garantiza que incluso cuando el agente eluda una skill, el hook lo detecte. En Q2BSTUDIO aplicamos esta filosofía en proyectos de ia para empresas, donde la integridad de la capa de dominio es crítica para mantener la coherencia del modelo de negocio. La combinación de agentes IA con un sistema de reglas explícitas permite a los equipos centrarse en la lógica de valor sin reescribir la misma arquitectura en cada sesión. Para un proyecto de software a medida con alta complejidad, disponer de un repositorio que incluya tanto el kernel DDD como las instrucciones para todos los asistentes comunes (Cursor, Claude Code, Copilot, Codex) reduce drásticamente el tiempo de onboarding de nuevos desarrolladores y evita que los agentes rompan la separación de capas. Además, al unificar las reglas en un único punto de verdad —por ejemplo, un directorio de skills con formato YAML+markdown— cualquier actualización se sincroniza automáticamente con los archivos de instrucciones de cada herramienta. Este enfoque es especialmente relevante cuando se integran servicios cloud aws y azure, ya que la infraestructura no debe filtrarse en el dominio. También resulta útil en contextos de ciberseguridad, donde una importación incorrecta puede exponer lógica sensible. Y en el ámbito de servicios inteligencia de negocio, donde los casos de uso deben permanecer puros y no contener llamadas a bases de datos externas. Los ganchos de proyecto, además, pueden verificar que no se introduzcan números mágicos o cadenas funcionales largas, manteniendo la legibilidad del código. Un chequeo habitual es el de entidades ORM que no extienden la clase base correcta, un error que en herramientas como MikroORM provoca que los proxies devuelvan valores incorrectos. Al implementar estos hooks como módulos ESM puros, sin dependencias externas, se garantiza que funcionen en cualquier sistema operativo y dentro de cualquier agente, incluso en acciones CI. La auditoría en pre-commit complementa la validación en tiempo de escritura, cubriendo tanto a los agentes que respetan los hooks como a aquellos que los omiten mediante herramientas externas. En Q2BSTUDIO, cuando desarrollamos soluciones de inteligencia artificial para automatización de procesos, utilizamos estas mismas prácticas para asegurar que los agentes generen código que respete la arquitectura definida, evitando costosos refactors. Los equipos que adoptan DDD por primera vez encuentran en esta estructura una referencia que compila y que les enseña el patrón mientras codifican. Los profesionales senior, por su parte, recuperan la semana que antes dedicaban a cablear infraestructura antes de la primera funcionalidad. El resultado es un ecosistema donde el desarrollador define las reglas una vez y el agente las sigue de forma consistente, permitiendo escalar la productividad sin sacrificar la calidad arquitectónica. Para empresas que buscan implementar agentes IA en sus pipelines de desarrollo, contar con un repositorio base que incluya tanto el kernel técnico como la orquestación de instrucciones es la diferencia entre una automatización caótica y una asistencia confiable. La inversión inicial en configurar skills y hooks se amortiza rápidamente con cada nuevo feature o con la incorporación de un nuevo miembro al equipo. Además, este patrón se extiende de forma natural a herramientas de inteligencia de negocio como Power BI, donde los casos de uso deben permanecer desacoplados de los adaptadores de visualización. En definitiva, la combinación de AGENTS.md, skills y ganchos de proyecto no es solo una moda técnica, sino una necesidad para cualquier organización que quiera aprovechar la IA generativa en el desarrollo de aplicaciones a medida manteniendo el control sobre la arquitectura.
Comentarios