Claude Code / Codex
Colección de prompts de instrucciones y plantillas

Lee el archivo de instrucciones que tú (este agente) cargas (CLAUDE.md / AGENTS.md, etc.),
señala los puntos débiles que los agentes de IA tienden a ignorar y luego reescríbelo
en una forma eficaz.

Aspectos a revisar:
- Convertir la redacción vaga en imperativos (haz siempre X / nunca hagas Y)
- Añadir una "definición de terminado" y pasos de verificación (ejecutar lint / test)
- Hacer las prohibiciones concretas hasta el objetivo (nombres de directorios, nombres de comandos)
- Si es demasiado largo, recórtalo solo al núcleo que quieres que se cumpla

Primero lista los puntos débiles en viñetas, luego muestra la versión reescrita
completa y aplícala a ese archivo de instrucciones.

Tras identificar los comandos reales de build / test / lint de este repositorio,
añade una sección "Definición de terminado" al archivo de instrucciones que cargas
(CLAUDE.md / AGENTS.md, etc.).

Requisitos:
- Hazla una lista de verificación con la forma "no reportes terminado hasta que se cumplan todos los siguientes puntos"
- Indica explícitamente los comandos reales de lint y test
- Incluye: no dejar TODO ni logs de depuración en los archivos modificados, y releer tu propio diff

No rompas el contenido existente; solo añade la sección.

Detecta automáticamente el lenguaje y el framework de este repositorio, y añade las
reglas de buenas prácticas correspondientes al archivo de instrucciones que cargas
(CLAUDE.md / AGENTS.md, etc.).

Ejemplos:
- Next.js: límite Server/Client (por defecto Server, mantén use client al mínimo)
- Laravel: validación mediante Form Requests, convenciones de migraciones
- Python: anotaciones de tipo, nunca sobrescribir ni inventar datos en bruto

Añade una nota de una línea sobre la base de tu detección (a partir de qué archivos lo juzgaste)
antes de añadir el contenido. No dupliques nada que ya esté escrito.

Añade las siguientes "reglas absolutas" al archivo de instrucciones que cargas
(CLAUDE.md / AGENTS.md, etc.), adaptadas a la configuración de este repositorio.

- Nunca hagas commit de secretos, .env ni credenciales
- Nunca hagas push / force-push salvo que se te indique
- Valida la entrada en el límite / nunca relajes la autenticación o la autorización por tu cuenta
- Nunca ejecutes comandos destructivos (DROP / TRUNCATE / migrate:fresh, etc.) en la base de datos de producción
- Siempre que cambies el comportamiento, añade o actualiza pruebas

Si ya existen reglas similares, no las dupliques; solo completa lo que falte.

Convierte el contenido de este `CLAUDE.md` al formato `AGENTS.md` para
OpenAI Codex y escríbelo.

- Conserva el significado, pero reorganízalo en una estructura fácil de leer
  para Codex (encabezados, viñetas)
- Mantén tal cual los comandos, las reglas absolutas y la definición de terminado
- Escríbelo como `AGENTS.md` en la raíz

Convierte el contenido de este `CLAUDE.md` al formato Project Rules de Cursor
(archivos `.mdc` bajo `.cursor/rules/`).

- Divide las reglas en unidades con sentido
- Separa las reglas que deben aplicarse siempre de las reglas que se aplican
  solo a tipos de archivo específicos
- Establece las condiciones de aplicación adecuadas (globs, etc.) al principio de cada archivo

Inspecciona la estructura de este monorepo y crea los archivos de instrucciones que
tú (este agente) cargas (Claude Code usa CLAUDE.md, Codex usa AGENTS.md, etc.),
divididos de la siguiente manera.

- En la raíz: reglas comunes a todo el repo
  (convenciones de commits, protección de secretos, la definición de terminado general)
- En cada directorio de paquete/app: solo las reglas y los comandos específicos de ese stack

Evita la duplicación y añade una nota de una línea en cada paquete que diga "sigue las
reglas comunes de la raíz". Al final, reporta una lista de qué colocaste en cada directorio.

# Proyecto: <name>

## Qué es esto
Una descripción de la app en un párrafo. Qué hace, quién la usa y el stack
tecnológico (lenguaje, framework, BD, runtime).

## Comandos
- Servidor de desarrollo: `npm run dev`
- Build:                  `npm run build`
- Test:                   `npm test`
- Lint:                   `npm run lint`

## Convenciones
- El lenguaje es TypeScript (strict). No uses `any`.
- Ajústate al estilo del archivo que estás editando. Pasa siempre el Lint antes de terminar.
- Mantén los cambios al mínimo; no toques líneas no relacionadas (sin reformateos no relacionados).

## Reglas absolutas (de cumplimiento estricto)
- Antes de reportar terminado, ejecuta siempre las pruebas y el Lint anteriores y haz que pasen.
- Nunca jamás hagas commit de secretos, .env ni artefactos de build.
- Prefiere editar archivos existentes antes que crear nuevos.
- Cuando los requisitos sean vagos, haz exactamente una pregunta aclaratoria antes de un cambio grande.

## Fuera de límites (salvo indicación contraria)
- Configuración de CI, versiones de dependencias, configuración de infraestructura.

# <name>

- Stack: <p. ej. Next.js + TypeScript + PostgreSQL>
- Ejecuta siempre antes de terminar: `npm run lint` y `npm test` (ambos deben pasar)
- Ajústate al estilo existente. No reformatees líneas no relacionadas.
- No hagas commit de secretos ni de .env. No hagas push hasta que se te indique.
- Si algo es vago, no adivines; haz exactamente una pregunta.

# Next.js (App Router) + TypeScript

## Stack
Next.js (App Router), TypeScript strict, Tailwind CSS, <your-ORM>

## Comandos
- Dev:   `npm run dev`
- Build: `npm run build`   # debe pasar sin errores de tipo
- Lint:  `npm run lint`
- Test:  `npm test`

## Reglas de arquitectura
- Por defecto usa Server Components. Añade "use client" solo cuando se necesiten estado, efectos o
  APIs del navegador. Mantén los Client Components pequeños y en las hojas.
- Obtén datos en Server Components o Route Handlers.
  No obtengas los datos iniciales en useEffect.
- Co-localiza los componentes con su segmento de ruta. La UI compartida va en `components/`.
- Valida siempre con esquema la entrada externa en el límite (p. ej. Zod).

## Convenciones
- Sin `any`. Da tipos de retorno explícitos a las funciones públicas.
- Usa los design tokens / clases de Tailwind existentes. No añadas colores por tu cuenta.
- Mantén `page.tsx` ligero; empuja la lógica a funciones y componentes.

## Definición de terminado
`npm run build`, `npm run lint` y `npm test` pasan todos con código de salida 0.
Sin `any`, sin exports no usados, sin console.log olvidados.

# React (Vite) + TypeScript

## Comandos
- Dev:   `npm run dev`
- Build: `npm run build`
- Lint:  `npm run lint`
- Test:  `npm test` (Vitest + Testing Library)

## Reglas
- Solo componentes de función y Hooks. No uses componentes de clase.
- Mantén el estado al mínimo, en el orden "local -> Context -> librería de estado".
  No eleves el estado a global innecesariamente.
- Confina los efectos secundarios en useEffect y escribe correctamente el array de dependencias.
- Separa la UI de la lógica. Agrupa la obtención de datos en hooks dedicados (useXxx).
- Accesibilidad: da a los elementos interactivos roles apropiados y operación por teclado.

## Convenciones
- Sin `any`. Define las props con tipos.
- Ajústate al estilo de los componentes y estilos existentes.

## Definición de terminado
`npm run build`, `npm run lint` y `npm test` pasan con código de salida 0.

# API de Node.js (Express / Hono) + TypeScript

## Comandos
- Dev:   `npm run dev`
- Build: `npm run build`
- Test:  `npm test`
- Lint:  `npm run lint`

## Reglas
- Valida con esquema toda la entrada (body, query, params, headers) en el límite.
- No te tragues los errores. Devuélvelos tipados a través de un manejador de errores central.
- Lee los secretos desde variables de entorno. No los pongas a mano en el código.
- Estructura el acceso a la BD en capas (route -> service -> repository).
- Devuelve una forma de JSON coherente (unifica las formas de éxito y de fallo).

## Reglas absolutas
- No omitas ni relajes la lógica de autenticación / autorización por tu cuenta.
- Verifica siempre la autorización al añadir un endpoint expuesto públicamente.
- No registres en logs información personal, tokens ni contraseñas.

## Definición de terminado
`npm test` (camino feliz + casos de error) y `npm run lint` pasan.

# Laravel + PHP

## Comandos
- Serve:   `php artisan serve`
- Migrate: `php artisan migrate`
- Test:    `php artisan test`
- Format:  `./vendor/bin/pint`   # ejecútalo antes de terminar

## Convenciones (sigue la forma de Laravel)
- Usa las relaciones de Eloquent. Evita el SQL crudo sin una razón clara.
- Valida la entrada en clases Form Request. No lo hagas dentro de los controladores.
- Mantén los controladores ligeros. Empuja la lógica de negocio a Services / Actions.
- Cada cambio de esquema lleva una nueva migración. No edites las ya ejecutadas.
- Usa rutas con nombre y route model binding.

## Reglas absolutas
- Nunca jamás hagas commit de `.env` ni de credenciales reales.
- No ejecutes comandos destructivos como `migrate:fresh` contra la base de datos de producción.
- Siempre que cambies el comportamiento, añade o actualiza pruebas (`php artisan test`).

## Definición de terminado
Tanto `php artisan test` como `./vendor/bin/pint --test` pasan.

# Python / análisis de datos

## Entorno
- Usa el venv `.venv` del proyecto. No instales de forma global.
- Instalar: `pip install -r requirements.txt`
- Ejecutar: `python -m src.main`
- Test: `pytest`
- Formato: `ruff check .` y `ruff format .`

## Convenciones
- Añade anotaciones de tipo a la firma de cada función. Ejecuta `mypy src` si está configurado.
- No pongas lógica en los notebooks. El código reutilizable va en `src/`.
- Fija la semilla para todo lo que use aleatoriedad, para que los resultados sean reproducibles.

## Reglas absolutas de datos (lo más importante)
- No rellenes en silencio ni inventes valores faltantes. Si hay valores
  faltantes, repórtalos y confirma cómo manejarlos.
- No sobrescribas los archivos de datos en bruto. Escribe la salida en `data/processed/`.
- Documenta todas las suposiciones (filtros, filas excluidas, unidades) en comentarios del código.

## Definición de terminado
`pytest` pasa, `ruff check .` está limpio y los resultados se reproducen desde un estado limpio.

# Go

## Comandos
- Build:  `go build ./...`
- Test:   `go test ./...`
- Formato: `gofmt -w .` y `go vet ./...`

## Convenciones
- No te tragues los errores. Manéjalos siempre con `if err != nil` y devuélvelos
  con contexto (`fmt.Errorf("...: %w", err)`).
- Mantén el anidamiento poco profundo con early returns.
- Usa concurrencia solo cuando sea necesario. Vigila las fugas de goroutines y las condiciones de carrera
  (haz que pase `go test -race`).
- Comenta los símbolos exportados. Prefiere la librería estándar.

## Reglas absolutas
- No añadas abstracciones ni interfaces innecesarias (créalas cuando se necesiten).
- Antes de añadir una dependencia, comprueba primero si basta con la librería estándar.

## Definición de terminado
`go build ./...`, `go vet ./...` y `go test -race ./...` pasan todos.

# Rust

## Comandos
- Build:  `cargo build`
- Test:   `cargo test`
- Lint:   `cargo clippy -- -D warnings`
- Formato: `cargo fmt`

## Convenciones
- No uses `unwrap()` / `expect()` a la ligera en código de producción.
  Maneja `Result` / `Option` correctamente con `?` o match.
- `unsafe` está prohibido por principio. Si es realmente necesario, indica la razón en un comentario.
- Sigue al compilador en lo relativo al préstamo y los lifetimes. Replantea el diseño antes de
  escapar con `clone()`.
- Haz que los tipos de error sean significativos con `thiserror` / `anyhow`, etc.

## Definición de terminado
`cargo build` y `cargo test` pasan, y
`cargo clippy -- -D warnings` reporta cero advertencias.

# Ruby on Rails

## Comandos
- Serve:   `bin/rails server`
- Migrate: `bin/rails db:migrate`
- Test:    `bin/rails test` (o `bundle exec rspec`)
- Formato: `bundle exec rubocop -A`

## Convenciones (sigue la forma de Rails)
- Respeta "convención sobre configuración"; no inventes tu propia estructura.
- Evita los controladores / modelos gordos. Empuja la lógica a Services / Concerns.
- Restringe la entrada con strong parameters.
- Evita el N+1 (usa `includes`).
- Los cambios de esquema llevan una nueva migración. No edites las ya ejecutadas.

## Reglas absolutas
- Nunca jamás hagas commit de `.env` ni de credenciales.
- No ejecutes comandos destructivos contra la base de datos de producción.
- Cuando cambies el comportamiento, añade o actualiza pruebas.

## Definición de terminado
Las pruebas y `bundle exec rubocop` pasan.

# SQL / migraciones de base de datos

## Reglas absolutas (la protección de datos es lo primero)
- No ejecutes operaciones destructivas contra los datos de producción por tu cuenta
  (DROP / TRUNCATE / DELETE o UPDATE sin condición).
- Las migraciones deben proporcionar un procedimiento de rollback, no solo la dirección hacia adelante.
- No edites las migraciones ya ejecutadas. Añade siempre nuevas.
- Elimina o renombra columnas por etapas ("añadir -> migrar -> retirar"); no lo hagas de una sola vez.

## Convenciones de consultas
- Evita `SELECT *`; especifica las columnas que necesitas.
- Confirma que las condiciones de WHERE / JOIN pueden usar un índice.
- Divide las actualizaciones grandes en lotes para mantener corto el tiempo de bloqueo.
- Para las consultas de verificación destructivas, confirma primero el número de filas afectadas con un `SELECT` antes de ejecutar.

## Definición de terminado
Tanto la aplicación como el rollback tienen éxito en un entorno equivalente a staging, y has
confirmado que no hay cambios no intencionados en los datos existentes.

# Enfoque guiado por pruebas

Al cambiar el comportamiento, sigue este bucle cada vez:
1. Escribe primero una "prueba que falle" que exprese el comportamiento deseado.
2. Ejecuta la prueba y confirma que falla por la razón correcta.
3. Escribe el código mínimo necesario para que la prueba pase.
4. Ejecuta la suite de pruebas completa y confirma que todo está en verde.
5. Refactoriza manteniéndolo en verde.

## Reglas absolutas
- No elimines ni omitas pruebas para que pase la suite.
- No debilites las aserciones para ponerlo en verde.
- Si una prueba realmente está mal, explica por qué antes de cambiarla.
- El código nuevo sin pruebas no está "terminado".

## Definición de terminado
La suite completa pasa, la cobertura no ha bajado y revertir la
implementación hace que la nueva prueba falle (es decir, es una prueba significativa).

# Enfoque de depuración

Procede en este orden. No corrijas adivinando:
1. Establece los pasos de reproducción (cómo desencadenar el bug).
2. Escribe el comportamiento esperado y el comportamiento real, una frase cada uno.
3. Formula una hipótesis. Verifícala con logs o una reproducción mínima antes de corregir.
4. Una vez que hayas identificado la causa, aplica la corrección mínima.
5. Tras corregir, confirma que el bug ha desaparecido mediante los pasos de reproducción y que las pruebas existentes pasan.
6. Si es posible, añade una prueba de regresión que capture este bug.

## Reglas absolutas
- No cambies varios sitios a la vez mientras la causa sea desconocida.
- No te quedes en "funciona por ahora". Explica por qué se corrigió.
- No mezcles refactorizaciones no relacionadas en la depuración.

# Enfoque de refactorización

## Principio fundamental
No cambies el comportamiento observable desde fuera. No cambies en absoluto las salidas ni los efectos
secundarios para ninguna entrada.

## Pasos
1. Confirma primero que existen pruebas para el área objetivo y que están en verde.
   Si no, escribe primero pruebas de caracterización que fijen el comportamiento actual.
2. Cambia en pasos pequeños e individuales, ejecutando las pruebas tras cada paso.
3. Mantén un commit = un tipo de mejora.

## Reglas absolutas
- No mezcles adiciones de funcionalidades ni correcciones de bugs en la refactorización (hazlas un trabajo aparte).
- Si una prueba se pone en rojo, detente ahí mismo. No continúes.
- No cambies las firmas de la API pública por tu cuenta (confirma primero si es necesario).

## Definición de terminado
Todas las pruebas se mantienen en verde y el código es más legible con menos duplicación.

# Cómo escribir un documento de diseño

Antes de implementar, escribe primero lo siguiente en prosa (no escribas código):

## 1. Objetivo
El problema a resolver y las condiciones para considerarlo logrado (criterios de éxito).

## 2. Estado actual y restricciones
La configuración existente, las dependencias y las restricciones a respetar (rendimiento, compatibilidad, plazo).

## 3. Propuesta de diseño
- El enfoque elegido y los enfoques que consideraste y descartaste (y por qué).
- El flujo de datos, las interfaces clave y los archivos a cambiar.

## 4. Riesgos y preguntas abiertas
Qué podría romperse, las suposiciones que hay que confirmar y los puntos que requieren una decisión.

## 5. Plan
Divide la implementación en pasos pequeños, ordenados en unidades verificables.

## Reglas
- No empieces a implementar hasta que este diseño esté aprobado.
- Enumera las incógnitas bajo "preguntas abiertas"; no las rellenes con tus propias suposiciones.

# Cómo hacer cambios grandes

## Principio fundamental
Evita un cambio gigante. Divídelo de modo que cada paso sea de forma independiente revisable,
testeable y (idealmente) desplegable.

## Pasos
1. Descompón los cambios que llevan a la forma final en una secuencia de pasos pequeños e
   independientes, y preséntala.
2. Para cada paso, escribe "qué / por qué / alcance del impacto" en 1-2 líneas.
3. Tras cada paso, ejecuta la suite de pruebas completa y confirma el verde antes de continuar.
4. Avanza preservando la compatibilidad hacia atrás (añadir -> migrar -> retirar el camino antiguo).

## Reglas absolutas
- No reescribas un área amplia de una vez para "probarlo todo junto después".
- Si un paso crece demasiado, divídelo más.
- Mantén cada paso a una granularidad que se pueda revertir.

## Definición de terminado
Las pruebas están en verde tras completar todos los pasos, y cada commit intermedio tampoco está roto.

# Instrucciones de revisión de código

Revisa los cambios, agrúpalos por gravedad y reporta en este orden:
1. CRITICAL - agujeros de seguridad, pérdida de datos, fallos, autenticación rota
2. HIGH     - bugs de lógica, condiciones de carrera, manejo de errores ausente
3. MEDIUM   - problemas de rendimiento, pruebas ausentes, nombres confusos
4. LOW      - objeciones menores de estilo (solo si no hay problemas de mayor gravedad)

## Cómo reportar
- Para cada hallazgo: archivo:línea / qué está mal / por qué importa / una corrección concreta.
- Cita solo el fragmento relevante más pequeño. No pegues el archivo completo.
- Si un cambio es correcto, dilo explícitamente. No inventes problemas.

## Cosas que no hacer
- No entierres bugs reales bajo una pila de objeciones LOW.
- No reescribas archivos completos. Propón el diff más pequeño.
- Salvo que haya un daño real, no señales líneas fuera del alcance del diff.

## Salida
Termina con un veredicto de una línea: APPROVE / REQUEST CHANGES / BLOCK, con una razón.

# Reglas de Git / PR

## Commits
- Usa Conventional Commits: `type(scope): summary`
  type: feat, fix, refactor, test, docs, chore.
- Un commit = un cambio lógico. Mantenlo pequeño y revisable.
- En el cuerpo, escribe el "por qué" más que el "qué".

## Reglas absolutas
- No hagas `git push` salvo que se te indique.
- No hagas force-push, rebase ni amend en ramas compartidas / main.
- No hagas commit de secretos, .env, credenciales ni binarios grandes.
- Añade los archivos por nombre. No lo arrastres todo con `git add -A`.

## Pull requests
- Título dentro de 70 caracteres. El cuerpo es "Resumen" + "Plan de pruebas (lista de verificación)".
- Indica cualquier cambio que rompa la compatibilidad.
- No hagas merge. Crea el PR y reporta la URL.

# Instrucciones de revisión de seguridad

Revisa los cambios en orden frente a los siguientes ángulos y reporta cualquier
problema encontrado con una calificación de gravedad:
- Validación de entrada ausente (inyección: SQL / comandos / XSS / SSRF)
- Brechas de autenticación/autorización (comprobaciones de permisos ausentes, escalada de privilegios)
- Exposición de secretos (claves/tokens puestos a mano, salida a logs)
- Valores por defecto inseguros (exposición excesiva, CORS laxo, redirecciones sin validar)
- Vulnerabilidades conocidas en las dependencias, uso de criptografía / RNG inseguros

## Cómo reportar
- Para cada hallazgo: ubicación / escenario de ataque (cómo podría explotarse) / una corrección concreta.
- Marca las sospechas de las que no estés seguro como "requiere confirmación" (no las omitas en silencio).
- Si no hay problema, indica "sin problemas" junto con los ángulos que revisaste.

## Cosas que no hacer
- No generes código de ataque real ni pasos de explotación (muestra solo las correcciones).

# Reglas de trabajo con Docker / infraestructura

## Reglas absolutas (prevenir la destrucción es lo primero)
- No ejecutes comandos destructivos contra entornos de producción o compartidos por tu cuenta
  (`docker system prune`, eliminar volúmenes, `down -v`, etc.).
- Fija las imágenes a tags fijos. No dependas de `latest`.
- Pasa los secretos mediante variables de entorno / gestión de secretos.
  No los hornees en el Dockerfile ni en la imagen.
- Mantén los puertos expuestos y los privilegios (privileged, etc.) al mínimo necesario.

## Convenciones
- Mantén los Dockerfiles pequeños con builds multietapa, atento al cacheo de capas.
- Ejecuta como un usuario no root.
- Tras los cambios, haz build y arranca en local para verificar antes de reportar.

## Definición de terminado
`docker build` pasa, el contenedor arranca y se puede confirmar el health check / la
operación básica.

# Reglas de dependencias

## Reglas absolutas
- Antes de añadir una dependencia, comprueba si basta con la librería estándar o una
  dependencia existente.
- Al añadir una nueva dependencia, añade una nota de una línea sobre su propósito, alternativas
  y estado de mantenimiento.
- No subas versiones mayores por tu cuenta (solo cuando se te indique).
- No regeneres los archivos de lock (package-lock.json, etc.) por tu cuenta.
- Evita paquetes de origen dudoso o con muy pocas estrellas o mantenimiento deficiente.

## Pasos
1. Indica la razón de la adición o actualización.
2. Tras añadirla, confirma que el build y las pruebas pasan.
3. Confirma que la licencia no entra en conflicto con tu caso de uso.

## Definición de terminado
El build y las pruebas pasan tras el cambio de dependencias, y puedes explicar el diff del archivo de lock.