Kanji
・Ingeniero Cloud / Freelance ・Nacido en 1993 ・De Ehime / Residente en Shibuya, Tokio ・5 años de experiencia en AWS Detalles del perfil
Índice
En mi flujo de trabajo diario de ingeniería de software, yo orquesto múltiples agentes de codificación de IA de forma simultánea: Google Antigravity, Anthropic Claude Code, Kiro y OpenAI Codex. Sin embargo, el cuello de botella más frustrante con el que me topé una y otra vez fue «el colapso de las definiciones de reglas y la deriva de instrucciones entre distintos entornos de agentes» .
Al principio asumí que bastaba con redactar pautas exhaustivas de codificación y restricciones de seguridad en un único archivo AGENTS.md o CLAUDE.md para que todas las herramientas actuaran con inteligencia. No obstante, a medida que mis proyectos crecieron hasta convertirse en arquitecturas empresariales multirrepositorio, me enfrenté a graves fallos operativos:
AGENTS.md
CLAUDE.md
git push origin main
En este análisis profundo comparto los patrones arquitectónicos forjados en producción con los que resolví estos problemas en los cuatro principales agentes de IA.
Delimitaremos con precisión qué constituye la Base Universal (estándares abiertos aplicables en cualquier herramienta) frente a los Superpoderes Especializados (extensiones específicas de cada proveedor) , culminando en una Arquitectura de Reglas Federadas (Federated Rules Architecture) probada en entornos reales.
Al redactar instrucciones para agentes, los equipos de ingeniería suelen caer en tres trampas clásicas.
Intentar documentar convenciones de pruebas, formatos de mensajes de commit, versiones obsoletas de librerías y políticas IAM en la nube dentro de un único archivo raíz de instrucciones.
Dado que los agentes inyectan ese documento completo en la ventana de contexto en cada llamada a herramientas, un monolito de 1.000 líneas drena el presupuesto de tokens y satura el mecanismo de atención del modelo, multiplicando exponencialmente el olvido de instrucciones clave.
Mantener archivos CLAUDE.md y AGENTS.md separados mediante copiado manual. Inevitablemente, uno se actualiza mientras el otro queda obsoleto, generando órdenes contradictorias y regresiones destructivas en el código.
Confiar únicamente en texto descriptivo en lenguaje natural para impedir operaciones de alto riesgo ( «No ejecutes comandos peligrosos» ). Como los LLM son modelos probabilísticos, los prompts pueden verse desplazados durante razonamientos complejos de varios pasos. Las restricciones críticas deben aplicarse mecánicamente mediante hooks, permisos o sandboxes, jamás mediante prosa cortés.
Así es como los cuatro principales agentes de codificación procesan y cargan sus reglas operativas:
~/.gemini/config/rules/*.md
<repo>/AGENTS.md
~/.kiro/steering/*.md
.kiro/steering/*.md
~/.claude/rules/*.md
~/.codex/AGENTS.md
AGENTS.override.md
config.toml
glob
model_decision
manual
#[[file:...]]
@ruta/al/archivo
settings.json
Independientemente de la herramienta que utilice, tres principios arquitectónicos resultan universales:
Siguiendo la filosofía /etc/ → ~/.config/ → ./ , las instrucciones del agente deben fluir de lo general a lo específico, donde la configuración local del espacio de trabajo siempre prevalece sobre la configuración global :
/etc/
~/.config/
./
~/.gemini/config/rules/
~/.claude/rules/
./AGENTS.md
./src/api/AGENTS.md
Mantenga los archivos AGENTS.md raíz por debajo de 150 a 200 líneas . Aplique esta prueba de fuego a cada oración: > «Si elimino esta línea, ¿cometerá el agente un error catastrófico o irreversible?»
Pode cualquier regla que linters, formateadores o verificadores de tipos ya impongan automáticamente. Conserve únicamente las particularidades no obvias del proyecto y los comandos exactos de compilación.
Nunca incruste manuales extensos de despliegue ni scripts de migración de múltiples pasos dentro de los archivos de reglas: - Reglas ( AGENTS.md ) : Restricciones invariantes, límites y criterios de evaluación. - Skills ( SKILL.md ) / Runbooks : Procedimientos operativos paso a paso que se cargan bajo demanda únicamente cuando se necesitan.
SKILL.md
Incluso cuando los equipos comprenden la cascada de 3 niveles, el tropiezo de ingeniería más habitual es el diseño de los límites de alcance : «¿Qué instrucciones exactas deben ir en la configuración global del usuario y cuáles dentro del repositorio?»
En mis primeras etapas yo mismo cometí el error de guardar configuraciones de un proyecto concreto en el ámbito global por comodidad —provocando despliegues accidentales o fallos de credenciales al cambiar de cliente—, o bien confirmar rutas locales de mi Mac en el repositorio rompiendo el entorno de mis compañeros.
Esta es la matriz de límites de alcance en producción que yo aplico estrictamente en todos mis flujos empresariales con agentes:
~/.gemini/...
./.agents/...
features/
components/
/tmp
npm run build
pytest
npm run dev
tsc --noEmit
ruff check
SPONSORED
feat:
fix:
git worktree
develop
main
Cuando estas fronteras se desdibujan, los agentes introducen inevitablemente errores sutiles y fricción operativa:
Codificar identificadores específicos de un proyecto —como AWS_PROFILE=client-prod o rutas absolutas del tipo /Users/user01/workspace/client-a/... — dentro de archivos globales ( ~/.gemini/config/rules/ o ~/.claude/rules/ ). Al cambiar a un repositorio personal o al código de otro cliente, el agente intenta invocar inconscientemente las credenciales del cliente A, provocando fallos de permisos o, en el peor de los casos, desplegando código en la infraestructura equivocada .
AWS_PROFILE=client-prod
/Users/user01/workspace/client-a/...
Confirmar rutas locales de la máquina ( file:///Users/kanji/... ), alias SSH privados o credenciales personales directamente en el AGENTS.md del repositorio. En el instante en que los pipelines de CI/CD (GitHub Actions), contenedores Docker o compañeros en Windows clonan o actualizan el repositorio, las compilaciones automatizadas fallan de inmediato por rutas inexistentes, mientras la estructura interna de la máquina privada queda expuesta para siempre en el historial de Git .
file:///Users/kanji/...
Atiborrar las reglas globales con buenas prácticas especializadas de todas las tecnologías imaginables (Next.js, Python, Terraform, Docker, Go, Rust, Tailwind) pensando que «algún día podrían servir» . El agente arranca cada sesión cargando más de 10.000 tokens irrelevantes —incluso para escribir un script de shell de una sola línea—, asfixiando su ventana de atención y disparando la probabilidad de alucinaciones .
Cada vez que redacto una regla nueva, la someto a estas dos preguntas rápidas:
Cuando una regla es útil en múltiples proyectos pero solo aplica durante tareas concretas (por ejemplo, convenciones de nombres en Terraform), utilizo trigger: glob: "**/*.tf" en Antigravity o el Steering condicional de Kiro. Así la regla reside en el ámbito global, pero solo se inyecta en el contexto cuando se abren archivos que coinciden con el patrón .
trigger: glob: "**/*.tf"
Una vez consolidada la base universal, podemos exprimir las extensiones propias de cada fabricante para obtener la máxima ventaja operativa.
La capacidad más destacada de Antigravity es la activación granular por frontmatter en ~/.gemini/config/rules/*.md :
--- trigger: glob globs: "**/*.tf, **/*.tfvars, infra/**/*.yaml" description: Terraform naming conventions and provider requirements --- # Infrastructure Rules - Resource names must include environment prefixes (prd, stg, dev).
Combinando glob y model_decision , las tareas de desarrollo frontend jamás se contaminan con pesadas reglas de infraestructura o migración.
Kiro permite incrustar dinámicamente el contenido de archivos reales dentro de los documentos de Steering sin duplicar código:
# API Response Contract All error payloads must strictly comply with our central schema: #[[file:src/types/api_errors.ts]]
Cuando el esquema subyacente cambia, el contexto del agente se sincroniza de forma automática. Además, /context show permite inspeccionar en tiempo real qué reglas están activas en la sesión.
/context show
Cuando existe un archivo CLAUDE.md en la raíz del repositorio, Claude Code le otorga prioridad sobre AGENTS.md . Aunque muchos ingenieros en macOS y Linux recurren al atajo local de crear un enlace simbólico ( CLAUDE.md -> AGENTS.md ), esto introduce un fallo silencioso catastrófico en equipos multiplataforma o entornos empresariales con Windows.
CLAUDE.md -> AGENTS.md
En sistemas Windows, Git desactiva los enlaces simbólicos de forma predeterminada ( core.symlinks = false ). Cuando un desarrollador en Windows clona un repositorio que contiene dicho symlink, CLAUDE.md no se materializa como un enlace válido, sino como un archivo de texto plano de 9 bytes que contiene literalmente la cadena "AGENTS.md" . Claude Code ingiere en silencio ese fragmento de 9 bytes como si fuera todo el conjunto de instrucciones sin emitir ninguna advertencia, eliminando en la práctica todas las reglas de seguridad y directrices arquitectónicas en absoluto silencio.
core.symlinks = false
"AGENTS.md"
Sintaxis nativa de inclusión @AGENTS.md (Recomendado) Confirme CLAUDE.md como un archivo ligero de texto plano encabezado por una directiva de importación @ :
@AGENTS.md
@
@AGENTS.md # Claude-Specific Directives - (Añada aquí únicamente comportamientos exclusivos de Claude o roles de subagentes)
Al tratarse de texto Markdown estándar, funciona de manera determinista en Windows, macOS, Linux y ejecutores de CI en contenedores.
Respaldo sin configuración (omitir CLAUDE.md por completo) Claude Code recurre de forma nativa a leer AGENTS.md siempre que CLAUDE.md no exista. Si su proyecto no requiere instrucciones exclusivas para Claude, mantener un único AGENTS.md es el patrón más limpio y libre de mantenimiento.
Adicionalmente, imponga los límites innegociables de forma mecánica mediante hooks deterministas PreToolUse en .claude/settings.json en lugar de pedirlo por favor en el prompt:
PreToolUse
.claude/settings.json
{ "hooks": { "PreToolUse": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "python3 scripts/secret_guard.py" } ] } ] } }
Trampa de producción 1: Evite el «autobloqueo» en los hooks PreToolUse Al escanear secretos (como claves de OpenAI o Anthropic) en hooks previos a la ejecución de herramientas, el uso de expresiones regulares ingenuas sin límites de palabra (como sk-[A-Za-z0-9_-]+ ) dispara falsos positivos sobre texto normal en kebab-case dentro de Markdown (por ejemplo, risk-assessment-workflow... ). Devolver el código de salida 2 ante estas falsas alarmas provoca que Claude Code bloquee todas las herramientas posteriores , encerrando al agente en un bucle del que ni siquiera puede salir leyendo o editando archivos para corregir el fallo. Exija siempre límites de palabra estrictos ( \b ) y asegúrese de excluir de forma segura los archivos .env de desarrollo local y los mocks de prueba bajo un diseño fail-open .
sk-[A-Za-z0-9_-]+
risk-assessment-workflow...
\b
.env
Trampa de producción 2: Protección contra sobrescrituras accidentales ( install.py ) Al distribuir paquetes estandarizados de reglas en una organización de ingeniería, los comandos cp manuales suelen sobrescribir sin previo aviso los archivos AGENTS.md o CLAUDE.md existentes del equipo. Utilizar un script instalador automatizado ( install.py ) que respalde las reglas previas en .bak antes de escribir garantiza una adopción fluida y sin pérdidas.
install.py
cp
.bak
En grandes monorrepositorios, Codex permite aislar subpaquetes colocando un archivo AGENTS.override.md . Esto detiene el recorrido hacia directorios superiores y ofrece al agente un contexto limpio y despejado. Tenga también presente el límite predeterminado de 32 KiB en Codex ( project_doc_max_bytes en config.toml ) para evitar truncamientos silenciosos al final del documento.
project_doc_max_bytes
Esta es la estructura de repositorio estandarizada que yo utilizo para coordinar los cuatro agentes sin conflictos:
my-project/ ├── AGENTS.md # [SSOT] Reglas centrales universales (< 200 líneas) ├── CLAUDE.md # Específico de Claude (importación @AGENTS.md, 100 % compatible con Windows) ├── .kiro/ │ └── steering/ # Reglas por patrón de archivo de Kiro y #[[file:...]] ├── .gemini/ (o global) │ └── rules/ # Reglas glob y model_decision de Antigravity ├── .codex/ │ └── config.toml # Límites de bytes y políticas de sandbox de Codex └── .agents/ └── hooks.json # Barreras deterministas PreToolUse / PostToolUse
Gestionar las directrices de los agentes de codificación de IA ha superado con creces la etapa de añadir recordatorios improvisados en un cuadro de texto.
Al cimentar su entorno sobre estos cinco pilares, eliminará las regresiones entre agentes y la fatiga de prompts, desbloqueando un flujo de trabajo de ingeniería multiagente verdaderamente predecible y de alta velocidad.
Guía completa sobre la arquitectura de memoria a largo plazo para agentes de IA (Gen 3): transición ... [Leer más]
Ranking LLM noviembre 2026: SWE-bench (86,8%), Terminal-Bench 4.0, ARC-AGI y precios API ($2/$10) pa ... [Leer más]
A medida que personalizas asistentes de IA como Google Antigravity, las reglas y habilidades pueden ... [Leer más]
Entrene habilidades sociales con llamadas simuladas realistas, retroalimentación en 5 ejes, academia interactiva y fotos de perfil con IA.
Fotografíe recibos para un desglose instantáneo con IA. Conexión directa con LINE para liquidar gastos compartidos sin fricción.
Personajes de IA (Adivina, Mayordomo, Barman) moderan dinámicas y retos en tiempo real para animar cualquier reunión.
Obtén el paquete completo: AGENTS.md universal, hooks.json deterministas, reglas de Git seguras y scripts probados en Antigravity, Kiro, Claude Code y Codex.
