1. ¿Qué lenguajes/frameworks se usan?
   - Principales:
   - Secundarios:
 
2. ¿Qué herramientas de build existen?
   - Build:
   - Test:
   - Lint:
   - Format:
 
3. ¿Cómo está organizado el código?
   - Estructura de carpetas:
   - Patrones arquitectónicos:
   - Naming conventions:
 
4. ¿Qué comandos ejecuta el equipo frecuentemente?
   - Desarrollo:
   - Testing:
   - Deploy:
   - Mantenimiento:

1. Estilo de código
   - Prettier/ESLint configurado: Sí/No
   - Reglas específicas:
   - Excepciones:
 
2. Patrones de diseño
   - Patrones usados:
   - Anti-patrones a evitar:
 
3. Testing
   - Framework:
   - Coverage objetivo:
   - Dónde van los tests:
 
4. Git workflow
   - Branching strategy:
   - Formato de commits:
   - PR requirements:

1. Escribir boilerplate de componentes/clases/tests
2. Generar documentación
3. Formatear/lint antes de commits
4. Ejecutar tests relacionados
5. Generar mensajes de commit
6. Code review checklist
7. ... (añade las tuyas)

# Proyecto: [Nombre]
 
## Descripción
[Descripción breve del proyecto en 2-3 líneas]
 
## Arquitectura
[Stack tecnológico y decisiones arquitectónicas principales]
 
## Convenciones de código
[Reglas de estilo, naming, patrones]
 
## Estructura de carpetas
[Mapa de directorios con descripción]
 
## Comandos importantes
[Scripts npm, make targets, etc.]
 
## Reglas específicas
[Cosas importantes que Claude debe saber]
 
## Gotchas y trampas comunes
[Problemas conocidos, workarounds]

# Proyecto: TaskFlow API
 
## Descripción
API REST para gestión de tareas y proyectos. Backend del producto TaskFlow,
usado por +10K usuarios activos. Stack: Node.js + TypeScript + Prisma + PostgreSQL.

## Arquitectura
 
### Stack tecnológico
- **Runtime**: Node.js 20.x
- **Lenguaje**: TypeScript 5.3 (modo strict)
- **Framework**: Express 4.x
- **ORM**: Prisma 5.x
- **Base de datos**: PostgreSQL 16
- **Testing**: Jest + Supertest
- **Documentación**: OpenAPI 3.0 (Swagger)
 
### Decisiones arquitectónicas
 
1. **Arquitectura en capas**
   - Controllers: Manejo de HTTP, validación de entrada
   - Services: Lógica de negocio
   - Repositories: Acceso a datos (Prisma)
 
2. **Autenticación**
   - JWT con refresh tokens
   - Tokens firmados con RS256
   - Expiración: 15min (access), 7 días (refresh)
 
3. **Manejo de errores**
   - Errores custom heredan de AppError
   - Middleware global de error handling
   - Logs estructurados con Winston

## Arquitectura
 
### Stack tecnológico
- **Framework**: React 18 + TypeScript
- **Build**: Vite 5.x
- **Estado**: Zustand + React Query
- **Routing**: React Router v6
- **UI**: Tailwind CSS + shadcn/ui
- **Forms**: React Hook Form + Zod
- **Testing**: Vitest + Testing Library
 
### Patrones de diseño
 
1. **Composición de componentes**
   - Componentes atómicos en `/components/ui`
   - Componentes de negocio en `/components/features`
   - Páginas solo orquestan componentes
 
2. **Estado**
   - Estado global: Zustand (auth, theme, config)
   - Estado servidor: React Query (cache, refetch)
   - Estado local: useState solo cuando no se puede evitar
 
3. **Data fetching**
   - useQuery para lecturas
   - useMutation para escrituras
   - Optimistic updates en operaciones críticas

## Convenciones de código
 
### Naming conventions
 
1. **Variables y funciones**: camelCase
   ```typescript
   const userProfile = { ... }
   function calculateTotal() { ... }

// 1. React y frameworks
import { useState } from 'react';
 
// 2. Librerías externas
import { z } from 'zod';
 
// 3. Absolute imports del proyecto
import { Button } from '@/components/ui/button';
 
// 4. Relative imports
import { userSchema } from './schemas';
 
// 5. Tipos
import type { IUser } from './types';

// ✅ BUENO: Explica el "por qué", no el "qué"
// Usamos debounce aquí porque la API tiene rate limit de 10 req/s
const debouncedSearch = debounce(search, 300);
 
// ❌ MALO: Repite lo que el código ya dice
// Crea una variable llamada debouncedSearch
const debouncedSearch = debounce(search, 300);
 
// ✅ BUENO: JSDoc para funciones públicas
/**
 * Calcula el precio total incluyendo impuestos y descuentos.
 * @param items - Array de items del carrito
 * @param discountCode - Código de descuento opcional
 * @returns Precio total en centavos
 */
export function calculateTotal(items: ICartItem[], discountCode?: string): number {
  // ...
}

 
**Ejemplo Python:**
```markdown
## Convenciones de código
 
### Naming conventions
 
1. **Variables y funciones**: snake_case
   ```python
   user_profile = {...}
   def calculate_total(): ...

 
---
 
#### Estructura de carpetas
 
**Ejemplo API Node.js:**
```markdown
## Estructura de carpetas
 

 
**Ubicación de nuevos archivos:**
- Nuevo endpoint: Controller → Service → Repository
- Nuevo modelo: Primero en `schema.prisma`, después generar tipos
- Nueva utilidad: En `/utils` solo si es reusable en 3+ lugares

## Estructura de carpetas
 

 
**Reglas:**
- Componentes de UI no deben hacer fetching
- Páginas solo orquestan, lógica en components/features
- Un hook custom por archivo
- Services agrupados por entidad (`services/users.ts`, `services/tasks.ts`)

## Comandos importantes
 
### Desarrollo
```bash
npm run dev          # Inicia servidor en modo desarrollo (port 3000)
npm run dev:debug    # Igual pero con inspector de Node.js
npm run db:studio    # Abre Prisma Studio (GUI para ver la DB)

npm run test              # Ejecuta todos los tests
npm run test:watch        # Tests en modo watch
npm run test:coverage     # Genera reporte de coverage
npm run test:integration  # Solo integration tests (requiere DB)

npm run db:migrate        # Crea y aplica migración
npm run db:reset          # Resetea DB y aplica seeds
npm run db:seed           # Solo ejecuta seeds

npm run lint              # Ejecuta ESLint
npm run lint:fix          # Auto-fix de ESLint
npm run format            # Formatea con Prettier
npm run type-check        # Verifica tipos TypeScript

npm run build             # Build de producción
npm run start             # Inicia servidor en modo producción
npm run docker:up         # Levanta contenedor local

npm run pre-commit        # Ejecuta: lint, type-check, test

 
---
 
#### Reglas específicas
 
Aquí documenta las cosas que quieres que Claude **siempre** respete:
 
```markdown
## Reglas específicas
 
### Modificación de archivos
 
1. **NO modificar archivos generados**
   - ❌ `/prisma/migrations/*` (generado por Prisma)
   - ❌ `/src/generated/*` (generado por codegen)
   - ❌ `package-lock.json` (modificar package.json y regenerar)
 
2. **Pedir confirmación antes de:**
   - Modificar `schema.prisma` (requiere migración)
   - Cambiar archivos de configuración raíz (`.env`, `tsconfig.json`)
   - Eliminar funciones públicas (puede haber dependientes)
 
### Testing obligatorio
 
- ✅ TODO service nuevo DEBE tener tests unitarios
- ✅ TODO endpoint nuevo DEBE tener test de integración
- ✅ Ejecutar tests relacionados antes de marcar tarea como completa
 
### Seguridad
 
- ❌ NUNCA loggear información sensible (passwords, tokens, PII)
- ❌ NUNCA exponer stack traces en respuestas de producción
- ✅ Siempre validar inputs con Zod antes de procesar
- ✅ Sanitizar outputs de base de datos (omitir `password`, `refreshToken`)
 
### Performance
 
- ✅ Usar índices en queries frecuentes (añadir en schema.prisma)
- ✅ Paginar resultados de listas (default: 20 items)
- ⚠️ Queries N+1: Usar `include` de Prisma en lugar de queries en loops
 
### Commits
 
- Usar conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`
- Formato: `tipo(scope): descripción breve`
- Ejemplos:
  - `feat(auth): add password reset endpoint`
  - `fix(tasks): prevent duplicate task creation`
  - `docs(readme): update installation instructions`

## Gotchas y trampas comunes
 
### 1. Prisma y relaciones
 
**Problema:** Al actualizar una relación, Prisma no la elimina automáticamente.
 
```typescript
// ❌ INCORRECTO: No elimina tags viejos
await prisma.task.update({
  where: { id },
  data: {
    tags: { connect: newTagIds.map(id => ({ id })) }
  }
});
 
// ✅ CORRECTO: Primero desconecta, después conecta
await prisma.task.update({
  where: { id },
  data: {
    tags: {
      set: [],  // Desconecta todos
      connect: newTagIds.map(id => ({ id }))  // Conecta nuevos
    }
  }
});

// ❌ NO hacer esto en loops
for (const user of users) {
  await sendNotification(user.email);
}
 
// ✅ Hacer esto
for (const user of users) {
  await notificationQueue.add('send-email', { userId: user.id });
}

// ✅ Siempre usar luxon para fechas
import { DateTime } from 'luxon';
 
// Almacenar
const utcDate = DateTime.utc().toISO();
 
// Mostrar
const userDate = DateTime.fromISO(utcDate).setZone(user.timezone);

// El setup ya lo hace, pero ten en cuenta:
// - Cada test suite hace un reset de DB
// - Seeds están en tests/fixtures/seeds.ts
// - NO usar DB de desarrollo para tests

# En desarrollo local se usan .env files
# En producción se usan secrets de Kubernetes
 
# NUNCA commitear:
- .env
- .env.local
- .env.production
 
# Sí commitear (con valores de ejemplo):
- .env.example

 
---
 
### 2.3 Template completo
 
Descarga el template base aquí:
- CLAUDE.md.template
 
O crea el tuyo siguiendo la estructura de esta sección.
 
---
 
## Paso 3: Configurar settings.json
 
### 3.1 Ubicación
 
Crea: `.claude/settings.json` en la raíz del proyecto.
 
**⚠️ IMPORTANTE:**
- Este archivo SÍ se commitea (es configuración del equipo)
- Secrets van en `.claude/settings.local.json` (gitignored)
 
### 3.2 Estructura base
 
```json
{
  "model": "claude-sonnet-4-20250514",
  "maxTokens": 4096,
  "permissions": {
    "allowedTools": [],
    "deny": []
  },
  "hooks": {
    "PostToolUse": []
  }
}

{
  "model": "claude-sonnet-4-20250514",  // Balance perfecto (RECOMENDADO)
  "model": "claude-opus-4-5-20251101",  // Tareas complejas, arquitectura
  "model": "claude-haiku-4-20250514",   // Tareas rápidas, alto volumen
}

{
  "permissions": {
    "allowedTools": [
      "Read",
      "Write",
      "Edit"
    ]
  }
}

{
  "permissions": {
    "allowedTools": [
      "Read",
      "Write",
      "Edit",
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(npx *)"
    ]
  }
}

"Bash(git *)",
"Bash(npm *)",
"Bash(npx *)",
"Bash(node *)",
"Bash(pnpm *)",    // Si usas pnpm
"Bash(yarn *)"     // Si usas yarn

"Bash(git *)",
"Bash(python *)",
"Bash(pip *)",
"Bash(poetry *)",  // Si usas poetry
"Bash(pytest *)"

"Bash(git *)",
"Bash(go *)"

"Bash(git *)",
"Bash(cargo *)"

{
  "permissions": {
    "deny": [
      // Secrets
      "Read(./.env)",
      "Read(./.env.*)",
      "Write(./.env)",
      "Write(./.env.*)",
 
      // Configuración sensible
      "Write(./package.json)",     // Solo editar con confirmación
      "Write(./tsconfig.json)",
 
      // Archivos generados
      "Write(./prisma/migrations/*)",
      "Write(./src/generated/*)",
 
      // Comandos peligrosos
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(chmod *)",
      "Bash(npm publish)",  // Evitar publicaciones accidentales
 
      // Deploy
      "Bash(kubectl *)",
      "Bash(terraform *)",
      "Bash(aws *)"         // Añadir excepción específica si necesitas
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write(*.ts)",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $file"
          }
        ]
      },
      {
        "matcher": "Write(*.tsx)",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $file"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write(*.py)",
        "hooks": [
          {
            "type": "command",
            "command": "python -m black $file && python -m isort $file"
          }
        ]
      }
    ]
  }
}

{
  "matcher": "Write(*.ts)",
  "hooks": [
    {
      "type": "command",
      "command": "npx eslint --fix $file || true"
    }
  ]
}

{
  "matcher": "Write(src/**/*.ts)",
  "hooks": [
    {
      "type": "command",
      "command": "npm test -- --findRelatedTests $file --passWithNoTests --silent"
    }
  ]
}

{
  "matcher": "Write(**/*.types.ts)",
  "hooks": [
    {
      "type": "command",
      "command": "npx tsc --noEmit"
    }
  ]
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write(*.{ts,tsx})",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $file"
          },
          {
            "type": "command",
            "command": "npx eslint --fix $file || true"
          }
        ]
      },
      {
        "matcher": "Write(src/**/*.ts)",
        "hooks": [
          {
            "type": "command",
            "command": "npm test -- --findRelatedTests $file --passWithNoTests --silent"
          }
        ]
      },
      {
        "matcher": "Write(**/*.types.ts)",
        "hooks": [
          {
            "type": "command",
            "command": "npx tsc --noEmit"
          }
        ]
      }
    ]
  }
}

{
  "model": "claude-sonnet-4-20250514",
  "maxTokens": 4096,
 
  "permissions": {
    "allowedTools": [
      "Read",
      "Write",
      "Edit",
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(npx *)",
      "Bash(node *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Write(./.env)",
      "Write(./.env.*)",
      "Write(./package.json)",
      "Write(./tsconfig.json)",
      "Write(./prisma/migrations/*)",
      "Write(./src/generated/*)",
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(npm publish)"
    ]
  },
 
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write(*.{ts,tsx})",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $file"
          },
          {
            "type": "command",
            "command": "npx eslint --fix $file || true"
          }
        ]
      },
      {
        "matcher": "Write(src/**/*.ts)",
        "hooks": [
          {
            "type": "command",
            "command": "npm test -- --findRelatedTests $file --passWithNoTests --silent"
          }
        ]
      }
    ]
  }
}

.claude/
  skills/
    commit/
      SKILL.md
    test/
      SKILL.md
    review/
      SKILL.md
    doc/
      SKILL.md
    [tu-skill-específica]/
      SKILL.md

---
name: commit
description: Genera mensaje de commit siguiendo conventional commits
disable-model-invocation: false
argument-hint: "[mensaje opcional]"
allowed-tools: Read, Bash(git *)
---
 
# Generador de mensajes de commit
 
Analiza los cambios staged en git y genera un mensaje de commit siguiendo la convención del proyecto.
 
## Formato
 
Usamos **Conventional Commits**:
 

 
## Tipos permitidos
 
- `feat`: Nueva funcionalidad
- `fix`: Corrección de bug
- `docs`: Solo documentación
- `style`: Cambios de formato (no afectan lógica)
- `refactor`: Refactorización de código
- `test`: Añadir o modificar tests
- `chore`: Cambios en build, dependencias, etc.
 
## Proceso
 
1. Ejecuta `git diff --cached` para ver cambios staged
2. Analiza los cambios y determina:
   - El tipo de commit más apropiado
   - El scope (módulo/componente afectado)
   - Una descripción clara y concisa
3. Si los cambios son complejos, añade cuerpo con detalles
4. Si hay breaking changes, inclúyelos en el footer
5. Muestra el mensaje propuesto
6. Pregunta si desea hacer el commit con ese mensaje
 
## Argumentos
 
Si se proporciona `$ARGUMENTS`, úsalo como base para el mensaje pero valida que siga el formato.
 
## Ejemplo
 
```bash
$ /commit
 
Cambios detectados:
- Nuevo endpoint POST /api/tasks
- Tests para el endpoint
- Actualización de OpenAPI schema
 
Mensaje propuesto:
---
feat(tasks): add create task endpoint
 
- Implementa POST /api/tasks con validación
- Añade tests de integración
- Actualiza documentación OpenAPI
---
 
¿Deseas hacer commit con este mensaje? (sí/no)

 
---
 
### 4.3 Skill 2: `/test` - Generar tests
 
**Archivo:** `.claude/skills/test/SKILL.md`
 
```markdown
---
name: test
description: Genera tests para código existente
argument-hint: "<archivo>"
allowed-tools: Read, Write
---
 
# Generador de tests
 
Genera tests completos para un archivo de código siguiendo las convenciones del proyecto.
 
## Proceso
 
1. Lee el archivo especificado en `$ARGUMENTS`
2. Identifica funciones/clases públicas a testear
3. Genera tests siguiendo la estructura del proyecto:
   - Framework: Jest
   - Ubicación: archivo paralelo con sufijo `.test.ts`
   - Coverage: Casos felices + edge cases + errores
4. Crea el archivo de tests
5. Ejecuta los tests para validar
 
## Estructura de tests
 
```typescript
import { describe, it, expect, beforeEach } from '@jest/globals';
import { nombreFuncion } from './archivo';
 
describe('nombreFuncion', () => {
  describe('cuando recibe inputs válidos', () => {
    it('should return expected result', () => {
      // Arrange
      const input = ...;
 
      // Act
      const result = nombreFuncion(input);
 
      // Assert
      expect(result).toBe(...);
    });
  });
 
  describe('cuando recibe inputs inválidos', () => {
    it('should throw error for null input', () => {
      expect(() => nombreFuncion(null)).toThrow();
    });
  });
});

$ /test src/services/userService.ts
 
Analizando src/services/userService.ts...
 
Funciones detectadas:
1. createUser(data: ICreateUserDTO): Promise<IUser>
2. getUserById(id: string): Promise<IUser>
3. updateUser(id: string, data: IUpdateUserDTO): Promise<IUser>
4. deleteUser(id: string): Promise<void>
 
Generando tests en src/services/userService.test.ts...
 
Tests creados:
- ✅ 12 test cases
- ✅ Mocks de repositorio
- ✅ Casos de error incluidos
 
Ejecutando tests...
✓ All tests passed (12/12)

 
---
 
### 4.4 Skill 3: `/review` - Code review
 
**Archivo:** `.claude/skills/review/SKILL.md`
 
```markdown
---
name: review
description: Realiza code review de un archivo o cambios
argument-hint: "[archivo o 'staged']"
allowed-tools: Read, Bash(git *)
---
 
# Code reviewer
 
Realiza un code review detallado siguiendo los estándares del proyecto.
 
## Proceso
 
1. Si `$ARGUMENTS` es "staged": analiza cambios en `git diff --cached`
2. Si `$ARGUMENTS` es un archivo: analiza ese archivo completo
3. Si no hay argumentos: analiza los archivos modificados (`git diff --name-only`)
 
## Criterios de review
 
### 🔴 Crítico (P1) - Debe corregirse
- Bugs que causan crashes o corrupción de datos
- Vulnerabilidades de seguridad
- Memory leaks o problemas de performance severos
- Violaciones de principios SOLID
 
### 🟠 Alto (P2) - Fuertemente recomendado
- Bugs funcionales no críticos
- Code smells evidentes
- Falta de manejo de errores
- Tests insuficientes o faltantes
 
### 🟡 Medio (P3) - Recomendado
- Mejoras de legibilidad
- Oportunidades de refactor
- Documentación faltante
- Nombres poco claros
 
### ⚪ Bajo (P4) - Sugerencia
- Preferencias de estilo
- Optimizaciones menores
- Sugerencias de mejora
 
## Formato del reporte
 
```markdown
# Code Review: [archivo]
 
## Resumen
- Archivos revisados: X
- Issues encontrados: Y (P1: a, P2: b, P3: c, P4: d)
- Estado general: ✅ Aprobado / ⚠️ Aprobado con comentarios / ❌ Requiere cambios
 
## Issues
 
### 🔴 Crítico (P1)
 
#### [archivo.ts:línea] Descripción del problema
**Problema:**
[Descripción detallada]
 
**Impacto:**
[Qué puede salir mal]
 
**Solución sugerida:**
```typescript
// Código sugerido

 
## Ejemplo
 
```bash
$ /review src/controllers/taskController.ts
 
# Code Review: taskController.ts
 
## Resumen
- Archivos revisados: 1
- Issues encontrados: 5 (P1: 1, P2: 2, P3: 1, P4: 1)
- Estado general: ⚠️ Aprobado con comentarios
 
## Issues
 
### 🔴 Crítico (P1)
 
#### [taskController.ts:45] Falta validación de input
**Problema:**
La función `createTask` no valida el input antes de pasarlo al service.
 
**Impacto:**
Posible inyección SQL o datos corruptos en DB.
 
**Solución sugerida:**
```typescript
const validated = taskSchema.parse(req.body);
const task = await taskService.create(validated);

---
name: doc
description: Genera documentación para código
argument-hint: "<archivo>"
allowed-tools: Read, Edit
---
 
# Generador de documentación
 
Añade o actualiza documentación en código siguiendo el estilo del proyecto.
 
## Proceso
 
1. Lee el archivo especificado en `$ARGUMENTS`
2. Identifica funciones/clases sin documentación o con documentación incompleta
3. Genera documentación apropiada:
   - JSDoc para TypeScript/JavaScript
   - Docstrings para Python
   - Doc comments para Go/Rust
4. Actualiza el archivo añadiendo la documentación
 
## Formato TypeScript/JavaScript (JSDoc)
 
```typescript
/**
 * Descripción clara de qué hace la función.
 *
 * @param paramName - Descripción del parámetro
 * @param optionalParam - Descripción (opcional)
 * @returns Descripción de qué retorna
 * @throws {ErrorType} Cuándo lanza este error
 *
 * @example
 * ```typescript
 * const result = functionName('input');
 * console.log(result); // Output esperado
 * ```
 */
export function functionName(
  paramName: string,
  optionalParam?: number
): ReturnType {
  // ...
}

def function_name(param_name: str, optional_param: int = None) -> ReturnType:
    """Descripción clara de qué hace la función.
 
    Args:
        param_name: Descripción del parámetro
        optional_param: Descripción (opcional)
 
    Returns:
        Descripción de qué retorna
 
    Raises:
        ValueError: Cuándo lanza este error
 
    Example:
        >>> result = function_name('input')
        >>> print(result)
        Expected output
    """
    pass

$ /doc src/utils/validation.ts
 
Analizando src/utils/validation.ts...
 
Funciones sin documentación:
1. isValidEmail(email: string): boolean
2. sanitizeInput(input: string): string
3. validatePassword(password: string): IValidationResult
 
Añadiendo documentación...
 
✅ Documentación añadida a 3 funciones

 
---
 
### 4.6 Skill 5: Skill específica de tu stack
 
Crea una skill personalizada para tu stack o workflow específico.
 
**Ejemplos por stack:**
 
#### React: `/component` - Generar componente
 
```markdown
---
name: component
description: Genera componente React con tests
argument-hint: "<nombre>"
allowed-tools: Read, Write
---
 
# Generador de componente React
 
Genera un componente React completo con:
- Componente TypeScript
- Props interface
- Test básico
- Storybook story (si existe)
 
## Proceso
 
1. Parsea el nombre del componente de `$ARGUMENTS`
2. Crea estructura en `src/components/[nombre]/`
3. Genera archivos:
   - `[Nombre].tsx` - Componente
   - `[Nombre].types.ts` - Props interface
   - `[Nombre].test.tsx` - Tests
   - `index.ts` - Barrel export
 
## Template del componente
 
```typescript
import type { I[Nombre]Props } from './[Nombre].types';
 
export function [Nombre]({ prop1, prop2 }: I[Nombre]Props) {
  return (
    <div>
      {/* Implementación */}
    </div>
  );
}

$ /component UserCard
 
Generando componente UserCard...
 
Estructura creada:
src/components/UserCard/
├── UserCard.tsx
├── UserCard.types.ts
├── UserCard.test.tsx
└── index.ts
 
✅ Componente generado exitosamente

 
#### Python/FastAPI: `/endpoint` - Generar endpoint
 
```markdown
---
name: endpoint
description: Genera endpoint completo de API
argument-hint: "<método> <ruta>"
allowed-tools: Read, Write
---
 
# Generador de endpoint FastAPI
 
Genera un endpoint completo con:
- Route handler
- Pydantic schemas
- Service layer
- Tests
 
## Uso
 
```bash
/endpoint POST /users
/endpoint GET /users/{id}

 
#### Node.js/Express: `/api` - Generar recurso REST
 
```markdown
---
name: api
description: Genera CRUD completo para un recurso
argument-hint: "<nombre-recurso>"
allowed-tools: Read, Write
---
 
# Generador de recurso REST
 
Genera CRUD completo:
- Controller con endpoints CRUD
- Service con lógica de negocio
- Repository con queries
- Validadores Zod
- Tests integration
 
## Ejemplo
 
```bash
$ /api task
 
Generando recurso 'task'...
 
Archivos creados:
- src/controllers/taskController.ts
- src/services/taskService.ts
- src/repositories/taskRepository.ts
- src/validators/taskValidators.ts
- src/routes/taskRoutes.ts
- tests/integration/tasks.test.ts
 
✅ Endpoints generados:
- GET    /api/tasks
- GET    /api/tasks/:id
- POST   /api/tasks
- PUT    /api/tasks/:id
- DELETE /api/tasks/:id

 
**Elige la que tenga más sentido para tu proyecto o crea una totalmente personalizada.**
 
---
 
### 4.7 Resumen de skills
 
Deberías tener estas 5 skills:
 
1. ✅ `/commit` - Mensajes de commit estandarizados
2. ✅ `/test` - Generar tests
3. ✅ `/review` - Code review
4. ✅ `/doc` - Documentar código
5. ✅ `/[tu-skill]` - Específica de tu stack
 
**Templates completos disponibles en:**
- recursos/templates/opcion-a/skills/
 
---
 
## Paso 5: Documentación
 
Crea documentación para que otros desarrolladores (o tú en el futuro) sepan usar la configuración.
 
### 5.1 README de configuración
 
**Archivo:** `docs/claude-code-setup.md`
 
```markdown
# Configuración de Claude Code
 
Este proyecto está optimizado para trabajar con Claude Code.
 
## Prerequisitos
 
- Claude Code instalado: `npm install -g @anthropic-ai/claude-code`
- API key configurada (Claude Pro/Max o API key)
 
## Setup inicial
 
1. **Instalar Claude Code** (si no lo tienes):
   ```bash
   npm install -g @anthropic-ai/claude-code
   claude --version

# Inicia sesión
claude
 
# Crea branch
> Crea branch feature/user-authentication
 
# Desarrolla
> Implementa login endpoint con JWT
 
# Tests
> /test src/controllers/authController.ts
 
# Review
> /review staged
 
# Commit
> /commit

claude
 
> Analiza el error: [pega stack trace]
> Propón solución
> Implementa la solución
> /test [archivo modificado]
> /commit

claude
 
> /review src/services/oldService.ts
> Refactoriza oldService.ts aplicando las sugerencias
> /test src/services/oldService.ts
> /commit

# Ver contexto actual
> /context
 
# Compactar conversación larga
> /compact
 
# Cambiar modelo temporalmente
> /model opus

> Lee userService.ts, genera tests con Jest, asegúrate de cubrir
  casos felices y errores, usa mocks para el repository...

> /test src/services/userService.ts

# Verifica que las herramientas estén instaladas
npx prettier --version
npx eslint --version
npm test -- --version
 
# Verifica permisos en settings.json
cat .claude/settings.json | grep -A 20 hooks

# Verifica que existe
ls -la .claude/CLAUDE.md
 
# Pregunta directamente
> ¿Qué dice el CLAUDE.md sobre [tema específico]?

# Edita settings.json para permitir lo necesario
vi .claude/settings.json
 
# O usa modo peligroso temporalmente (con cuidado)
claude --dangerously-skip-permissions

npm install -g @anthropic-ai/claude-code
claude login
cd proyecto
claude  # Y trustear el directorio

 
---
 
### 5.2 Guía de onboarding
 
**Archivo:** `docs/onboarding-claude.md`
 
```markdown
# Onboarding: Trabajar con Claude Code
 
Bienvenido al equipo. Este proyecto usa Claude Code como herramienta de desarrollo.
 
## ¿Qué es Claude Code?
 
Claude Code es un agente de IA que:
- Entiende todo el codebase
- Puede leer, escribir y editar código
- Ejecuta comandos y tests
- Se integra con git
 
**No es Copilot:** No autocompleta mientras escribes. Es un asistente conversacional que hace cambios más amplios.
 
## Setup (5 minutos)
 
### 1. Instalar
 
```bash
npm install -g @anthropic-ai/claude-code

claude login
# Sigue las instrucciones en el navegador

cd /ruta/a/este/proyecto
claude

> Explica la arquitectura general del proyecto
> ¿Cómo funciona la autenticación?
> ¿Dónde están los tests y cómo se ejecutan?
> Muéstrame el flujo de crear una tarea desde la UI hasta la DB

> Necesito añadir paginación al endpoint GET /tasks
> [Claude propone cambios]
> Implementa la solución
> /test src/controllers/taskController.ts
> /review staged
> /commit

> Este es el error que estoy teniendo: [pega stack trace]
> [Claude analiza y propone causa]
> ¿Cómo lo arreglo?
> [Claude propone solución]
> Impleméntalo

# Antes de hacer commit
> /review staged
 
# O de un archivo específico
> /review src/services/paymentService.ts

 
---
 
## Paso 6: Testing y validación
 
### 6.1 Checklist de validación
 
Antes de dar por terminado tu proyecto, valida:
 
#### CLAUDE.md
- [ ] Documenta arquitectura del stack
- [ ] Lista convenciones de código
- [ ] Mapea estructura de carpetas
- [ ] Incluye comandos importantes
- [ ] Tiene reglas específicas del proyecto
- [ ] Documenta gotchas o trampas comunes
 
#### settings.json
- [ ] Modelo apropiado configurado
- [ ] Permisos siguen principio de mínimo privilegio
- [ ] Comandos bash necesarios permitidos
- [ ] Archivos sensibles (.env) denegados
- [ ] Hook de formateo funciona
- [ ] Hook de linting funciona
- [ ] Hook de tests funciona (si aplica)
 
#### Skills
- [ ] 5 skills creadas
- [ ] Cada skill tiene frontmatter YAML válido
- [ ] `/commit` genera mensajes conventional commits
- [ ] `/test` genera tests funcionales
- [ ] `/review` da feedback útil
- [ ] `/doc` añade documentación apropiada
- [ ] Skill específica resuelve problema real
 
#### Documentación
- [ ] `docs/claude-code-setup.md` existe y está completo
- [ ] `docs/onboarding-claude.md` para nuevos devs
- [ ] Instrucciones claras de instalación
- [ ] Troubleshooting incluido
- [ ] Ejemplos de uso
 
---
 
### 6.2 Pruebas prácticas
 
#### Prueba 1: Nueva sesión limpia
 
```bash
# Cierra claude si está abierto
exit
 
# Nueva sesión
claude
 
# Pregunta sobre el proyecto
> Explica la arquitectura del proyecto

> Añade un comentario en src/index.ts

> /commit
> /test src/utils/helper.ts
> /review src/services/userService.ts
> /doc src/utils/validation.ts
> /[tu-skill-especifica] [argumentos]

> Lee el archivo .env

> Ejecuta "sudo rm -rf /"

> Crea una nueva función "saludar" en src/utils/greeter.ts que retorne "Hola [nombre]"
> /test src/utils/greeter.ts
> /doc src/utils/greeter.ts
> /review staged
> /commit

proyecto/
├── .claude/
│   ├── CLAUDE.md                    ← Contexto del proyecto
│   ├── settings.json                ← Configuración base
│   └── skills/
│       ├── commit/SKILL.md          ← Skill 1
│       ├── test/SKILL.md            ← Skill 2
│       ├── review/SKILL.md          ← Skill 3
│       ├── doc/SKILL.md             ← Skill 4
│       └── [tu-skill]/SKILL.md      ← Skill 5
├── docs/
│   ├── claude-code-setup.md         ← Setup y uso
│   └── onboarding-claude.md         ← Guía para nuevos devs
└── README.md                        ← Mencionar Claude Code

┌─────────────────────────────────────────────────────────────┐
│                     WORKFLOW DE DESARROLLO                  │
└─────────────────────────────────────────────────────────────┘
 
┌──────────────┐
│ Nuevo Dev    │
│ se une       │
└──────┬───────┘
       │
       ├─────────> Script de Setup
       │           - Instala Claude Code
       │           - Configura API key
       │           - Instala deps
       │           - Valida instalación
       │
       ▼
┌──────────────┐
│ Desarrollo   │
│ local        │
└──────┬───────┘
       │
       ├─────────> Hooks locales (pre-commit, pre-push)
       │           - Formateo
       │           - Linting
       │           - Tests
       │
       ▼
┌──────────────┐
│ Crea PR      │
└──────┬───────┘
       │
       ├─────────> GitHub Actions Workflow
       │           ├── AI Code Review
       │           ├── Breaking Changes Detection
       │           ├── Test Suite
       │           └── Comment on PR
       │
       ▼
┌──────────────┐
│ Merge PR     │
└──────┬───────┘
       │
       ├─────────> Post-merge Workflow
       │           ├── Generate Changelog
       │           ├── Update Docs
       │           └── Notify team
       │
       ▼
┌──────────────┐
│ Release      │
└──────┬───────┘
       │
       └─────────> Release Workflow
                   ├── Create Release Notes
                   ├── Tag version
                   └── Deploy

#!/bin/bash
 
set -e  # Exit on error
 
# Colors para output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
 
# Funciones auxiliares
print_step() {
    echo -e "${BLUE}▶ $1${NC}"
}
 
print_success() {
    echo -e "${GREEN}✓ $1${NC}"
}
 
print_error() {
    echo -e "${RED}✗ $1${NC}"
}
 
print_warning() {
    echo -e "${YELLOW}⚠ $1${NC}"
}
 
# Header
echo "================================================"
echo "  Claude Code Setup Script"
echo "  Proyecto: $(basename $(pwd))"
echo "================================================"
echo ""
 
# 1. Verificar Node.js
print_step "Verificando Node.js..."
if ! command -v node &> /dev/null; then
    print_error "Node.js no está instalado"
    echo "Instala Node.js desde: https://nodejs.org/"
    exit 1
fi
 
NODE_VERSION=$(node --version)
print_success "Node.js instalado: $NODE_VERSION"
 
# 2. Instalar Claude Code
print_step "Instalando Claude Code..."
 
if command -v claude &> /dev/null; then
    CLAUDE_VERSION=$(claude --version 2>&1 | head -n 1)
    print_warning "Claude Code ya está instalado: $CLAUDE_VERSION"
    read -p "¿Deseas actualizar a la última versión? (y/n) " -n 1 -r
    echo
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        npm install -g @anthropic-ai/claude-code@latest
        print_success "Claude Code actualizado"
    fi
else
    npm install -g @anthropic-ai/claude-code
    print_success "Claude Code instalado"
fi
 
# Verificar instalación
if ! command -v claude &> /dev/null; then
    print_error "Error al instalar Claude Code"
    exit 1
fi
 
CLAUDE_VERSION=$(claude --version 2>&1 | head -n 1)
print_success "Claude Code version: $CLAUDE_VERSION"
 
# 3. Configurar API Key
print_step "Configurando API Key..."
 
# Verificar si ya está configurado
if [ -n "$ANTHROPIC_API_KEY" ]; then
    print_success "API key ya configurada (variable de entorno)"
elif [ -f "$HOME/.claude/config" ]; then
    print_success "API key ya configurada (archivo config)"
else
    echo ""
    echo "Necesitas una API key de Claude."
    echo "Opciones:"
    echo "  1) Tengo Claude Pro/Max (login con cuenta)"
    echo "  2) Tengo API key de Anthropic"
    echo ""
    read -p "Elige opción (1/2): " API_OPTION
 
    case $API_OPTION in
        1)
            print_step "Iniciando login con Claude..."
            claude login
            print_success "Login completado"
            ;;
        2)
            read -sp "Ingresa tu API key: " API_KEY
            echo ""
            export ANTHROPIC_API_KEY="$API_KEY"
 
            # Guardar en shell config
            SHELL_RC=""
            if [ -f "$HOME/.bashrc" ]; then
                SHELL_RC="$HOME/.bashrc"
            elif [ -f "$HOME/.zshrc" ]; then
                SHELL_RC="$HOME/.zshrc"
            fi
 
            if [ -n "$SHELL_RC" ]; then
                if ! grep -q "ANTHROPIC_API_KEY" "$SHELL_RC"; then
                    echo "" >> "$SHELL_RC"
                    echo "# Claude Code API Key" >> "$SHELL_RC"
                    echo "export ANTHROPIC_API_KEY=\"$API_KEY\"" >> "$SHELL_RC"
                    print_success "API key guardada en $SHELL_RC"
                fi
            fi
            ;;
        *)
            print_error "Opción inválida"
            exit 1
            ;;
    esac
fi
 
# 4. Instalar dependencias del proyecto
print_step "Instalando dependencias del proyecto..."
 
if [ -f "package.json" ]; then
    if [ -f "package-lock.json" ]; then
        npm ci
    else
        npm install
    fi
    print_success "Dependencias de npm instaladas"
elif [ -f "requirements.txt" ]; then
    if command -v python3 &> /dev/null; then
        python3 -m pip install -r requirements.txt
        print_success "Dependencias de Python instaladas"
    else
        print_error "Python3 no está instalado"
        exit 1
    fi
elif [ -f "go.mod" ]; then
    go mod download
    print_success "Dependencias de Go descargadas"
elif [ -f "Cargo.toml" ]; then
    cargo fetch
    print_success "Dependencias de Rust descargadas"
fi
 
# 5. Verificar configuración de Claude
print_step "Verificando configuración de Claude Code..."
 
if [ ! -f ".claude/CLAUDE.md" ]; then
    print_warning "No se encontró .claude/CLAUDE.md"
else
    print_success "CLAUDE.md encontrado"
fi
 
if [ ! -f ".claude/settings.json" ]; then
    print_warning "No se encontró .claude/settings.json"
else
    print_success "settings.json encontrado"
fi
 
# 6. Trustear el directorio
print_step "Trusteando directorio actual..."
echo ""
echo "Cuando se abra Claude, acepta el trust dialog."
echo "Revisa los archivos de configuración antes de aceptar:"
echo "  - .claude/CLAUDE.md"
echo "  - .claude/settings.json"
echo ""
read -p "Presiona Enter para continuar..."
 
# Iniciar Claude en modo interactivo brevemente
timeout 5s claude || true
 
# 7. Instalar herramientas adicionales
print_step "Verificando herramientas de desarrollo..."
 
# Prettier (si es proyecto JS/TS)
if [ -f "package.json" ]; then
    if ! npm list prettier &> /dev/null; then
        print_warning "Prettier no está instalado (recomendado para formateo)"
    else
        print_success "Prettier instalado"
    fi
 
    if ! npm list eslint &> /dev/null; then
        print_warning "ESLint no está instalado (recomendado para linting)"
    else
        print_success "ESLint instalado"
    fi
fi
 
# 8. Setup de git hooks (opcional)
print_step "Configurando git hooks..."
 
if [ -d ".git" ]; then
    read -p "¿Deseas instalar git hooks? (y/n) " -n 1 -r
    echo
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        if command -v husky &> /dev/null || npm list husky &> /dev/null; then
            npx husky install
            print_success "Git hooks configurados con Husky"
        else
            print_warning "Husky no está disponible"
        fi
    fi
fi
 
# 9. Validación final
print_step "Ejecutando validación final..."
 
echo ""
echo "Probando Claude Code..."
CLAUDE_TEST=$(claude -p "responde solo: OK" 2>&1 || echo "ERROR")
 
if echo "$CLAUDE_TEST" | grep -qi "ok"; then
    print_success "Claude Code funciona correctamente"
else
    print_error "Claude Code no respondió correctamente"
    echo "Output: $CLAUDE_TEST"
    exit 1
fi
 
# Resumen final
echo ""
echo "================================================"
echo -e "${GREEN}✓ Setup completado exitosamente${NC}"
echo "================================================"
echo ""
echo "Próximos pasos:"
echo "  1. Lee la documentación: docs/claude-code-setup.md"
echo "  2. Familiarízate con los comandos: claude --help"
echo "  3. Prueba: claude"
echo ""
echo "Comandos útiles:"
echo "  claude              - Modo interactivo"
echo "  claude -p \"...\"     - Prompt directo"
echo "  /help               - Ayuda de comandos"
echo ""
echo "Skills disponibles en este proyecto:"
if [ -d ".claude/skills" ]; then
    ls -1 .claude/skills/ | sed 's/^/  \//'
fi
echo ""

# Setup script para Claude Code en Windows
# Ejecutar con: powershell -ExecutionPolicy Bypass -File .\scripts\setup-claude.ps1
 
# Configuración
$ErrorActionPreference = "Stop"
 
# Funciones auxiliares
function Print-Step {
    param($Message)
    Write-Host "▶ $Message" -ForegroundColor Blue
}
 
function Print-Success {
    param($Message)
    Write-Host "✓ $Message" -ForegroundColor Green
}
 
function Print-Error {
    param($Message)
    Write-Host "✗ $Message" -ForegroundColor Red
}
 
function Print-Warning {
    param($Message)
    Write-Host "⚠ $Message" -ForegroundColor Yellow
}
 
# Header
Write-Host "================================================"
Write-Host "  Claude Code Setup Script (Windows)"
Write-Host "  Proyecto: $(Split-Path -Leaf (Get-Location))"
Write-Host "================================================"
Write-Host ""
 
# 1. Verificar Node.js
Print-Step "Verificando Node.js..."
try {
    $nodeVersion = node --version
    Print-Success "Node.js instalado: $nodeVersion"
} catch {
    Print-Error "Node.js no está instalado"
    Write-Host "Instala Node.js desde: https://nodejs.org/"
    exit 1
}
 
# 2. Instalar Claude Code
Print-Step "Instalando Claude Code..."
 
try {
    $claudeVersion = claude --version 2>&1 | Select-Object -First 1
    Print-Warning "Claude Code ya está instalado: $claudeVersion"
 
    $update = Read-Host "¿Deseas actualizar a la última versión? (y/n)"
    if ($update -eq "y") {
        npm install -g @anthropic-ai/claude-code@latest
        Print-Success "Claude Code actualizado"
    }
} catch {
    npm install -g @anthropic-ai/claude-code
    Print-Success "Claude Code instalado"
}
 
# Verificar instalación
try {
    $claudeVersion = claude --version 2>&1 | Select-Object -First 1
    Print-Success "Claude Code version: $claudeVersion"
} catch {
    Print-Error "Error al instalar Claude Code"
    exit 1
}
 
# 3. Configurar API Key
Print-Step "Configurando API Key..."
 
if ($env:ANTHROPIC_API_KEY) {
    Print-Success "API key ya configurada (variable de entorno)"
} elseif (Test-Path "$env:USERPROFILE\.claude\config") {
    Print-Success "API key ya configurada (archivo config)"
} else {
    Write-Host ""
    Write-Host "Necesitas una API key de Claude."
    Write-Host "Opciones:"
    Write-Host "  1) Tengo Claude Pro/Max (login con cuenta)"
    Write-Host "  2) Tengo API key de Anthropic"
    Write-Host ""
    $apiOption = Read-Host "Elige opción (1/2)"
 
    switch ($apiOption) {
        "1" {
            Print-Step "Iniciando login con Claude..."
            claude login
            Print-Success "Login completado"
        }
        "2" {
            $apiKey = Read-Host "Ingresa tu API key" -AsSecureString
            $apiKeyPlain = [Runtime.InteropServices.Marshal]::PtrToStringAuto(
                [Runtime.InteropServices.Marshal]::SecureStringToBSTR($apiKey)
            )
 
            [Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", $apiKeyPlain, "User")
            $env:ANTHROPIC_API_KEY = $apiKeyPlain
 
            Print-Success "API key configurada"
        }
        default {
            Print-Error "Opción inválida"
            exit 1
        }
    }
}
 
# 4. Instalar dependencias del proyecto
Print-Step "Instalando dependencias del proyecto..."
 
if (Test-Path "package.json") {
    if (Test-Path "package-lock.json") {
        npm ci
    } else {
        npm install
    }
    Print-Success "Dependencias de npm instaladas"
}
 
# 5. Verificar configuración de Claude
Print-Step "Verificando configuración de Claude Code..."
 
if (-not (Test-Path ".claude\CLAUDE.md")) {
    Print-Warning "No se encontró .claude\CLAUDE.md"
} else {
    Print-Success "CLAUDE.md encontrado"
}
 
if (-not (Test-Path ".claude\settings.json")) {
    Print-Warning "No se encontró .claude\settings.json"
} else {
    Print-Success "settings.json encontrado"
}
 
# 6. Validación final
Print-Step "Ejecutando validación final..."
 
Write-Host ""
Write-Host "Probando Claude Code..."
try {
    $claudeTest = claude -p "responde solo: OK" 2>&1
    if ($claudeTest -match "OK") {
        Print-Success "Claude Code funciona correctamente"
    } else {
        Print-Error "Claude Code no respondió correctamente"
        Write-Host "Output: $claudeTest"
        exit 1
    }
} catch {
    Print-Error "Error al probar Claude Code"
    Write-Host $_.Exception.Message
    exit 1
}
 
# Resumen final
Write-Host ""
Write-Host "================================================"
Write-Host "✓ Setup completado exitosamente" -ForegroundColor Green
Write-Host "================================================"
Write-Host ""
Write-Host "Próximos pasos:"
Write-Host "  1. Lee la documentación: docs\claude-code-setup.md"
Write-Host "  2. Familiarízate con los comandos: claude --help"
Write-Host "  3. Prueba: claude"
Write-Host ""
Write-Host "Skills disponibles:"
if (Test-Path ".claude\skills") {
    Get-ChildItem ".claude\skills" -Directory | ForEach-Object {
        Write-Host "  /$($_.Name)"
    }
}
Write-Host ""

# Linux/macOS
chmod +x scripts/setup-claude.sh
 
# Ejecutar
./scripts/setup-claude.sh

# Windows
# Ejecutar con PowerShell como admin
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
 
# Ejecutar
.\scripts\setup-claude.ps1

# Scripts de Setup
 
## setup-claude.sh / setup-claude.ps1
 
Automatiza la instalación y configuración de Claude Code para nuevos desarrolladores.
 
### Uso
 
**Linux/macOS:**
```bash
./scripts/setup-claude.sh

.\scripts\setup-claude.ps1

# Verifica que npm bin global esté en PATH
echo $PATH | grep npm
 
# En algunos sistemas necesitas añadir a PATH manualmente
export PATH="$PATH:$(npm root -g)/bin"

# Opción 1: Variable de entorno
export ANTHROPIC_API_KEY="tu-api-key"
 
# Opción 2: Login con cuenta
claude login

# Linux/macOS
chmod +x scripts/setup-claude.sh
 
# Windows (ejecutar PowerShell como admin)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude

 
---
 
## Paso 3: Pipeline de CI/CD
 
### 3.1 Configurar secrets
 
Primero, configura los secrets necesarios en tu plataforma CI/CD.
 
#### GitHub Actions
 
1. Ve a tu repositorio → **Settings** → **Secrets and variables** → **Actions**
2. Añade estos secrets:
 
| Secret | Valor | Uso |
|--------|-------|-----|
| `ANTHROPIC_API_KEY` | Tu API key de Claude | Para ejecutar Claude en CI |
| `GH_TOKEN` | GitHub Personal Access Token | Para comentar en PRs |
 
#### GitLab CI/CD
 
1. Ve a tu proyecto → **Settings** → **CI/CD** → **Variables**
2. Añade las mismas variables marcando "Masked" y "Protected"
 
---
 
### 3.2 Workflow 1: AI Code Review en PRs
 
Este workflow ejecuta un code review automático cada vez que se crea o actualiza un PR.
 
**Archivo:** `.github/workflows/ai-review.yml`
 
```yaml
name: AI Code Review
 
on:
  pull_request:
    types: [opened, synchronize, reopened]
    branches:
      - main
      - develop
 
# Evita ejecuciones concurrentes en el mismo PR
concurrency:
  group: ai-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true
 
jobs:
  ai-review:
    name: AI Code Review
    runs-on: ubuntu-latest
 
    # Solo ejecutar en PRs de ramas del mismo repo (no forks)
    if: github.event.pull_request.head.repo.full_name == github.repository
 
    permissions:
      contents: read
      pull-requests: write
 
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Necesario para git diff
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
 
      - name: Install Claude Code
        run: |
          npm install -g @anthropic-ai/claude-code
          claude --version
 
      - name: Get changed files
        id: changed-files
        run: |
          echo "files<<EOF" >> $GITHUB_OUTPUT
          git diff --name-only origin/${{ github.base_ref }}...HEAD >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT
 
      - name: Run AI Code Review
        id: review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # Crear directorio temporal para el reporte
          mkdir -p /tmp/review
 
          # Ejecutar review de los cambios
          claude --dangerously-skip-permissions -p "
          Analiza los cambios en este PR y genera un code review detallado.
 
          Archivos modificados:
          ${{ steps.changed-files.outputs.files }}
 
          Ejecuta: git diff origin/${{ github.base_ref }}...HEAD
 
          Genera un reporte en formato markdown con:
          1. Resumen ejecutivo
          2. Issues críticos (P1)
          3. Issues importantes (P2)
          4. Mejoras sugeridas (P3)
          5. Aspectos positivos
          6. Veredicto final (APROBADO/CAMBIOS REQUERIDOS)
 
          Guarda el reporte en /tmp/review/report.md
          " > /tmp/review/output.log 2>&1
 
          # Verificar que el reporte fue generado
          if [ ! -f /tmp/review/report.md ]; then
            echo "Error: No se generó el reporte de review"
            cat /tmp/review/output.log
            exit 1
          fi
 
      - name: Post review as comment
        uses: actions/github-script@v7
        with:
          github-token: ${{ secrets.GH_TOKEN }}
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('/tmp/review/report.md', 'utf8');
 
            const comment = `## 🤖 AI Code Review
 
            ${report}
 
            ---
            <sub>Generated by Claude Code • [View workflow run](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})</sub>
            `;
 
            // Buscar comentario anterior del bot
            const { data: comments } = await github.rest.issues.listComments({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
            });
 
            const botComment = comments.find(comment =>
              comment.user.type === 'Bot' &&
              comment.body.includes('🤖 AI Code Review')
            );
 
            // Actualizar o crear comentario
            if (botComment) {
              await github.rest.issues.updateComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                comment_id: botComment.id,
                body: comment
              });
            } else {
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.issue.number,
                body: comment
              });
            }
 
      - name: Upload review report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: ai-review-report
          path: /tmp/review/
          retention-days: 30
 
      - name: Check for critical issues
        run: |
          # Verificar si hay issues P1 (críticos)
          if grep -q "🔴.*P1" /tmp/review/report.md; then
            echo "⚠️ Se encontraron issues críticos (P1)"
            echo "critical_issues=true" >> $GITHUB_OUTPUT
            # No fallar el workflow, solo advertir
          fi

# Code Review
 
## 📊 Resumen
 
| Métrica | Valor |
|---------|-------|
| Archivos revisados | 5 |
| Líneas modificadas | +245, -87 |
| Issues encontrados | 3 |
| Distribución | 🔴 P1: 0, 🟠 P2: 1, 🟡 P3: 2 |
 
**Veredicto:** ⚠️ APROBADO CON COMENTARIOS
 
## 🔍 Issues encontrados
 
### 🟠 P2 - Alto
 
#### src/services/userService.ts:45 - Falta manejo de errores
 
**Problema:**
La función `createUser` no maneja el caso donde el email ya existe.
 
**Solución:**
```typescript
if (await this.userExists(email)) {
  throw new DuplicateEmailError(email);
}

 
---
 
### 3.3 Workflow 2: Detección de Breaking Changes
 
Detecta cambios que pueden romper la API pública o compatibilidad.
 
**Archivo:** `.github/workflows/breaking-changes.yml`
 
```yaml
name: Detect Breaking Changes
 
on:
  pull_request:
    types: [opened, synchronize]
    branches:
      - main
 
jobs:
  detect-breaking-changes:
    name: Detect Breaking Changes
    runs-on: ubuntu-latest
 
    permissions:
      contents: read
      pull-requests: write
 
    steps:
      - name: Checkout PR branch
        uses: actions/checkout@v4
        with:
          path: current
 
      - name: Checkout base branch
        uses: actions/checkout@v4
        with:
          ref: ${{ github.base_ref }}
          path: base
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
 
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
 
      - name: Detect breaking changes
        id: detect
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          cd current
 
          claude --dangerously-skip-permissions -p "
          Analiza los cambios entre la rama base y el PR para detectar breaking changes.
 
          Compara:
          - Base: ../base
          - Current: .
 
          Busca breaking changes en:
          1. **API pública** (exported functions, classes, types)
             - Funciones/métodos eliminados
             - Parámetros eliminados o cambiados
             - Returns types modificados
             - Interfaces/types modificados
 
          2. **Configuración**
             - Variables de entorno requeridas nuevas
             - Cambios en formato de configuración
 
          3. **Base de datos** (si aplica)
             - Migraciones que eliminan columnas
             - Cambios en schemas
 
          4. **Dependencias**
             - Major version bumps
             - Dependencias eliminadas
 
          Genera reporte en /tmp/breaking-changes.md con formato:
 
          # Breaking Changes Report
 
          ## ⚠️ Breaking Changes Detected: [YES/NO]
 
          [Si hay breaking changes, listar cada uno con:]
 
          ### [Categoría]: [Descripción breve]
 
          **Impact:** [Descripción del impacto]
 
          **Migration:**
          \`\`\`
          [Código o pasos para migrar]
          \`\`\`
 
          **Files affected:**
          - [archivo:línea]
 
          ---
 
          [Si NO hay breaking changes:]
 
          ✅ No se detectaron breaking changes.
          " > /tmp/detection.log 2>&1
 
          # Verificar resultado
          if [ -f /tmp/breaking-changes.md ]; then
            cat /tmp/breaking-changes.md
 
            # Detectar si hay breaking changes
            if grep -q "Breaking Changes Detected: YES" /tmp/breaking-changes.md; then
              echo "has_breaking_changes=true" >> $GITHUB_OUTPUT
            else
              echo "has_breaking_changes=false" >> $GITHUB_OUTPUT
            fi
          fi
 
      - name: Add label if breaking changes
        if: steps.detect.outputs.has_breaking_changes == 'true'
        uses: actions/github-script@v7
        with:
          github-token: ${{ secrets.GH_TOKEN }}
          script: |
            github.rest.issues.addLabels({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              labels: ['breaking-change']
            });
 
      - name: Comment on PR
        uses: actions/github-script@v7
        with:
          github-token: ${{ secrets.GH_TOKEN }}
          script: |
            const fs = require('fs');
            let report = '';
 
            if (fs.existsSync('/tmp/breaking-changes.md')) {
              report = fs.readFileSync('/tmp/breaking-changes.md', 'utf8');
            } else {
              report = '✅ No se detectaron breaking changes.';
            }
 
            const comment = `## 🔍 Breaking Changes Analysis
 
            ${report}
 
            ---
            <sub>Automated by Claude Code</sub>
            `;
 
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: comment
            });
 
      - name: Fail if breaking changes without confirmation
        if: steps.detect.outputs.has_breaking_changes == 'true'
        run: |
          # Verificar si el PR tiene el label "breaking-change-approved"
          # o si el título contiene "BREAKING:"
          PR_TITLE="${{ github.event.pull_request.title }}"
 
          if echo "$PR_TITLE" | grep -qi "BREAKING:"; then
            echo "✓ Breaking change reconocido en el título"
            exit 0
          fi
 
          # Si no está aprobado, fallar
          echo "⚠️ Breaking changes detectados"
          echo "Para aprobar:"
          echo "  1. Añade 'BREAKING:' al título del PR, o"
          echo "  2. Añade el label 'breaking-change-approved'"
          exit 1

name: Generate Changelog
 
on:
  push:
    branches:
      - main
  workflow_dispatch:  # Permite ejecución manual
 
jobs:
  generate-changelog:
    name: Generate Changelog
    runs-on: ubuntu-latest
 
    permissions:
      contents: write
 
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Necesario para todo el historial
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
 
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
 
      - name: Get last release tag
        id: last-release
        run: |
          LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
          if [ -z "$LAST_TAG" ]; then
            echo "tag=" >> $GITHUB_OUTPUT
            echo "range=HEAD" >> $GITHUB_OUTPUT
          else
            echo "tag=$LAST_TAG" >> $GITHUB_OUTPUT
            echo "range=$LAST_TAG..HEAD" >> $GITHUB_OUTPUT
          fi
 
      - name: Generate changelog
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude --dangerously-skip-permissions -p "
          Genera un changelog para los commits desde ${{ steps.last-release.outputs.range }}
 
          Ejecuta: git log ${{ steps.last-release.outputs.range }} --pretty=format:'%h %s (%an)' --no-merges
 
          Agrupa los commits por tipo (conventional commits):
          - ✨ Features (feat:)
          - 🐛 Bug Fixes (fix:)
          - 📚 Documentation (docs:)
          - ♻️ Refactoring (refactor:)
          - ✅ Tests (test:)
          - 🔧 Chores (chore:)
          - ⚡ Performance (perf:)
          - 💥 Breaking Changes (BREAKING:)
 
          Genera en formato:
 
          # Changelog
 
          ## [Unreleased]
 
          ### ✨ Features
          - [commit msg] ([hash](link))
 
          ### 🐛 Bug Fixes
          - [commit msg] ([hash](link))
 
          [etc...]
 
          ### Contributors
          - @username
 
          Guarda en CHANGELOG.md PREPENDING al archivo existente (no sobrescribir).
          Si no existe CHANGELOG.md, créalo.
 
          Formato de links: https://github.com/${{ github.repository }}/commit/{hash}
          " > /tmp/changelog-gen.log 2>&1
 
      - name: Commit changelog
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
 
          if git diff --quiet CHANGELOG.md; then
            echo "No changes to changelog"
          else
            git add CHANGELOG.md
            git commit -m "docs: update CHANGELOG.md [skip ci]"
            git push
          fi

#!/bin/bash
 
# Agente que genera/actualiza documentación automáticamente
 
set -e
 
DOCS_DIR="docs"
SRC_DIR="src"
 
echo "🤖 Documentation Agent"
echo "======================"
echo ""
 
# 1. Generar API docs desde código
echo "📚 Generando documentación de API..."
 
claude --dangerously-skip-permissions -p "
Analiza todos los archivos en $SRC_DIR/ y genera documentación de API.
 
Para cada módulo/servicio público:
1. Lee el código
2. Extrae funciones/clases públicas
3. Documenta:
   - Propósito
   - Parámetros
   - Returns
   - Ejemplos de uso
   - Errores posibles
 
Estructura en docs/api/:
- docs/api/services.md
- docs/api/controllers.md
- docs/api/utils.md
 
Usa formato markdown con:
- Table of contents
- Anchors para navegación
- Code examples
- Links cruzados entre módulos
"
 
echo "✓ API docs generados"
 
# 2. Actualizar README si es necesario
echo "📝 Verificando README..."
 
claude --dangerously-skip-permissions -p "
Lee el README.md actual y el código del proyecto.
 
Verifica que README incluya:
1. Descripción actualizada del proyecto
2. Instalación
3. Uso básico
4. API reference (link a docs/api/)
5. Contribución
6. License
 
Si falta algo o está desactualizado, actualiza el README.md
"
 
echo "✓ README verificado"
 
# 3. Generar changelog si hay commits nuevos
echo "📋 Actualizando changelog..."
 
COMMITS_SINCE_LAST=$(git log --oneline -n 20 | wc -l)
 
if [ "$COMMITS_SINCE_LAST" -gt 0 ]; then
    claude --dangerously-skip-permissions -p "
    Actualiza CHANGELOG.md con los últimos commits.
    Ejecuta: git log -20 --pretty=format:'%h %s'
    Agrupa por tipo (feat, fix, docs, etc.)
    "
    echo "✓ Changelog actualizado"
else
    echo "⊘ No hay commits nuevos"
fi
 
echo ""
echo "✅ Documentation Agent completado"

#!/bin/bash
 
# Agente que identifica código sin tests y los genera
 
set -e
 
echo "🤖 Test Generation Agent"
echo "========================"
echo ""
 
# 1. Identificar archivos sin tests
echo "🔍 Buscando archivos sin tests..."
 
claude --dangerously-skip-permissions -p "
Analiza el proyecto y encuentra archivos de código sin tests correspondientes.
 
Busca en src/ archivos .ts/.js/.py que NO tengan:
- Archivo .test.ts/.test.js/.test.py correspondiente
- Archivo .spec.ts/.spec.js
 
Genera reporte en /tmp/missing-tests.txt con:
- Ruta del archivo
- Complejidad estimada (líneas de código)
- Prioridad (alta si es service/controller, media si es util)
 
Formato:
src/services/paymentService.ts | 250 líneas | ALTA
"
 
if [ ! -f /tmp/missing-tests.txt ]; then
    echo "✓ Todos los archivos tienen tests"
    exit 0
fi
 
MISSING_COUNT=$(wc -l < /tmp/missing-tests.txt)
echo "⚠️ Encontrados $MISSING_COUNT archivos sin tests"
echo ""
 
# 2. Generar tests para archivos prioritarios
echo "✅ Generando tests..."
 
# Leer archivos de alta prioridad
HIGH_PRIORITY=$(grep "ALTA" /tmp/missing-tests.txt | cut -d'|' -f1 | tr -d ' ')
 
for file in $HIGH_PRIORITY; do
    if [ -f "$file" ]; then
        echo "  Generando tests para: $file"
 
        claude --dangerously-skip-permissions -p "
        Genera tests completos para $file
 
        Lee el archivo y crea tests con:
        - Happy paths
        - Edge cases
        - Error handling
        - Mocking de dependencias
 
        Guarda en la ubicación estándar de tests del proyecto.
        Ejecuta los tests para verificar que pasan.
        "
    fi
done
 
echo ""
echo "✅ Test Agent completado"
echo "Tests generados para archivos de alta prioridad"