# Regla: Consultar Context7 antes de generar código con dependencias externas

Esta regla es OBLIGATORIA para todo agente o skill del sistema SWL que
genere código que use librerías, frameworks, SDKs o APIs externas. La regla
se carga automáticamente para los agentes de stack (`backend-*-swl`,
`frontend-*-swl`, `mobile-*-swl`, `implementador-swl`, `llm-apps-swl`,
`pagos-swl`, `datos-swl`) y para skills de implementación.

---

## Por qué existe esta regla

El conocimiento del modelo sobre librerías de terceros tiene fecha de
corte. Una librería que en el corte estaba en la versión X y era la
recomendación, hoy puede estar:

- En una versión Y mayor con cambios incompatibles
- Deprecada y reemplazada por otra librería
- Con vulnerabilidades conocidas que requieren un parche
- Renombrada o migrada a otra organización

Generar código sin verificar la versión actual genera tres clases de
defectos en producción:

1. **Imports a APIs deprecadas** que arrastran warnings o se eliminan
   en próximas versiones (ejemplo histórico: `@xenova/transformers`
   migrado a `@huggingface/transformers`).
2. **Dependencias transitivas obsoletas** que el usuario ve como
   warnings al instalar (ejemplo: `prebuild-install@7.1.3` arrastrada
   por una librería que el sistema eligió sin verificar la salud).
3. **Vulnerabilidades CVE conocidas** que están parchadas en versiones
   más nuevas que el modelo no conoce.

Context7 (MCP `mcp__claude_ai_Context7__query-docs` y
`mcp__claude_ai_Context7__resolve-library-id`) provee documentación
actualizada de librerías y frameworks. Su uso es la primera línea de
defensa contra estos tres problemas.

---

## Cuándo consultar Context7 (OBLIGATORIO)

Antes de:

1. **Agregar una nueva dependencia** a `package.json`, `requirements.txt`,
   `pom.xml`, `Cargo.toml`, `go.mod`, `composer.json`, `Package.swift` o
   equivalente.
2. **Generar código que importe o use una librería externa** que no
   estaba ya en uso en el proyecto, aunque la librería ya esté
   instalada.
3. **Actualizar la versión** de una dependencia existente.
4. **Migrar de una librería a otra** alternativa (ej.
   `axios` → `fetch`, `moment` → `date-fns`, `jest` → `vitest`).
5. **Resolver un warning de deprecación** de una dependencia
   transitiva.
6. **Implementar un patrón nuevo** del framework (ej. Server Actions
   en Next.js, Signals en Angular, Suspense en React) — la API
   correcta cambia rápido.

NO es necesario consultar Context7 cuando:

- La librería es interna al proyecto SWL (`scripts/lib/*`,
  `hooks/lib/*`).
- Es la biblioteca estándar del lenguaje (Node `fs`, Python `os`).
- Es código que no usa dependencias externas (algoritmos, lógica de
  negocio sin librerías de terceros).
- El cambio es trivial (renombrar variable, formatear).

---

## Cómo consultar Context7

El MCP de Context7 expone dos herramientas principales:

```
mcp__claude_ai_Context7__resolve-library-id(libraryName)
  → Resuelve un nombre de librería (ej. "react", "next.js") al ID
    canónico que Context7 usa internamente.

mcp__claude_ai_Context7__query-docs(library, topic, version?)
  → Devuelve documentación actualizada de la librería sobre el
    topic específico. Acepta versión opcional.
```

Flujo típico:

1. Resolver el ID de la librería:
   ```
   const id = mcp__claude_ai_Context7__resolve-library-id({
     libraryName: "next.js"
   });
   ```

2. Consultar el tema específico:
   ```
   const docs = mcp__claude_ai_Context7__query-docs({
     library: id,
     topic: "Server Actions",
     version: "16"
   });
   ```

3. Verificar:
   - ¿La librería sigue siendo la recomendada o está deprecada?
   - ¿Hay una alternativa migrada que deberíamos usar?
   - ¿La API que voy a generar es la actual o cambió?
   - ¿La versión que recomienda Context7 coincide con la del
     `package.json` del proyecto?

---

## Reglas estrictas

### NUNCA agregar dependencia sin verificar

Antes de escribir `npm install <paquete>`, `pip install <paquete>`,
`go get <paquete>` o equivalente:

- Consultar Context7 para confirmar que la librería sigue activa.
- Confirmar la versión más reciente compatible con el resto del
  stack del proyecto.
- Si Context7 reporta deprecación, **NO la uses**. Buscar la
  alternativa migrada.

### NUNCA generar código con API obsoleta

Si el usuario pide implementar X usando librería Y:

- Consultar Context7 sobre cómo se hace X en la versión actual de Y.
- Si la API que aparece en el contexto del modelo difiere de la que
  Context7 reporta como actual, **usar la de Context7**.
- Documentar en un comentario corto la versión consultada y la
  fecha si la API es notable.

### NUNCA copiar ejemplos de la web sin verificar versión

Stack Overflow, blogs y tutoriales tienen alta probabilidad de
mostrar código deprecado. Si el agente consulta una web (vía
WebSearch o WebFetch) y obtiene un ejemplo, ese ejemplo debe
validarse contra Context7 antes de incorporarlo.

---

## Excepción: Context7 no responde o no tiene la librería

Si Context7 no tiene documentación disponible para una librería
específica:

1. **Documentar en el código** que Context7 no respondió y la API se
   tomó de la fuente oficial (npm registry, docs del repo).
2. **Verificar al menos**: la librería existe, no está deprecada en
   npm/PyPI, su última publicación es reciente (≤ 12 meses).
3. **NO bloquear** el flujo del usuario por este caso — proceder con
   diligencia razonable.

---

## Auditoría retroactiva

Esta regla aplica también al código existente del proyecto SWL:

- Si durante un refactor se detecta una dependencia que arrastra
  warnings de deprecación, abrir un ticket para auditarla con
  Context7 y migrar si hay alternativa actual.
- El comando `/swl:auditar-deps` (cuando esté disponible) debe
  cruzar las dependencias del proyecto contra Context7 para
  detectar deprecaciones silenciosas.

---

## Aplicabilidad por agente

| Agente | Aplica | Cuándo |
|---|---|---|
| `backend-python-swl` | SÍ | Al generar código FastAPI/Django/SQLAlchemy |
| `backend-node-swl` | SÍ | Al generar código Express/Fastify/NestJS |
| `backend-java-swl` | SÍ | Al generar código Spring Boot/JPA |
| `backend-go-swl` | SÍ | Al generar código Go con frameworks |
| `backend-rust-swl` | SÍ | Al generar código Axum/Actix |
| `backend-csharp-swl` | SÍ | Al generar código ASP.NET Core |
| `frontend-react-swl` | SÍ | Al generar código React/Next.js |
| `frontend-angular-swl` | SÍ | Al generar código Angular |
| `frontend-css-swl` | SÍ | Al usar PostCSS/Tailwind plugins |
| `frontend-tailwind-swl` | SÍ | Al usar Tailwind v4+ APIs |
| `frontend-swl` | SÍ | Al usar Vue/Svelte/Lit |
| `mobile-android-swl` | SÍ | Al usar Jetpack Compose libs |
| `mobile-ios-swl` | SÍ | Al usar SwiftUI/Combine |
| `mobile-cross-swl` | SÍ | Al usar React Native/Flutter |
| `implementador-swl` | SÍ | Generalista — siempre |
| `llm-apps-swl` | SÍ | LangChain, OpenAI SDK, Anthropic SDK |
| `pagos-swl` | SÍ | Stripe SDK actualizado |
| `datos-swl` | SÍ | ORMs y drivers de BD |
| `arquitecto-swl` | RECOMENDADO | Al evaluar tradeoffs entre librerías |
| `revisor-codigo-swl` | RECOMENDADO | Al detectar deps deprecadas en review |
| `revisor-seguridad-swl` | OBLIGATORIO | Al verificar CVEs de dependencias |
| Resto de agentes | NO | No generan código con dependencias externas |

---

## Checklist de consulta Context7

Antes de marcar una tarea como completa:

- [ ] ¿Las dependencias agregadas/usadas se verificaron contra Context7?
- [ ] ¿La versión usada está alineada con la que Context7 reporta como actual?
- [ ] ¿No hay imports de APIs deprecadas según Context7?
- [ ] ¿Las dependencias transitivas conocidas no son warnings de
      deprecación al instalar?
- [ ] Si Context7 no tenía la librería, ¿se documentó el motivo?

---

## Origen de esta regla

Esta regla se formalizó tras observar en la primera instalación pública
de `@saulwade/swl-ses@1.0.0` (2026-04-30) un warning de
`prebuild-install@7.1.3 deprecated` arrastrado por
`@xenova/transformers` que estaba en `optionalDependencies`. La
dependencia se eligió en una iteración anterior sin verificar Context7;
la migración oficial era `@huggingface/transformers`. El warning se vio
en cada `npm install` del paquete distribuido. Resuelto en v1.0.1
eliminando la dependencia opcional y elevando esta regla a obligatoria
para que no se repita.

Memoria asociada: `feedback_usar_context7.md` (preferencia previa del
usuario, formalizada como regla).
