Claude Code a escala: arquitectura de contexto para grandes codebases

¿Por qué necesitás leer esto?

Sos desarrollador y trabajás en un codebase que lleva años creciendo. Veinte módulos. Reglas de negocio que nadie documentó. Workarounds que solo tu equipo entiende. Empezás a usar Claude Code y las primeras tareas salen genial — se siente como magia. Después le pedís algo simple: actualizar un template de email. Un archivo, scope claro, debería tomar minutos.

Lo que genera se ve limpio, profesional. Con un header que tu design system prohíbe. Sin el CTA obligatorio con gradiente rosa. Sin las tres capas de CSS dark mode. El código compila. Viola todas las reglas visuales de tu módulo de email.

Las soluciones obvias aparecen rápido. Escribís un CLAUDE.md más largo. Creás una skill por módulo. Probás agentes dedicados que se especialicen en billing, o email, o auth. Cada approach ayuda — y cada uno choca con su propia pared. El CLAUDE.md se convierte en un archivo de 2.000 líneas que se carga en cada tarea. Las skills se multiplican hasta que mantenerlas es un proyecto en sí mismo. Los agentes especializados necesitan su propio contexto, y estás de vuelta al mismo problema un nivel más arriba.

Ninguno de estos approaches resuelve el problema real: ¿cómo hace el agente para saber lo que necesita saber, cuando lo necesita saber, sin ahogarse en contexto irrelevante?

Después de mucho prueba y error, la respuesta resultó ser casi vergonzosamente simple. Sin frameworks, sin tooling complejo, sin reinventar nada. Simplemente documentar lo que necesita ser documentado, para un agente de IA, donde necesita ser documentado.

La solución: documentar para IA

El patrón se llama IA-docs. Archivos markdown llamados IA-docs.md se colocan en puntos estratégicos del árbol de directorios del codebase. Cada archivo documenta el contexto relevante para ese nivel de la jerarquía. Cuando un agente de IA necesita trabajar en cualquier archivo, lee cada IA-docs.md desde la raíz hasta el directorio objetivo.

Esta es la estructura real de una plataforma SaaS en producción con 20+ módulos:

back-cliencer/
├── IA-docs.md                          # Global: tech stack, reglas DDD, convenciones
├── src/
│   ├── IA-docs.md                      # Capas DDD en detalle, anti-patrones, estructura de módulo
│   └── app/
│       ├── billing/
│       │   └── IA-docs.md              # Integración Stripe, flujo de checkout, price IDs
│       ├── customer-support/
│       │   └── IA-docs.md              # Arquitectura multi-agente AI, patrones LangGraph
│       ├── crm/
│       │   ├── IA-docs.md              # Marketing automation, pasos del journey
│       │   └── emailService/
│       │       └── IA-docs.md          # Anatomía de templates, dark mode, identidad visual
│       ├── games/
│       │   └── IA-docs.md              # Tipos de juego, sistema de premios, configuración
│       ├── analytics/
│       │   └── IA-docs.md              # Tipos de eventos, colecciones, patrones de query
│       ├── auth/
│       │   └── IA-docs.md              # Auth passwordless, gotchas, endpoints deprecated
│       ├── image-generation/
│       │   └── IA-docs.md              # Flujo asíncrono, arquitectura del worker, quota
│       └── ...8 módulos más
├── src/jobs/
│   └── IA-docs.md                      # Schedules de cron, colas de workers, config Redis
└── src/scripts/
    └── IA-docs.md                      # Scripts de migración, operaciones de mantenimiento

El CLAUDE.md raíz define el protocolo como obligatorio:

## Protocolo IA-docs.md (Backend)
 
**ANTES de editar/crear/analizar cualquier archivo en back-cliencer/:**
 
1. Identificar el path del archivo a trabajar
2. **Leer TODOS los IA-docs.md en la jerarquía** desde la raíz del módulo hasta el directorio del archivo
3. Seguir los patrones y reglas documentados
 
**Sin excepciones.** Ni para cambios "simples".

Pero un protocolo que el agente puede ignorar es solo una sugerencia. Un archivo de estado de sesión trackea qué IA-docs ya se leyeron, y un hook de Claude Code verifica — antes de cada edición — que el agente haya cargado el contexto relevante. Más sobre el sistema de enforcement después.

¿Cómo funciona en la práctica?

La idea clave es la carga progresiva de contexto. Cada nivel agrega especificidad sin repetir lo que el padre ya dijo.

Trabajando en src/app/crm/emailService/templates/paymentFailed.template.ts:

Leer en orden:
1. back-cliencer/IA-docs.md           → Tech stack, reglas DDD, convenciones de logging
2. back-cliencer/src/IA-docs.md       → Capas DDD, patrones de controller, validación Zod
3. src/app/crm/IA-docs.md             → Pasos del journey CRM, arquitectura de servicios
4. src/app/crm/emailService/IA-docs.md → Anatomía de templates, reglas dark mode, paleta

Después de leer estos cuatro archivos, el agente sabe:

El proyecto usa TypeScript strict con Express.js y MongoDB
Los controllers usan arrow functions y propagan errores al middleware global
El módulo CRM orquesta tres servicios: Chatwoot, SendGrid y WhatsApp
Los templates de email no llevan header, tienen saludo por nombre, un CTA con gradiente rosa, y tres capas de CSS dark mode

Trabajando en src/app/games/GameApi.ts:

Leer en orden:
1. back-cliencer/IA-docs.md           → Tech stack, reglas DDD
2. back-cliencer/src/IA-docs.md       → Capas DDD, patrones de clase API
3. src/app/games/IA-docs.md           → Tipos de juego, sistema de premios, variantes

Distinto archivo, distinto path, distinto contexto cargado. El agente solo lee lo relevante.

Tips para un mejor diseño

Cada IA-docs.md sigue una estructura consistente, pero el contenido varía según el nivel:

Nivel raíz: el contrato global

# Backend Cliencer - IA-docs (Root)
> Actualizado: 2026-01-10
> Este archivo se lee SIEMPRE que se trabaja en cualquier archivo del backend.
 
## Qué es Cliencer
Descripción de la plataforma, contexto de negocio.
 
## Tecnologías Clave
Runtime, framework, base de datos, stack AI, colas, auth, storage...
 
## Arquitectura DDD (Resumen)
Routes -> Controllers -> APIs -> Domain <- Repositories
 
## Convenciones de Código
TypeScript estricto, patrones de logging, manejo de errores, reglas de documentación.

Nivel source: patrones en detalle

El src/IA-docs.md expande la arquitectura con ejemplos de código reales para cada capa DDD, anti-patrones a evitar, checklists de creación de módulos, y convenciones de nombres. Solo este archivo tiene 300+ líneas de patrones probados en producción.

Nivel módulo: conocimiento específico del dominio

El IA-docs.md de cada módulo contiene lo que solo el desarrollador de ese módulo sabría:

# Auth Module - IA-docs
 
## Gotchas
- **Upgrade de leads**: En signup-with-trial, si el phoneNumber ya existe
  con email @chatwoot.auto, se upgradea el lead en vez de rechazar.
  Solo aplica a leads, no a clientes reales (409 con email masked).
- **Trial lazy Stripe**: signup-with-trial NO crea Stripe customer.
  Se crea cuando el usuario decide pagar.
- **Charset de códigos**: Los magic codes usan A-Z (sin I,L,O,G) y 1-9 (sin 0)
  para evitar confusión visual. 6 chars, expiran en 1h.

Estos son los "gotchas" que le llevarían días descubrir a un desarrollador nuevo. Con IA-docs, el agente los sabe antes de escribir una sola línea.

DDD también funciona para IA

Si practicás Domain-Driven Design — o arquitectura hexagonal, o clean architecture — vas a reconocer algo familiar: cada IA-docs.md define un límite de bounded context.

Cada IA-docs.md incluye una sección "Responsibility" obligatoria. Esta sección declara explícitamente de qué ES y de qué NO ES responsable un módulo:

## Responsibility
Este módulo maneja autenticación de usuarios y gestión de sesiones.
NO maneja autorización (los checks de roles ocurren en el middleware de cada módulo).
NO crea Stripe customers (eso es responsabilidad de billing).

Esto es el bounded context de DDD hecho explícito para el agente de IA. Sin esto, el agente podría asumir razonablemente que el módulo de auth debería crear un Stripe customer durante el signup — después de todo, muchas plataformas SaaS hacen exactamente eso. El IA-docs codifica la decisión de negocio: "signup-with-trial NO crea Stripe customer. Se crea cuando el usuario decide pagar."

La estructura de directorios refleja el modelo de dominio. Los IA-docs a nivel de módulo codifican el lenguaje ubicuo de cada bounded context. Cuando el IA-docs del módulo de games dice "Influencer," significa "usuario final/jugador" — no "influencer de marketing." Esa distinción existe solo en el lenguaje de dominio de este codebase, y el agente solo puede aprenderla de la documentación.

Esto significa que el agente no solo sigue patrones de código. Entiende semántica de dominio. Conoce reglas de negocio que son invisibles en el código: qué módulo es dueño de qué responsabilidad, qué significa la terminología en este contexto específico, y qué integraciones están intencionalmente diferidas. El código por sí solo no puede decirte nada de esto.

¿Cómo puedo empezar a implementarlo?

Empezá con estos tres pasos:

Escribí un IA-docs.md raíz con tu tech stack, decisiones de arquitectura, y convenciones de código. Solo esto va a mejorar cada interacción con IA.
Agregá docs a nivel de módulo para tus módulos más complejos. Los que generan preguntas de los desarrolladores nuevos. Los que tienen "gotchas".
Mandatá el protocolo en CLAUDE.md. Hacelo explícito: antes de editar cualquier archivo, leer la jerarquía de IA-docs. Sin excepciones.

Una vez que lo básico funcione, la siguiente pregunta es: ¿qué pasa si el agente ignora el protocolo?

Haciendo que el agente siga las reglas

El protocolo CLAUDE.md dice "leer todos los IA-docs antes de editar." Pero ¿qué pasa si el agente se lo saltea? Tres hooks de Claude Code forman una red de seguridad que hace imposible saltearlo:

// .claude/settings.json (simplificado)
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "command": ".claude/hooks/enforce-ia-docs.sh" },
          { "command": ".claude/hooks/inject-dev-context.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          { "command": ".claude/hooks/notify-ia-docs-read.sh" }
        ]
      }
    ]
  }
}

enforce-ia-docs.sh (PreToolUse: Edit|Write) — El hook central de enforcement. Antes de cada edición, recorre el árbol de directorios desde el archivo objetivo hasta la raíz del proyecto, encuentra todos los IA-docs.md en el path, y los inyecta como additionalContext en la llamada de la herramienta. El agente no puede editar un archivo sin recibir los IA-docs relevantes primero.

notify-ia-docs-read.sh (PostToolUse: Read) — El hook de deduplicación. Cuando Claude lee explícitamente un archivo IA-docs.md, este hook lo registra en un archivo de estado de sesión. El hook de enforce chequea este estado para evitar inyectar el mismo contenido dos veces.

inject-dev-context.sh (PreToolUse: Edit|Write) — El hook de gold rules. Inyecta principios de arquitectura condensados (diferentes sets para backend vs frontend) en cada edición. No son específicos del módulo — son anti-patrones y convenciones de todo el proyecto destilados en un formato compacto.

Los tres hooks comparten estado a través de un archivo de sesión en /tmp/claude-ia-docs-<session_id>, que trackea qué IA-docs ya fueron inyectados en la sesión actual. Esto evita que el mismo contexto se cargue repetidamente, manteniendo el uso de tokens bajo control.

Desarrollador pide editar archivo
        │
        ▼
  ┌─────────────┐
  │ PreToolUse   │──→ enforce-ia-docs.sh recorre árbol, inyecta IA-docs
  │ Edit|Write   │──→ inject-dev-context.sh inyecta gold rules
  └──────┬──────┘
         │
         ▼
    Edición procede con contexto completo
         │
         ▼
  ┌─────────────┐
  │ PostToolUse  │──→ notify-ia-docs-read.sh trackea lo que se leyó
  │ Read         │
  └─────────────┘

El resultado: el agente no puede editar código sin entender el dominio local. No porque elija seguir el protocolo, sino porque los hooks inyectan el contexto automáticamente.

Mientras los IA-docs llevan conocimiento específico del módulo, las gold rules llevan principios arquitectónicos de todo el proyecto:

Gold rules de backend: límites de capas DDD, patrones de propagación de errores, convenciones de logging, patrones de testing
Gold rules de frontend: estructura de componentes, gestión de estado, patrones de integración con API, convenciones MUI

Son destilaciones condensadas — intencionalmente breves — de los patrones más críticos. El IA-docs de un módulo puede decir "este servicio usa SendGrid," pero las gold rules dicen "todas las llamadas a servicios externos deben ir por la capa de dominio, nunca desde controllers."

Manteniendo la documentación viva

Escribir IA-docs a mano funciona, pero no escala. Dos agentes dedicados manejan la creación y el mantenimiento de los archivos IA-docs.

El agente de creación (`ia-docs-create`)

Cuando un módulo no tiene IA-docs.md, este agente analiza su código fuente y propone uno:

Apunta a 30–60 líneas (80 máx) — suficiente contexto sin ruido
Exige una sección "Responsibility" obligatoria con alcance y límites
Principio central: "Documentar SOLO lo que una IA NO PUEDE inferir leyendo el código directamente"
Usa herramientas de solo lectura (Read, Grep, Glob) — nunca escribe archivos
Corre sobre Sonnet por eficiencia de costo
Propone contenido para revisión humana, nunca commitea directamente

El agente examina imports, jerarquías de clases, definiciones de rutas y lógica de negocio para extraer lo importante. Deliberadamente ignora detalles de implementación que la IA puede leer del código fuente, enfocándose en el "por qué" y los "gotchas."

El agente de actualización (`ia-docs-update`)

Después de semanas de desarrollo, los IA-docs se desvían de la realidad. Este agente detecta qué cambió y propone actualizaciones:

Escanea cambios recientes de git, agrupados por módulo
Evalúa los IA-docs existentes contra el código actual
Propone adiciones, modificaciones, Y remociones (con justificación)
Evalúa bottom-up: módulos más profundos primero, luego padres
Conservador en adiciones, proactivo en remover contenido redundante
También solo lectura — propone cambios para revisión

El ciclo de vida forma un loop cerrado:

Agente de creación propone → Humano revisa → Código evoluciona →
Agente de update evalúa → Propone cambios → Humano aprueba → repetir

Ambos agentes están definidos como task agents de Claude Code con restricciones explícitas. No pueden modificar tu codebase — solo producen propuestas que vos aceptás, modificás o rechazás.

El elenco de soporte

IA-docs es el núcleo, pero tres capas más potencian su valor.

Skills para concerns transversales

Las operaciones específicas de dominio que cruzan módulos (queries de base de datos, operaciones de pago, testing de emails) se encapsulan como skills del agente con sus propias instrucciones:

| Skill     | Cuándo usar                              |
|-----------|------------------------------------------|
| /mongodb  | Queries, buscar clientes, analytics      |
| /stripe   | Suscripciones, pagos, webhooks           |
| /front-dev| Desarrollo frontend (Next.js, MUI)       |

Cada skill contiene queries probadas, reglas de seguridad, y awareness de entorno (producción vs desarrollo).

Tipos como documentación

Las interfaces con JSDoc extensivo sirven como documentación viva que el compilador refuerza:

/**
 * Fecha de expiración del plan.
 *
 * **Uso:**
 * - Planes TRIAL: Fecha fin del período de prueba de 7 días (local, sin suscripción Stripe)
 * - Planes BEAUTY/STORE: NO se usa (las suscripciones Stripe son abiertas)
 *
 * **Control de acceso:**
 * - TRIAL: Se verifica contra esta fecha
 * - BEAUTY/STORE: Controlado por el estado de suscripción en Stripe, NO por este campo
 */
endDate: Date;

El predecesor: archivos HowTo

Antes de que IA-docs existiera como patrón, el mismo instinto se manifestó como archivos "HowTo" — guías markdown viviendo al lado del código que documentaban:

sub-agents/tools/
  HowToCreateTools.md    ← Guía paso a paso con ejemplos
  sendLoginEmail.ts       ← Implementación de referencia
  escalateToHuman.ts      ← Otra implementación de referencia

En la práctica, un archivo HowTo es un IA-docs a un nivel de anidamiento más profundo: instrucciones específicas del dominio viviendo al lado del código que describen. La convención de nombres (HowTo*.md) es anterior a la nomenclatura estandarizada IA-docs.md. La idea era correcta — documentación al lado del código, no en una wiki — y evolucionó hacia el sistema jerárquico descrito aquí.

Qué resuelve — y qué no

Qué resuelve:

Precisión de contexto. El agente carga solo la documentación relevante al path del archivo que está editando — no toda la base de conocimiento del proyecto.
Transferencia de conocimiento de dominio. Gotchas, bounded contexts, decisiones de negocio, y terminología que son invisibles en el código se vuelven explícitas y accesibles.
Ownership escalable. Los dueños de cada módulo mantienen sus propios docs. Nadie se convierte en cuello de botella.
Entendimiento progresivo. Cada nivel de la jerarquía agrega especificidad sin repetir lo que el padre ya dijo.
Onboarding humano y de IA. Desarrolladores nuevos y agentes de IA leen los mismos archivos. Buena documentación para IA es buena documentación, punto.

Qué no resuelve:

Planificación. IA-docs le dice al agente cómo escribir código en tu proyecto. No dice nada sobre qué construir ni en qué orden. Igual necesitás un sistema de planificación o un issue tracker.
Patrones transversales por tipo de archivo. Si necesitás "en todos los archivos de test, seguí este patrón," usá herramientas como .claude/rules/*.md con glob matching. IA-docs se organiza por jerarquía de directorios, no por tipo de archivo.
Estado en tiempo real. IA-docs describe arquitectura y decisiones, no estado del sistema en vivo. No le va a decir al agente qué servicios están caídos o qué feature flag está activo.

Las desventajas honestas

Ningún patrón es perfecto. Esto es lo que aprendí de la manera difícil:

El mantenimiento es trabajo real. Cada vez que la arquitectura cambia, alguien tiene que actualizar los IA-docs. En la práctica, esto significa agregar "actualizar IA-docs" al checklist del PR. Si lo salteas, los docs se desvían de la realidad y se vuelven dañinos en vez de útiles. El agente de update ayuda a detectar el drift, pero igual requiere revisión humana.

La sobre-documentación es una trampa. Algunos módulos necesitan 150 líneas de contexto. Otros necesitan 20. La tentación de ser exhaustivo en todos lados lleva a docs demasiado largos para ser útiles. Mi regla: documentar decisiones que sorprenderían a alguien, saltear todo lo obvio.

El enforcement agrega complejidad. El sistema de hooks automatiza la inyección de contexto, pero introduce su propia superficie de mantenimiento. Los scripts de hooks necesitan mantenerse en sync con la estructura del proyecto, los archivos de estado de sesión necesitan limpieza, y debuggear por qué un hook no se disparó agrega un nivel de indirección. Funciona — el agente genuinamente no puede saltear los IA-docs — pero no es costo cero.

El costo inicial de setup es significativo. Escribir 16 archivos IA-docs desde cero tomó varios días. Para un proyecto nuevo, empezá solo con el archivo raíz y agregá docs a nivel de módulo solo cuando un módulo tenga patrones no obvios que valga la pena documentar. El agente de creación reduce significativamente este costo para codebases existentes.

Docs desactualizados son peores que no tener docs. Un IA-docs.md que dice "usar config.configurable" cuando la API migró a "config.context" va a generar bugs activamente. Poné fecha a cada archivo y revisá trimestralmente.

Por qué esto importa más allá de la IA

La documentación siempre fue importante. READMEs, wikis, architecture decision records — los buenos equipos vienen escribiendo esto hace décadas. Lo que cambió no es el principio. Lo que cambió es la audiencia.

Cuando un agente de IA trabaja en tu codebase, la documentación deja de ser un nice-to-have que los nuevos leen en su primera semana. Se convierte en el sistema operativo de cada cambio de código. El agente que entiende tu dominio produce código correcto. El que no, produce código plausible — que es peor, porque se ve bien hasta que rompe en producción.

Pero acá está la clave: un desarrollador nuevo que se une al equipo lee los mismos IA-docs que lee el agente. Los mismos bounded contexts, los mismos gotchas, los mismos límites de "este módulo hace X, no Y". Buena documentación para IA es buena documentación, punto.

Las herramientas y frameworks van a cambiar. Claude Code puede ser reemplazado por otra cosa el año que viene. El sistema de hooks puede evolucionar. Pero la necesidad de codificar conocimiento de dominio donde se necesita — en el límite de cada contexto, no en un monolito central — eso es atemporal. Es context engineering, e importa sin importar si tu lector es un modelo de IA o un humano con un git clone fresco.

El objetivo no es documentación perfecta. El objetivo es que cualquiera — humano o IA — trabajando en cualquier archivo de tu codebase, entienda el contexto local lo suficiente como para producir código que un reviewer aprobaría en el primer pase.

Ese es el interés compuesto de la documentación jerárquica: cada minuto invertido escribiendo contexto hoy ahorra horas de re-explicar y corregir mañana.

Probalo en tu proyecto

Los hooks, agentes y guía de setup son open source: ia-docs en GitHub.

Dos scripts de bash, dos agentes, cero dependencias más allá de jq. Copialos en tu directorio .claude/ y empezá a escribir tu primer IA-docs.md.