La odisea del contexto

Ejemplo del kernel (L0.md):

# L0 KERNEL (ROOT CONTEXT)

## MISSION

Act as a senior software architect and lead developer. Your goal is to produce maintainable, scalable, and secure code following the project's established patterns. You must orchestrate the loading of specialized contexts (L1) based on the task at hand.

## CRITICAL RULES (THE "NEVER" LIST)

1.  **NEVER** commit secrets or credentials.
2.  **NEVER** bypass the established hexagonal architecture layers.
3.  **NEVER** introduce new dependencies without explicit approval (ADR required).
4.  **NEVER** write "spaghetti code" (high cyclomatic complexity).
5.  **NEVER** ignore linter or type-checker errors.

## L1 CONTEXT MAP (ROUTING TABLE)

| Priority | Pattern (Regex) | L1 Context File | Description | Load Strategy |
| :------- | :-------------- | :-------------- | :---------- | :------------ | --------------- | ------------------------------ | ----------------------------------- | ----------------------------------- | ---- |
| 1        | `/\b(auth       | login           | signup      | session       | jwt             | oauth)\b/i`                    | `L1/Auth.md`                        | Authentication & Security protocols | AUTO |
| 2        | `/\b(db         | database        | prisma      | drizzle       | sql             | migration)\b/i`                | `L1/Database.md`                    | Data persistence & schema rules     | AUTO |
| 3        | `/\b(api        | endpoint        | route       | controller    | trpc            | graphql)\b/i`                  | `L1/API.md`                         | API design & interface standards    | AUTO |
| 4        | `/\b(ui         | component       | tailwind    | css           | front)\b/i`     | `L1/UI.md`                     | User Interface components & styling | AUTO                                |
| 5        | `/\b(test       | spec            | e2e         | mock)\b/i`    | `L1/Testing.md` | Testing strategies & standards | AUTO                                |

## OPERATING PROCEDURE

1.  **Analyze Task:** Read the user's prompt.
2.  **Scan for Patterns:** Match prompt content against the `L1 CONTEXT MAP` regex patterns.
3.  **Load L1 Contexts:** For each match, load the corresponding `L1` file.
    - _NOTE:_ L1 contexts provide domain-specific constraints and patterns.
4.  **Execute:** Perform the task, adhering strictly to L0 rules AND the loaded L1 rules.
5.  **Consult L2 (Optional):** If deep clarification is needed on a specific decision, consult the referenced L2 specs (ADRs) mentioned in the L1 files.

Ejemplo de DCL:

# ==========================================
# DCL (Dynamic Context Language) - Example
# ==========================================
# Domain: Authentication Module
# ==========================================

# Define el contexto global del dominio
@context[domain:auth]:
  # Restricciones estrictas (la IA NUNCA debe hacer esto)
  !constraints:
    - never: [commit_secrets, raw_sql_queries]
    - enforce: [use_orm, secure_password_hashing]

  # Dependencias necesarias para este contexto
  ^dependencies:
    - lib: [bcrypt, jsonwebtoken]
    - service: [user_service, email_service]

  # Procedimientos y patrones a seguir
  ~procedures:
    # Patrón para el registro de usuario
    user_signup:
      - step: validate_input
        desc: "Verificar complejidad de contraseña y formato de email."
      - step: hash_password
        desc: "Usar bcrypt para hash. Nunca guardar en texto plano."
      - step: create_user
        desc: "Llamar a user_service para creación en base de datos."
      - step: generate_token
        desc: "Generar un JWT para la sesión."
      - step: send_welcome_email
        desc: "Llamar a email_service."

    # Patrón para inicio de sesión
    user_login:
      - step: find_user
        desc: "Buscar usuario por email."
      - step: verify_password
        desc: "Comparar hash con bcrypt."
      - step: generate_token
        desc: "Generar un nuevo JWT."

  # Modelos de datos esperados
  #schema:
    User:
      - id: [uuid, pk]
      - email: [string, unique]
      - password_hash: [string]
      - created_at: [datetime]

Ejemplo de archivo con etiquetas de contexto:

// ==========================================
// FILE: src/modules/user/core/application/use-cases/CreateUser.ts
//
// @L1: auth, database, domain-events
// @architect: hexagonal/use-case
// ==========================================

import { User } from "../../domain/User";
import { IUserRepository } from "../../ports/IUserRepository";
// ... otras importaciones

export class CreateUserUseCase {
  constructor(
    private readonly userRepo: IUserRepository,
    // ...
  ) {}

  async execute(command: CreateUserCommand): Promise<Result<User>> {
    // Lógica de negocio...
    // La IA sabe que debe respetar las reglas "auth" y "database"
    // porque fueron declaradas en el encabezado.
  }
}

// ==========================================
// @security: low-risk
// ==========================================

Ejemplo de archivo de contexto (context.ai):

# ==========================================
# LOCATION: src/modules/payment/context.ai
# ==========================================

# Metadatos para el agente
meta:
  domain: payment
  description: "Reglas críticas para el procesamiento de pagos."

# Reglas de carga condicional
# El agente evalúa estas reglas antes de decidir cargar este contexto.
load_if:
  - rule: "Task involves money, transactions, or stripe."
    reason: "High risk domain."
  - rule: "User explicitly mentions 'payment' or 'checkout'."
    reason: "Explicit request."
  - rule: "Files being edited are in 'src/modules/payment/'."
    reason: "Proximity."

# El contexto en sí, cargado solo si se cumple una regla.
context:
  # Restricciones críticas
  constraints:
    - "NEVER log full credit card numbers or CVV."
    - "MUST use the 'PaymentGatewayPort' for all external calls."
    - "All transactions MUST be wrapped in a database transaction."

  # Patrones de implementación
  patterns:
    - name: "Idempotency"
      description: "Ensure payment requests are idempotent using a unique key."

Simulación: el agente con MCP custom en acción

Usuario: “Necesito reembolsar un pago. Es sensible.”

IA (Pensamiento): “Tarea crítica en el dominio payment. No codifico nada sin verificar las reglas.” IA (Acción MCP): fs_scanner.scan("src/modules/payment", look_for=["context.ai"]) IA (Resultado): “Archivo context.ai encontrado.” IA (Acción MCP): context_loader.load("src/modules/payment/context.ai") IA (Pensamiento): “Contexto cargado. Reglas críticas: usar PaymentGatewayPort, envolver en transacción DB. Ok, puedo empezar el plan.”

La arquitectura de la constitución

Una sola fuente de verdad para todos los agentes, cero duplicación.

# Regreso a las bases: Simplicidad
$ ls -l .ai/
-rw-r--r--  1 user  staff  4096 Nov 21 AI.md       # La constitución (fuente única)
# Los alias para la compatibilidad de herramientas. Todos apuntan al mismo archivo.
lrwxr-xr-x  1 user  staff     5 Nov 21 CLAUDE.md -> AI.md
lrwxr-xr-x  1 user  staff     5 Nov 21 CURSOR.md -> AI.md
lrwxr-xr-x  1 user  staff     5 Nov 21 GEMINI.md -> AI.md

Extracto de la constitución (AI.md):

# Constitution

## TL;DR (The "NEVER" List)

**NEVER:**

- Mute lint/type errors (fix root causes)
- Violate layer boundaries (core→npm, application→infrastructure)
- Throw in domain/application (return `Result<T, E>`)

## Principles & Rationale (Drift Prevention)

**Why these rules exist:**

1. **Architecture**: We decouple the _core domain_ from _technology_...
   ...