← Volver al listado de tecnologías ← Índice de Everything Claude Code

Capítulo 5: Comandos Esenciales

Por: Artiko
claude-codecomandosslash-commandsworkflows

1. ¿Qué son los Slash Commands en Claude Code?

Los slash commands son la interfaz de alto nivel de Everything Claude Code (ECC). Cuando escribes /plan "add auth" en Claude Code, no estás ejecutando un simple script: estás invocando un agente especializado con contexto, herramientas y prompt engineering pre-configurado para esa tarea específica.

Cómo funciona el sistema

Claude Code tiene un sistema de custom slash commands que vive en el directorio .claude/commands/. Cuando instalas ECC (ya sea como plugin o manualmente), este directorio se popula con archivos .md — uno por comando. Claude Code escanea esos archivos al inicio de cada sesión y los registra como comandos disponibles.

El flujo de ejecución es:

sequenceDiagram
    participant U as Usuario
    participant CC as Claude Code
    participant FS as FileSystem
    participant A as Agente

    U->>CC: /plan "add Stripe payment"
    CC->>FS: Lee .claude/commands/plan.md
    CC->>CC: Interpola $ARGUMENTS = "add Stripe payment"
    CC->>A: Lanza agente con prompt del archivo
    A->>A: Ejecuta workflow: restate → breakdown → risks
    A->>U: Presenta plan + espera confirmación

Dónde viven los archivos

En una instalación típica de ECC:

~/.claude/commands/          # Comandos globales (disponibles en todos los proyectos)
├── plan.md
├── tdd.md
├── verify.md
├── ...

.claude/commands/            # Comandos locales del proyecto (mayor prioridad)
├── mi-comando-custom.md
└── ...

Los comandos locales (en el directorio del proyecto) tienen prioridad sobre los globales. Esto permite sobreescribir comportamiento de ECC para proyectos específicos.

Cómo Claude los carga y ejecuta

Cuando ejecutas un slash command:

  1. Claude Code busca el archivo .md correspondiente en .claude/commands/
  2. Lee el frontmatter YAML para obtener description y allowedTools
  3. Interpola $ARGUMENTS con el texto que escribiste después del comando
  4. Envía el contenido del archivo como prompt de sistema al agente
  5. El agente tiene acceso a las herramientas especificadas en allowedTools
  6. La respuesta del agente aparece en tu terminal

2. Anatomía de un Comando

Cada comando es un archivo Markdown con frontmatter YAML seguido del prompt del agente.

Estructura completa

---
description: Descripción corta que aparece en el autocompletado
allowedTools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
---

# Nombre del Comando

Eres un agente especializado en X. Tu objetivo es Y.

## Instrucciones

1. Primero, haz A con $ARGUMENTS
2. Luego, evalúa B
3. Por último, presenta C

## Formato de Output

Presenta el resultado en este formato:
...

El campo description

description: Restate requirements, assess risks, and create step-by-step plan

Esta descripción aparece en el autocompletado cuando escribes / en Claude Code. Es lo que el usuario ve antes de ejecutar el comando. Debe ser concisa y descriptiva.

El campo allowedTools

allowedTools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - WebSearch
  - Task

Este campo controla qué herramientas tiene disponible el agente durante la ejecución. Por seguridad, los comandos deberían solicitar solo las herramientas que realmente necesitan:

El marcador $ARGUMENTS

$ARGUMENTS es el mecanismo que permite pasar texto desde el usuario al prompt del agente.

---
description: Plan feature implementation
---

Crea un plan de implementación para: $ARGUMENTS

Sigue estos pasos:
1. Restate el requerimiento
2. ...

Cuando el usuario ejecuta /plan "add Stripe payment", Claude Code reemplaza $ARGUMENTS con "add Stripe payment" antes de enviar el prompt al agente.

3. El Sistema de $ARGUMENTS

Cómo funciona exactamente

$ARGUMENTS captura todo el texto que sigue al nombre del comando en la línea de entrada:

Entrada del usuarioValor de $ARGUMENTS
/plan "add auth""add auth"
/plan add user authentication with JWTadd user authentication with JWT
/verify quickquick
/verify(cadena vacía)

Comandos con $ARGUMENTS opcionales

Muchos comandos de ECC tienen comportamiento por defecto cuando no se pasan argumentos:

---
description: Run verification suite. Arguments: quick, full (default), pre-commit, pre-pr
---

Ejecuta la suite de verificación con modo: $ARGUMENTS

Si $ARGUMENTS está vacío, usa el modo "full" por defecto.

Modos disponibles:
- quick: solo build + types
- full: build + types + lint + tests + secrets
- pre-commit: subset optimizado para hooks
- pre-pr: suite completa con coverage report

Ejemplos de uso con $ARGUMENTS

# Argumento simple
/plan "add user authentication"

# Argumento con modo
/verify quick
/verify pre-commit
/verify pre-pr

# Argumento con contexto
/build-fix "TypeScript error in auth module"

# Sin argumento (usa default)
/tdd
/code-review
/learn

Múltiples argumentos como texto libre

$ARGUMENTS recibe el texto completo como string. Si necesitas estructurar múltiples parámetros, la convención en ECC es usar el texto natural:

/eval "coverage >= 80%, no critical errors, all types pass"
/quality-gate src/api/ strict
/prompt-optimize "explain authentication flow to a senior developer"

4. Comandos Core — Ciclo de Desarrollo

/plan

Sintaxis: /plan "descripción del feature"

Description: Restate requirements, assess risks, and create step-by-step implementation plan. WAIT for user CONFIRM before touching any code.

Descripción detallada:

El comando /plan invoca al agente planner, cuyo trabajo exclusivo es analizar y planificar — nunca escribir código. Es el punto de entrada ideal para cualquier feature nueva o refactor significativo.

El agente sigue esta secuencia:

  1. Restate requirements — Reformula el requerimiento con sus propias palabras para confirmar comprensión
  2. Explore codebase — Analiza los archivos relevantes existentes
  3. Break down into phases — Divide el trabajo en fases lógicas y secuenciales
  4. Identify dependencies — Identifica qué debe hacerse antes que qué
  5. Assess risks — Señala los puntos técnicos que pueden ser problemáticos
  6. WAIT for confirmation — Se detiene y espera tu “yes” antes de tocar cualquier archivo

Cuándo usarlo:

Ejemplo de output del planner:

PLAN: Add Stripe Payment Processing

## Requerimiento
Implementar procesamiento de pagos con Stripe: crear PaymentIntent,
confirmar pago desde el frontend, manejar webhooks de confirmación.

## Análisis del Codebase
- src/api/payments/ — directorio vacío, aquí van los nuevos endpoints
- src/services/ — ya existe AuthService, patrón a seguir
- src/db/schema.ts — hay tabla users, necesitamos tabla payments

## Fases de Implementación

### Fase 1: Backend (estimado: 3 archivos)
- [ ] src/services/StripeService.ts — wrapper del SDK de Stripe
- [ ] src/api/payments/create-intent.ts — endpoint POST /payments/intent
- [ ] src/api/payments/webhook.ts — endpoint POST /payments/webhook

### Fase 2: Base de datos
- [ ] src/db/migrations/004_add_payments.sql
- [ ] src/db/schema.ts — agregar tabla payments

### Fase 3: Frontend
- [ ] src/components/PaymentForm.tsx — formulario con Stripe Elements
- [ ] src/hooks/usePayment.ts — hook para manejar el flujo

## Dependencias
Fase 2 debe completarse antes de Fase 1 (los endpoints necesitan la tabla).
Fase 3 depende de que Fase 1 esté funcionando.

## Riesgos
- El webhook de Stripe requiere HTTPS en desarrollo (usar ngrok o Stripe CLI)
- Las claves de Stripe deben estar en variables de entorno, no en código
- El idempotency key es crítico para evitar cobros duplicados

¿Confirmas este plan? (yes/no)

/tdd

Sintaxis: /tdd o /tdd "descripción de la funcionalidad"

Description: Enforce test-driven development workflow. Scaffold interfaces, generate tests FIRST, then implement minimal code to pass. Ensure 80%+ coverage.

Descripción detallada:

El comando /tdd implementa el ciclo clásico de Test-Driven Development con una variación importante: el agente primero define las interfaces (tipos, contratos) antes de escribir los tests. Esto garantiza que los tests reflejen el contrato real de la API.

Ciclo completo:

stateDiagram-v2
    [*] --> DefineInterface : /tdd
    DefineInterface --> RED : interface definida
    RED --> GREEN : test falla (esperado)
    GREEN --> REFACTOR : test pasa
    REFACTOR --> RED : nuevo test
    REFACTOR --> [*] : coverage >= 80%

    state RED {
        [*] --> WriteTest
        WriteTest --> RunTest
        RunTest --> [*] : ✗ falla
    }

    state GREEN {
        [*] --> MinimalImplementation
        MinimalImplementation --> RunTest
        RunTest --> [*] : ✓ pasa
    }

    state REFACTOR {
        [*] --> CleanCode
        CleanCode --> RunAllTests
        RunAllTests --> [*] : todos pasan
    }

Ejemplo completo:

/tdd "UserService.createUser should validate email and hash password"

El agente:

  1. Define la interfaz primero:
// src/services/UserService.ts (interface)
interface CreateUserInput {
  email: string;
  password: string;
  name: string;
}

interface CreateUserResult {
  id: string;
  email: string;
  name: string;
  createdAt: Date;
}

interface UserService {
  createUser(input: CreateUserInput): Promise<CreateUserResult>;
}
  1. Escribe el test que FALLA (RED):
// src/services/__tests__/UserService.test.ts
describe('UserService.createUser', () => {
  it('should reject invalid email', async () => {
    await expect(
      userService.createUser({ email: 'not-an-email', password: 'pass123', name: 'Test' })
    ).rejects.toThrow('Invalid email format');
  });

  it('should hash password before storing', async () => {
    const result = await userService.createUser({
      email: '[email protected]',
      password: 'mypassword',
      name: 'Test User'
    });
    // Verify the stored user has hashed password, not plaintext
    const stored = await db.users.findById(result.id);
    expect(stored.password).not.toBe('mypassword');
    expect(stored.password).toMatch(/^\$2[aby]\$/); // bcrypt hash
  });
});
  1. Implementación mínima para pasar (GREEN):
// src/services/UserService.ts
export class UserServiceImpl implements UserService {
  async createUser(input: CreateUserInput): Promise<CreateUserResult> {
    if (!isValidEmail(input.email)) {
      throw new Error('Invalid email format');
    }
    const hashedPassword = await bcrypt.hash(input.password, 10);
    return db.users.create({ ...input, password: hashedPassword });
  }
}

  1. Refactor (sin cambiar comportamiento, solo mejorar estructura)

  2. Repite hasta alcanzar 80%+ de cobertura

Cuándo usarlo: Para cualquier funcionalidad nueva que tenga lógica de negocio clara. Especialmente valioso para validaciones, transformaciones de datos y casos de error.

/code-review

Sintaxis: /code-review o /code-review "path/to/file.ts"

Description: Review code quality, security, performance, and maintainability. Provide actionable feedback with severity levels.

Descripción detallada:

El agente de code review analiza el código en busca de problemas en cuatro dimensiones:

  1. Security — Inyección SQL, XSS, secrets hardcodeados, validación de inputs
  2. Performance — N+1 queries, re-renders innecesarios, loops O(n²)
  3. Maintainability — Funciones largas, acoplamiento excesivo, nombres confusos
  4. Quality — Cobertura de tests, manejo de errores, tipos correctos

Formato del output:

CODE REVIEW REPORT
==================

## Crítico (bloquea el merge)
- [SECURITY] src/api/users.ts:45 — SQL query construida con string concatenation
  Riesgo: SQL injection. Usar parámetros preparados.

- [SECURITY] src/config/database.ts:12 — Password hardcodeado en el código
  Riesgo: Exposición de credenciales. Mover a variables de entorno.

## Alto (debe resolverse)
- [PERFORMANCE] src/services/UserService.ts:78 — N+1 query en bucle
  Por cada user se ejecuta una query adicional. Usar JOIN o include.

## Medio (recomendado)
- [MAINTAINABILITY] src/api/auth.ts:120-180 — Función de 60 líneas
  Extraer validateToken() y refreshSession() como funciones separadas.

## Bajo (sugerencia)
- [QUALITY] src/utils/email.ts — Sin tests
  La función validateEmail() no tiene cobertura de tests.

## Resumen
- 2 críticos, 1 alto, 1 medio, 1 bajo
- Bloquea PR: Sí (por los 2 críticos)

Cuándo usarlo: Antes de abrir un PR, después de una sesión de pair programming con Claude, o cuando quieres una segunda opinión sobre un módulo específico.

/verify

Sintaxis: /verify o /verify quick o /verify pre-commit o /verify pre-pr

Description: Run full verification suite: build, types, lint, tests, secrets scan, log analysis. Report pass/fail with coverage.

Las 6 fases del verify:

flowchart LR
    A[Build] --> B[Types]
    B --> C[Lint]
    C --> D[Tests]
    D --> E[Secrets]
    E --> F[Logs]
    F --> G{Resultado}
    G -->|todo OK| H[✓ Ready for PR]
    G -->|falló| I[✗ Report detallado]

Modos disponibles:

ModoFases ejecutadasUso típico
quickBuild + TypesFeedback rápido durante desarrollo
full (default)Todas las 6 fasesAntes de commit importante
pre-commitBuild + Types + Lint + SecretsEn git hook pre-commit
pre-prTodas las 6 fases + reporte de coberturaAntes de abrir PR

Ejemplo de output completo:

VERIFICATION REPORT
===================
Mode: full | 2024-12-17 14:32:11

[1/6] BUILD ................... ✓ PASS (12.3s)
[2/6] TYPES ................... ✓ PASS (3.1s)
[3/6] LINT .................... ✓ PASS (2.8s) — 0 errors, 2 warnings
[4/6] TESTS ................... ✓ PASS (8.4s)
      Unit:        42/42 passed
      Integration: 8/8 passed
      Coverage:    87% (threshold: 80%) ✓
[5/6] SECRETS ................. ✓ PASS — No secrets detected
[6/6] LOGS .................... ⚠ WARN — 3 console.log() en producción

OVERALL: ✓ PASS (26.6s)
Warnings: 1 (non-blocking)
Ready for PR: YES

Cómo interpretar el reporte:

/build-fix

Sintaxis: /build-fix o /build-fix "descripción del error"

Description: Analyze build errors, identify root cause, and fix systematically. Run build again to confirm fix.

Descripción detallada:

El agente de build-fix ejecuta el build, analiza el output de error, identifica la causa raíz y aplica la corrección. A diferencia de simplemente “arreglar lo que dice el mensaje de error”, este agente sigue una estrategia:

  1. Captura el output completo del build
  2. Agrupa errores relacionados (un solo cambio puede resolver múltiples errores)
  3. Identifica el error más profundo en la cadena de dependencias
  4. Aplica la corrección
  5. Ejecuta el build nuevamente para confirmar
  6. Repite si hay más errores

Ejemplo de sesión:

BUILD-FIX SESSION
=================

Ejecutando build... ✗ FAIL

Errores encontrados (12 errores en 3 archivos):
- src/services/AuthService.ts:15 — Property 'userId' does not exist on type 'JWTPayload'
- src/services/AuthService.ts:23 — Property 'userId' does not exist on type 'JWTPayload'
- src/api/users.ts:8 — ...misma causa raíz

Análisis: El tipo JWTPayload fue refactorizado pero no se actualizó la interfaz.
Causa raíz: src/types/auth.ts — falta el campo userId

Aplicando fix en src/types/auth.ts...

Ejecutando build nuevamente... ✓ PASS (0 errores)

Cuándo invocarlo: Cuando tienes errores de build y no quieres invertir tiempo debuggeando manualmente. Especialmente útil después de upgrades de dependencias o refactors grandes.

/e2e

Sintaxis: /e2e o /e2e "flujo a testear"

Description: Generate E2E tests with Playwright using Page Object Model. Cover happy path and critical error scenarios.

Descripción detallada:

El agente de e2e analiza tu aplicación y genera tests de extremo a extremo con Playwright, usando el patrón Page Object Model (POM) para maintainability.

Page Object Model generado:

// tests/pages/LoginPage.ts — Page Object
export class LoginPage {
  constructor(private page: Page) {}

  async goto() {
    await this.page.goto('/login');
  }

  async fillEmail(email: string) {
    await this.page.fill('[data-testid="email-input"]', email);
  }

  async fillPassword(password: string) {
    await this.page.fill('[data-testid="password-input"]', password);
  }

  async submit() {
    await this.page.click('[data-testid="login-button"]');
  }

  async getErrorMessage() {
    return this.page.textContent('[data-testid="error-message"]');
  }
}
// tests/auth.spec.ts — Test con POM
import { LoginPage } from './pages/LoginPage';

test.describe('Authentication', () => {
  test('happy path: valid credentials redirect to dashboard', async ({ page }) => {
    const loginPage = new LoginPage(page);
    await loginPage.goto();
    await loginPage.fillEmail('[email protected]');
    await loginPage.fillPassword('validpassword');
    await loginPage.submit();
    await expect(page).toHaveURL('/dashboard');
  });

  test('error path: invalid credentials show error', async ({ page }) => {
    const loginPage = new LoginPage(page);
    await loginPage.goto();
    await loginPage.fillEmail('[email protected]');
    await loginPage.fillPassword('wrongpassword');
    await loginPage.submit();
    expect(await loginPage.getErrorMessage()).toContain('Invalid credentials');
  });
});

/refactor-clean

Sintaxis: /refactor-clean o /refactor-clean "path/"

Description: Remove dead code, unused imports, duplicate logic, and stale comments. Preserve all functionality.

Qué detecta y limpia:

  1. Dead code — Funciones y variables declaradas pero nunca usadas
  2. Unused imports — import statements que no se utilizan
  3. Duplicate logic — Código idéntico o casi idéntico en múltiples lugares
  4. Stale comments — Comentarios // TODO viejos, código comentado
  5. Magic numbers — Números hardcodeados sin constante nombrada
  6. God functions — Funciones que hacen demasiadas cosas (>30 líneas)

Ejemplo de output:

REFACTOR-CLEAN REPORT
=====================

Archivos analizados: 47
Archivos modificados: 8

Cambios aplicados:
- src/utils/helpers.ts — Eliminadas 3 funciones sin uso (formatDate, parseQuery, sleep)
- src/api/users.ts — Removidos 5 imports sin usar
- src/services/AuthService.ts — Extraída función validateToken() (líneas 45-78)
- src/components/UserCard.tsx — Eliminado bloque de código comentado (líneas 23-41)

Líneas eliminadas: 127
Líneas refactorizadas: 34
Funcionalidad preservada: ✓ (todos los tests pasan)

5. Comandos de Calidad y Verificación

/quality-gate

Sintaxis: /quality-gate o /quality-gate "src/api/" o /quality-gate strict

Description: Run quality checks against configurable thresholds. Block or warn based on coverage, complexity, duplication.

Checks que ejecuta:

CheckThreshold defaultConfigurable
Test coverage>= 80%Sí
Cyclomatic complexity<= 10 por funciónSí
Code duplication<= 5%Sí
Max function length<= 30 líneasSí
Max file length<= 150 líneasSí
TypeScript strict modehabilitadoSí

Configuración de thresholds (en .claude/quality-gate.json):

{
  "coverage": { "min": 80, "block": true },
  "complexity": { "max": 10, "block": false },
  "duplication": { "max": 5, "block": true },
  "functionLength": { "max": 30, "block": false },
  "fileLength": { "max": 150, "block": false }
}

Output:

QUALITY GATE REPORT
===================
Mode: default | Path: src/

Coverage:       87% ✓ (min: 80%)
Complexity:     Avg 4.2, Max 12 ⚠ (1 función supera 10)
Duplication:    2.3% ✓ (max: 5%)
Function length: Max 28 líneas ✓ (max: 30)
File length:    Max 143 líneas ✓ (max: 150)

RESULT: ✓ PASS (1 warning, 0 blocking failures)

/test-coverage

Sintaxis: /test-coverage o /test-coverage "src/services/"

Description: Analyze test coverage, identify untested paths, and generate missing tests for critical code.

Descripción detallada:

El agente analiza el reporte de cobertura generado por tu test runner (Jest, Vitest, etc.) e identifica:

  1. Líneas sin cobertura — Código que nunca se ejecuta en los tests
  2. Branches sin cobertura — Condiciones if/else donde solo se testea un lado
  3. Funciones sin tests — Funciones exportadas sin ningún test
  4. Cobertura por módulo — Desglosa la cobertura por directorio/archivo

Output de análisis:

TEST COVERAGE ANALYSIS
======================

Global:    87% lines | 82% branches | 91% functions | 87% statements

Módulos bajo threshold (80%):
- src/services/PaymentService.ts  — 45% (crítico)
- src/utils/validation.ts         — 71% (advertencia)

Top 5 funciones sin tests:
1. PaymentService.handleWebhook() — 0 tests
2. PaymentService.refundPayment() — 0 tests
3. validation.validateCreditCard() — 0 tests
4. validation.sanitizeAmount() — 0 tests
5. AuthService.revokeAllTokens() — 1 test (solo happy path)

Generando tests para funciones críticas...

Luego el agente genera los tests faltantes para las funciones identificadas.

/checkpoint

Sintaxis: /checkpoint o /checkpoint "nombre del checkpoint"

Description: Save current verification state, git status, and test results. Create restoration point.

Qué guarda:

Un checkpoint guarda:

Archivo generado (.claude/checkpoints/checkpoint-{timestamp}.json):

{
  "timestamp": "2024-12-17T14:32:11Z",
  "name": "before-payment-refactor",
  "git": {
    "commit": "abc123",
    "branch": "feature/payments",
    "dirty": false
  },
  "verification": {
    "build": "pass",
    "types": "pass",
    "lint": "pass",
    "tests": { "passed": 50, "failed": 0, "coverage": 87 },
    "secrets": "pass"
  },
  "notes": "Estado estable antes de refactorear PaymentService"
}

Cómo restaurar: El checkpoint no hace rollback del código (para eso está git), pero te da contexto exacto del estado en ese momento para comparación.

/eval

Sintaxis: /eval "criterios de éxito"

Description: Evaluate current state against success criteria. Support pass@k and threshold-based evaluation.

Framework de evaluación:

El agente de eval soporta dos modos de evaluación:

Threshold-based (criterios concretos):

/eval "coverage >= 80%, no TypeScript errors, no critical security issues, all tests pass"
EVALUATION REPORT
=================
Criterios evaluados:

✓ coverage >= 80%        — Actual: 87% [PASS]
✓ no TypeScript errors   — Actual: 0 errores [PASS]
✗ no critical security   — Encontrado: 1 SQL injection en users.ts [FAIL]
✓ all tests pass         — 50/50 pasando [PASS]

RESULTADO: FAIL (1/4 criterios falló)
Bloqueante: SQL injection debe resolverse antes de continuar

pass@k (para evaluar prompts y generación de código):

/eval "pass@3: generated code compiles and passes unit tests"

El agente ejecuta el código generado 3 veces y reporta cuántas veces pasó todos los criterios.

/prompt-optimize

Sintaxis: /prompt-optimize "prompt a optimizar"

Description: Analyze and optimize a prompt for clarity, token efficiency, and better model response quality.

Ejemplo de antes/después:

Antes:

/prompt-optimize "can you please look at this code and tell me if there are any
problems with it and maybe suggest some improvements if you think that would be
helpful and also let me know if the tests look good thanks"

Después (output del agente):

PROMPT OPTIMIZATION
===================

Original (47 palabras, estimado ~60 tokens):
"can you please look at this code and tell me if there are any problems..."

Problemas identificados:
- Lenguaje cortés redundante ("can you please", "thanks")
- Múltiples solicitudes vagas en una sola oración
- Falta de contexto sobre qué código

Versión optimizada (18 palabras, estimado ~23 tokens — 62% reducción):
"Review this code: identify security issues, performance problems, and test coverage gaps."

Mejoras:
- 62% menos tokens
- Tres tareas específicas y medibles
- Tono directo apropiado para LLM
- Resultado esperado claramente definido

6. Comandos de Aprendizaje e Instincts

/learn

Sintaxis: /learn

Description: Analyze current session to extract reusable patterns, conventions, and decisions. Save as instincts.

Qué analiza:

El agente de /learn revisa:

  1. El historial de la sesión actual
  2. Los archivos que se modificaron
  3. Los patrones de código que se aplicaron
  4. Las decisiones de arquitectura tomadas
  5. Los errores que se cometieron y cómo se resolvieron

Formato del instinct guardado (.claude/instincts/instinct-{timestamp}.json):

{
  "id": "inst-20241217-001",
  "source": "session-2024-12-17",
  "confidence": 0.85,
  "category": "error-handling",
  "pattern": {
    "trigger": "async function that calls external API",
    "convention": "Wrap in try-catch, log error with context, return Result type",
    "example": "async function fetchUser(id: string): Promise<Result<User, ApiError>>",
    "antipattern": "Throwing raw errors without context from async boundaries"
  },
  "tags": ["typescript", "api", "error-handling"],
  "appliedIn": ["src/services/UserService.ts", "src/api/payments.ts"]
}

/learn-eval

Sintaxis: /learn-eval

Description: Extract patterns from session AND evaluate their quality before saving. Higher confidence threshold.

Diferencia con /learn:

/learn/learn-eval
Extrae patronesSíSí
Evalúa calidadNoSí
Threshold de confianza0.60.8
Descarta patrones dudososNoSí
Tiempo de ejecuciónRápidoMás lento

Qué evalúa extra:

Cuándo usar /learn-eval vs /learn:

/instinct-status

Sintaxis: /instinct-status

Description: Show all learned instincts with confidence scores, usage frequency, and health status.

Formato del output:

INSTINCT STATUS REPORT
======================
Total instincts: 23
Avg confidence: 0.81

Por categoría:
  error-handling    [8 instincts] avg: 0.87 ████████░░
  typescript        [6 instincts] avg: 0.79 ███████░░░
  testing           [5 instincts] avg: 0.83 ████████░░
  architecture      [4 instincts] avg: 0.76 ███████░░░

Top instincts por confianza:
1. inst-20241217-003 [0.97] — Use Result type for async errors
   Usado: 12 veces | Última vez: hace 2 días

2. inst-20241215-001 [0.93] — Validate inputs at API boundary
   Usado: 8 veces | Última vez: hace 5 días

3. inst-20241210-007 [0.91] — Extract domain logic from controllers
   Usado: 6 veces | Última vez: hace 1 semana

Instincts con baja confianza (candidatos a revisar):
- inst-20241201-002 [0.41] — Use global error handler
  (conflicta con inst-20241217-003)

Cómo interpretar la confianza:

/instinct-import

Sintaxis: /instinct-import "path/to/instincts.json" o /instinct-import "@username"

Description: Import instincts from a JSON file or shared profile. Merge with existing, resolving conflicts.

Formato JSON de importación:

{
  "version": "1.0",
  "author": "senior-dev",
  "instincts": [
    {
      "id": "ext-001",
      "category": "security",
      "confidence": 0.95,
      "pattern": {
        "trigger": "user input used in database query",
        "convention": "Always use parameterized queries, never string concatenation",
        "antipattern": "db.query(`SELECT * FROM users WHERE id = ${userId}`)"
      },
      "tags": ["security", "sql", "injection"]
    }
  ]
}

Proceso de merge:

  1. Valida el formato del archivo
  2. Verifica que no haya conflictos con instincts existentes
  3. Si hay conflictos, pregunta cómo resolverlos (conservar existente, conservar nuevo, merge)
  4. Ajusta la confianza según la fuente (instincts externos empiezan con 0.6 de confianza)
  5. Importa y reporta

/instinct-export

Sintaxis: /instinct-export o /instinct-export "path/output.json"

Description: Export all instincts above confidence threshold to a shareable JSON file.

Qué exporta: Por defecto, exporta todos los instincts con confianza >= 0.7. Genera el mismo formato JSON que acepta /instinct-import para compartir entre equipos.

/evolve

Sintaxis: /evolve o /evolve "categoria"

Description: Promote high-confidence instincts into reusable skills. Analyze patterns and generate skill files.

Cuándo evolucionar instincts a skills:

CondiciónDescripción
Instinct con confianza >= 0.9Alta confianza acumulada
Instinct usado 10+ vecesPatrón frecuente y validado
Grupo de instincts relacionadosVarios instincts sobre el mismo tema
Instinct que requiere tool callsNecesita herramientas para aplicarse

Diferencia entre instinct y skill:

7. Comandos de Multi-Agente

/orchestrate

Sintaxis: /orchestrate "tarea compleja"

Description: Coordinate multiple specialized agents to complete a complex task. Assign subtasks and synthesize results.

Descripción detallada:

/orchestrate es el comando maestro de multi-agente. Analiza la tarea, la descompone en subtareas especializadas, lanza agentes paralelos para cada una y sintetiza los resultados.

flowchart TD
    U[/orchestrate "implementar auth completo"/] --> O[Orchestrator]
    O --> A1[Agente Backend\nJWT + endpoints]
    O --> A2[Agente Frontend\nLogin form + hooks]
    O --> A3[Agente DB\nSchema + migrations]
    A1 --> S[Synthesizer]
    A2 --> S
    A3 --> S
    S --> R[Resultado integrado]

Cuándo usarlo: Para tareas que abarcan múltiples partes del stack y pueden trabajarse en paralelo. El orchestrator gestiona las dependencias y asegura que los resultados sean coherentes entre sí.

/multi-plan

Sintaxis: /multi-plan "feature a planificar"

Description: Create implementation plan using multiple AI models for diverse perspectives. Synthesize into consensus plan.

Descripción detallada:

Lanza el mismo prompt de planificación a múltiples modelos (Claude Opus, Claude Sonnet, etc.) y sintetiza sus perspectivas en un plan consensuado. Útil para features donde quieres múltiples perspectivas antes de comprometerte con una arquitectura.

/multi-execute

Sintaxis: /multi-execute "plan a ejecutar"

Description: Execute a multi-phase plan with specialized agents per phase. Handle dependencies and rollback on failure.

Descripción detallada:

A diferencia de /orchestrate (que descompone la tarea en paralelo), /multi-execute sigue un plan con dependencias explícitas:

  1. Lee el plan (puede ser el output de /multi-plan o /plan)
  2. Identifica las dependencias entre fases
  3. Ejecuta fases independientes en paralelo
  4. Bloquea fases dependientes hasta que sus prerequisitos completen
  5. Si una fase falla, ejecuta rollback controlado

Manejo de dependencias:

flowchart LR
    DB[Fase 1: DB Schema] --> BE[Fase 2: Backend API]
    BE --> FE[Fase 3: Frontend]
    BE --> T[Fase 2b: Tests API]
    FE --> E2E[Fase 4: E2E Tests]
    T --> E2E

/multi-backend

Sintaxis: /multi-backend "cambio a implementar en todos los servicios"

Description: Orchestrate backend changes across multiple services. Handle service discovery and API contracts.

Uso típico: Cuando tienes una arquitectura de microservicios y necesitas propagar un cambio a través de múltiples servicios (por ejemplo, agregar un campo a la API compartida).

/multi-frontend

Sintaxis: /multi-frontend "componente o feature"

Description: Orchestrate frontend changes: component library, applications, and storybook. Keep design system in sync.

Uso típico: Cuando tienes múltiples aplicaciones frontend que comparten un design system y necesitas actualizar un componente en todos.

/multi-workflow

Sintaxis: /multi-workflow "workflow a ejecutar"

Description: Execute a complex workflow across multiple domains. General-purpose multi-agent coordinator.

Descripción detallada:

El más general de los comandos multi-agente. No está especializado en backend o frontend, sino que puede coordinar cualquier tipo de agentes especializados para workflows complejos.

8. Comandos de Session Management

/sessions

Sintaxis: /sessions o /sessions list o /sessions show {id}

Description: Manage session history. List, inspect, and restore previous work sessions.

Output de /sessions list:

SESSIONS
========
ID              Date              Duration  Tasks  Status
sess-20241217   2024-12-17 14:00  2h 15m   8      completed
sess-20241216   2024-12-16 10:30  45m      3      completed
sess-20241215   2024-12-15 09:00  3h 40m   12     completed (checkpoint)
sess-20241214   2024-12-14 16:00  1h 20m   5      interrupted

Output de /sessions show sess-20241217:

SESSION: sess-20241217
======================
Date: 2024-12-17 14:00 - 16:15
Duration: 2h 15m

Tasks completadas:
1. /plan "add Stripe payment" — DONE
2. /tdd — DONE (PaymentService, 8 tests)
3. /build-fix — DONE (3 errores TypeScript)
4. /code-review — DONE (2 issues encontrados)
5. /verify — DONE (87% coverage, all pass)

Archivos modificados: 12
Tests generados: 8
Instincts aprendidos: 3

/save-session

Sintaxis: /save-session o /save-session "nombre descriptivo"

Description: Save current session state to disk for later resumption.

Qué guarda y dónde:

Guarda en .claude/sessions/{id}/:

/resume-session

Sintaxis: /resume-session o /resume-session {session-id}

Description: Resume a previously saved session. Restore context and continue from where you left off.

Cómo continúa el trabajo anterior:

  1. Carga el context guardado de la sesión anterior
  2. Presenta un resumen de qué se hizo y qué quedó pendiente
  3. Sugiere el próximo paso basándose en las tareas incompletas
  4. Restaura las preferencias y configuraciones de la sesión

/projects

Sintaxis: /projects o /projects list o /projects switch {nombre}

Description: Manage multiple project contexts. Switch between projects with different configurations.

Caso de uso: Cuando trabajas en múltiples proyectos y cada uno tiene configuraciones diferentes de ECC, este comando permite cambiar de contexto sin confundir configuraciones.

9. Comandos de Autonomous Loops (v1.8)

/loop-start

Sintaxis: /loop-start "objetivo" o /loop-start --type=pr "descripción del PR"

Description: Start an autonomous execution loop. Types: sequential, pr-loop, dag. Define stop conditions.

Tipos de loops:

Sequential — Ejecuta una secuencia de pasos hasta que se cumpla una condición:

/loop-start --type=sequential "keep running tests until all pass"

PR Loop — Ciclo de code review y fix hasta que el PR esté listo:

/loop-start --type=pr "implement auth feature and get it PR-ready"
# El loop ejecuta: code → test → review → fix → test → review → ...
# Se detiene cuando /code-review no encuentra issues críticos

DAG — Ejecuta un grafo dirigido acíclico de tareas con dependencias:

/loop-start --type=dag "implement full payment feature"
# Define el DAG y lo ejecuta respetando dependencias

Condiciones de parada:

/loop-status

Sintaxis: /loop-status

Description: Show current loop status, completed steps, remaining tasks, and checkpoint history.

Output:

LOOP STATUS
===========
Loop ID: loop-20241217-001
Type: pr-loop
Objetivo: implement auth feature and get it PR-ready
Estado: RUNNING
Iteración: 3/10 (max)

Completado:
✓ Iteration 1: Initial implementation
  - AuthService.ts creado
  - 4 tests pasando
  - /code-review: 2 issues encontrados

✓ Iteration 2: Fix issues from review
  - SQL injection fixed
  - Input validation added
  - /code-review: 0 issues críticos

En progreso:
→ Iteration 3: Final verification
  - /verify en ejecución...

Próximo checkpoint: al completar iteración 3
Condición de parada: /code-review sin issues críticos ✓ (alcanzada)

/harness-audit

Sintaxis: /harness-audit

Description: Audit the ECC harness configuration: loop settings, model routing, safety controls, and risk posture.

Qué evalúa:

  1. Loop configuration — Límites de iteraciones, condiciones de parada
  2. Model routing — Si los modelos están correctamente configurados para cada tipo de tarea
  3. Safety controls — Si hay controles humanos en los puntos críticos
  4. Resource limits — Límites de tokens, tiempo, y costo
  5. Risk posture — Evaluación general del riesgo de la configuración

Output:

HARNESS AUDIT REPORT
====================

Loop Configuration: ✓ OK
  - Max iterations: 10 (razonable)
  - Stop conditions: definidas y verificables
  - Checkpoint interval: cada 2 iteraciones

Model Routing: ✓ OK
  - Complex tasks → Claude Opus
  - Simple tasks → Claude Haiku
  - Thresholds configurados

Safety Controls: ⚠ WARNING
  - Falta confirmación humana antes de writes a producción
  - Recomendado: agregar human-in-the-loop para cambios en DB

Resource Limits: ✓ OK
  - Max tokens por loop: 100k
  - Timeout: 30 minutos

RISK POSTURE: MEDIUM
Acción requerida: Configurar human-in-the-loop para cambios en DB

/model-route

Sintaxis: /model-route "descripción de tarea" o /model-route --analyze

Description: Route a task to the optimal model based on complexity and budget. Show routing decision with reasoning.

Criterios de ruteo:

ComplejidadModelo sugeridoUso típico
Alta (score > 7)Claude OpusArquitectura, diseño, análisis complejo
Media (score 4-7)Claude SonnetImplementación, code review, TDD
Baja (score < 4)Claude HaikuFormateo, documentación, tareas simples

Cálculo del score de complejidad:

Output de /model-route --analyze:

MODEL ROUTING ANALYSIS
======================

Tarea: "Implement OAuth2 flow with Google"

Score de complejidad: 8/10
  +2 múltiples dominios (auth, API, DB)
  +2 seguridad crítica
  +2 integración externa (Google API)
  +1 estado complejo (tokens, refresh)
  +1 código nuevo sin patrones existentes

Recomendación: Claude Opus
Razón: Tarea de alta complejidad con implicaciones de seguridad

Costo estimado:
  Claude Opus: ~$0.18 (estimado)
  Claude Sonnet: ~$0.06 (50% más barato, suficiente para esta tarea)

¿Continuar con Opus o usar Sonnet? (opus/sonnet)

10. Comandos de Skills

/skill-create

Sintaxis: /skill-create o /skill-create "nombre-del-skill"

Description: Analyze git history to extract recurring patterns and generate a reusable skill file.

Cómo funciona:

  1. Analiza el git log de los últimos 30-90 días
  2. Identifica commits relacionados con operaciones recurrentes
  3. Agrupa commits por patrón de cambio
  4. Genera un archivo de skill que captura ese patrón
  5. Guarda en .claude/skills/

Ejemplo: Si el agente detecta que cada vez que agregas un endpoint haces los mismos pasos (crear handler, agregar route, crear test, actualizar docs), genera un skill add-api-endpoint que automatiza esos pasos.

Output:

SKILL CREATION ANALYSIS
=======================

Git history analizado: 90 días, 247 commits

Patrones detectados:
1. "Add API endpoint" — 23 ocurrencias
   Pasos identificados: handler → route → test → swagger
   Confianza: 0.91

2. "Add database migration" — 15 ocurrencias
   Pasos identificados: migration → seed → update schema types
   Confianza: 0.87

3. "Fix TypeScript error" — 8 ocurrencias
   Pasos identificados: identify type → fix → run typecheck → test
   Confianza: 0.73

Generando skills...
✓ .claude/skills/add-api-endpoint.md — creado
✓ .claude/skills/add-db-migration.md — creado

/skill-health

Sintaxis: /skill-health

Description: Verify all installed skills are valid, up-to-date, and compatible with current codebase.

Qué verifica:

  1. Que cada skill tenga frontmatter válido
  2. Que los archivos referenciados en el skill aún existen
  3. Que los comandos del skill sean válidos en el entorno actual
  4. Que no haya conflictos entre skills

Output:

SKILL HEALTH REPORT
===================

Skills instalados: 12
Skills verificados: 12

Estado:
✓ add-api-endpoint.md — saludable
✓ add-db-migration.md — saludable
⚠ deploy-to-aws.md — ADVERTENCIA: referencia a .env.aws que no existe
✗ run-integration-tests.md — ERROR: comando 'jest --integration' ya no existe
  Sugerencia: actualizar a 'vitest run --mode=integration'

Resumen: 10 saludables, 1 advertencia, 1 error

/rules-distill

Sintaxis: /rules-distill

Description: Analyze codebase patterns and session history. Distill into CLAUDE.md rules for consistent behavior.

Qué analiza:

El agente analiza:

Output (propuesta de reglas para CLAUDE.md):

RULES DISTILLATION
==================

Basado en análisis de 90 días de historial y 23 sesiones:

Nuevas reglas propuestas para CLAUDE.md:

### Patrones de Código
- Siempre usar Result<T, E> para funciones async que llaman APIs externas
- Los controllers no deben contener lógica de negocio
- Cada endpoint debe tener al menos un test de integración

### Convenciones de Nombres
- Servicios: sufijo Service (UserService, PaymentService)
- Repositorios: sufijo Repository (UserRepository)
- Tests: mismo nombre que el archivo + .test.ts

### Seguridad
- Validar todos los inputs en la capa API
- Nunca loggear contraseñas, tokens, o datos PII

¿Agregar estas reglas a CLAUDE.md? (yes/edit/no)

11. Comandos Language-Specific

Go

/go-review

Sintaxis: /go-review o /go-review "./pkg/..."

Description: Review Go code: idiomatic patterns, error handling, goroutine safety, interface design.

Analiza el código Go buscando:

/go-test

Sintaxis: /go-test

Description: Run TDD workflow for Go: table-driven tests, benchmarks, and subtests. Use testing.T conventions.

Implementa TDD con el estilo idiomático de Go:

/go-build

Sintaxis: /go-build

Description: Fix Go build errors: imports, missing types, interface compliance.

Especializado en errores comunes de Go:

Python

/python-review

Sintaxis: /python-review o /python-review "src/"

Description: Review Python code: PEP 8, type hints, security (bandit), and performance (memory, CPU).

Analiza:

C++

/cpp-review

Sintaxis: /cpp-review

Description: Review C++ code: memory management, RAII, modern C++ idioms (C++17/20), undefined behavior.

Analiza:

/cpp-test

Sintaxis: /cpp-test

Description: Generate C++ tests with Google Test / Catch2. Cover edge cases and undefined behavior.

/cpp-build

Sintaxis: /cpp-build

Description: Fix C++ build errors: CMake, compiler flags, linker errors, header dependencies.

Kotlin

/kotlin-review

Sintaxis: /kotlin-review

Description: Review Kotlin code: nullability, coroutines, data classes, extension functions, Android idioms.

/kotlin-test

Sintaxis: /kotlin-test

Description: Generate Kotlin tests with JUnit5/Kotest. Handle coroutines testing with TestCoroutineDispatcher.

/kotlin-build

Sintaxis: /kotlin-build

Description: Fix Kotlin/Gradle build errors: dependency conflicts, kapt issues, AGP compatibility.

Rust

/rust-review

Sintaxis: /rust-review

Description: Review Rust code: ownership, borrowing, lifetimes, unsafe blocks, and idiomatic patterns.

Analiza:

/rust-test

Sintaxis: /rust-test

Description: Generate Rust tests: unit tests in-module, integration tests in tests/, doctests, property tests.

/rust-build

Sintaxis: /rust-build

Description: Fix Rust build errors: borrow checker, lifetime annotations, trait bounds, cargo issues.

Java/Gradle

/gradle-build

Sintaxis: /gradle-build

Description: Fix Gradle build errors: dependency resolution, task configuration, plugin compatibility.

Especializado en errores del ecosistema Gradle:

12. Comandos de Documentación

/update-docs

Sintaxis: /update-docs o /update-docs "src/services/"

Description: Update documentation to reflect current code state. Fix outdated examples and broken references.

Qué archivos actualiza:

  1. README.md — Actualiza el setup, comandos, y arquitectura si cambiaron
  2. CONTRIBUTING.md — Actualiza el proceso de desarrollo si cambió
  3. Comentarios JSDoc/TSDoc en el código — Actualiza cuando la firma de la función cambió
  4. openapi.yaml / swagger.json — Si los endpoints cambiaron
  5. Archivos de docs específicos del proyecto (docs/, documentation/)

/update-codemaps

Sintaxis: /update-codemaps

Description: Regenerate codebase maps (architecture, dependencies, API surface). Used for context optimization.

Qué son los codemaps:

Los codemaps son archivos generados que describen la estructura del proyecto de forma compacta para que Claude pueda entender la arquitectura sin necesitar leer todos los archivos. Se guardan en .claude/codemaps/:

.claude/codemaps/
├── architecture.md     # Vista de alto nivel de la arquitectura
├── dependencies.json   # Grafo de dependencias entre módulos
├── api-surface.md      # Todas las interfaces públicas
└── file-index.json     # Índice de todos los archivos con descripción

Cuándo actualizar: Después de refactors grandes, cuando agregas nuevos módulos, o cuando el agente parece confundido sobre la estructura del proyecto.

/docs

Sintaxis: /docs "pregunta o tema"

Description: Search and present relevant documentation from the codebase and external sources.

Cómo funciona:

  1. Busca en la documentación interna del proyecto (README, docs/, comentarios)
  2. Busca en los codemaps generados
  3. Si no encuentra suficiente información interna, puede buscar documentación externa
  4. Presenta la información relevante de forma estructurada

13. Comandos de Configuración

/setup-pm

Sintaxis: /setup-pm

Description: Detect and configure package manager (npm, yarn, pnpm, bun). Update scripts and configuration.

Detección automática:

flowchart TD
    A[/setup-pm] --> B{bun.lockb existe?}
    B -->|Sí| C[Configura Bun]
    B -->|No| D{pnpm-lock.yaml?}
    D -->|Sí| E[Configura pnpm]
    D -->|No| F{yarn.lock?}
    F -->|Sí| G[Configura Yarn]
    F -->|No| H[Configura npm]

Actualiza .claude/config.json con el package manager detectado para que todos los comandos que ejecutan install, run, etc. usen el correcto.

/context-budget

Sintaxis: /context-budget o /context-budget --analyze

Description: Analyze and optimize context window usage. Identify what's consuming tokens and suggest optimizations.

Descripción detallada:

El context window de Claude es limitado. Este comando analiza qué está consumiendo tokens en tu sesión actual:

CONTEXT BUDGET ANALYSIS
========================
Contexto total disponible: 200,000 tokens
Contexto usado: 87,432 tokens (43.7%)

Distribución:
- System prompt:      8,400 tokens  (9.6%)
- Conversation:      45,200 tokens (51.7%)
- Archivos abiertos: 33,832 tokens (38.7%)

Top archivos por consumo:
1. src/generated/schema.ts   — 12,400 tokens (considerar lazy loading)
2. package-lock.json          — 8,200 tokens  (excluir del contexto)
3. src/api/openapi.yaml       — 6,100 tokens  (usar /docs en su lugar)

Estimado restante: 112,568 tokens (~60% de sesión disponible)

Recomendaciones:
- Excluir package-lock.json del contexto
- Usar codemaps en lugar de abrir archivos grandes

/claw

Sintaxis: /claw "task"

Description: Execute task using NanoClaw integration. Optimized for token-efficient, fast operations.

Descripción detallada:

NanoClaw es el “modo nano” de ECC — optimizado para operaciones frecuentes con el mínimo de tokens posibles. /claw invoca tareas usando prompts ultra-compactos, apropiado para operaciones repetitivas donde el costo de tokens importa.

Cuándo usar:

/devfleet

Sintaxis: /devfleet o /devfleet status o /devfleet scale {n}

Description: Manage a fleet of development agents. Scale, monitor, and coordinate parallel work.

Descripción detallada:

Permite gestionar múltiples instancias de agentes trabajando en paralelo en diferentes partes del codebase. Útil para proyectos grandes donde quieres paralelizar el trabajo de refactor, generación de tests, o migración.

/pm2

Sintaxis: /pm2 o /pm2 status o /pm2 restart {service} o /pm2 logs {service}

Description: Manage Node.js services with PM2. Start, stop, restart, and monitor processes.

Integración con PM2:

Este comando es un wrapper inteligente de PM2 que:

  1. Lee el ecosystem.config.js del proyecto
  2. Entiende la arquitectura de servicios
  3. Puede realizar operaciones como restart con zero-downtime (/pm2 reload --update-env)
  4. Analiza los logs para detectar errores

/aside

Sintaxis: /aside "nota o contexto"

Description: Record a note or context without triggering any action. Useful for capturing thoughts mid-session.

Uso: Cuando quieres que Claude recuerde algo sin que ejecute ninguna acción. Por ejemplo:

/aside "El cliente requiere que la autenticación use OAuth2, no JWT directo"
/aside "Hay un bug conocido en la versión 2.3.1 de stripe-js con Safari"

Estas notas se incorporan al contexto de la sesión y pueden ser referenciadas más tarde.

14. Comandos Avanzados

/promote

Sintaxis: /promote o /promote staging o /promote production

Description: Promote changes to next environment stage. Run environment-specific verifications before promoting.

Flujo de promoción:

flowchart LR
    D[development] --> S[staging]
    S --> P[production]

    D --> V1[/verify pre-pr/]
    V1 --> S
    S --> V2[/verify pre-pr/ + smoke tests]
    V2 --> P

Antes de cada promoción, ejecuta las verificaciones apropiadas para ese entorno.

/prune

Sintaxis: /prune o /prune dependencies o /prune dead-code o /prune stale-branches

Description: Clean up: dead code, unused dependencies, stale git branches, old checkpoints.

Modos:

ModoQué limpia
dependenciesDependencias en package.json no usadas en el código
dead-codeCódigo declarado pero nunca referenciado
stale-branchesBranches de git merged hace más de 30 días
checkpointsCheckpoints de más de 90 días
(sin argumento)Ejecuta todos los modos

/instinct-status (Referencia adicional)

Ver sección 6 para detalle completo.

15. Crear Comandos Propios

Template completo

---
description: Descripción concisa que aparece en el autocompletado (máx 80 chars)
allowedTools:
  - Read
  - Bash
  - Glob
  - Grep
---

# Nombre del Comando

Eres un agente especializado en [dominio específico].

## Contexto

Estás trabajando en un proyecto con las siguientes características:
- [Tecnología principal]
- [Convenciones del proyecto]

## Tarea

[Si se proporcionan argumentos]: $ARGUMENTS
[Si no hay argumentos]: Ejecuta el comportamiento por defecto.

## Instrucciones

1. Primero, analiza [X] para entender el contexto
2. Luego, [acción específica]
3. Finalmente, [resultado esperado]

## Formato de Output

Presenta el resultado en este formato:

NOMBRE DEL REPORTE

[estructura del output]


## Restricciones

- NO modifiques [archivos específicos que no debe tocar]
- SIEMPRE [restricción importante]
- Si encuentras [condición de error], detente y pide confirmación

Cómo usar $ARGUMENTS en comandos propios

Argumento requerido:

---
description: Deploy to specific environment
---

Despliega al entorno: $ARGUMENTS

Válida que $ARGUMENTS sea uno de: staging, production, qa
Si no es válido, reporta el error y detente.

Argumento opcional con default:

---
description: Generate API documentation
---

Genera documentación para: $ARGUMENTS

Si $ARGUMENTS está vacío, genera documentación para todo el directorio src/api/

Múltiples argumentos parseados del texto:

---
description: Add feature with optional ticket reference
---

Tarea: $ARGUMENTS

Extrae del texto:
- El nombre de la feature (requerido)
- El número de ticket si se menciona (opcional, formato: TICKET-123)

Commands vs Skills vs Agents — Cuándo crear cada uno

Crea un Command cuando:

Crea un Skill cuando:

Crea un Agent cuando:

16. Workflows Completos con Comandos Encadenados

Workflow 1: Feature Nueva Completa

# Paso 1: Planificar — no tocar código hasta confirmar
/plan "add user profile editing with avatar upload"

# Después de revisar el plan y escribir "yes":

# Paso 2: Implementar con TDD
/tdd "UserProfileService.updateProfile"
/tdd "AvatarUploadService.uploadAvatar"

# Paso 3: Verificar que todo compila y los tests pasan
/verify quick

# Paso 4: Review de calidad
/code-review

# Paso 5: Generar tests E2E para el flujo
/e2e "user edits profile and uploads avatar"

# Paso 6: Verificación completa antes de PR
/verify pre-pr

# Paso 7: Actualizar documentación
/update-docs

# Paso 8: Aprender de la sesión
/learn

Tiempo estimado de overhead de comandos: ~5 minutos adicionales sobre la implementación pura. Beneficio: Feature bien testeada, documentada, y sin issues de calidad.

Workflow 2: Bug Fix con TDD

# Paso 1: Entender el bug — crear un test que reproduce el fallo
/tdd "PaymentService.processPayment should not double-charge on retry"

# El agente escribe el test que reproduce el bug (falla → RED)
# Luego implementa el fix (pasa → GREEN)
# Luego refactoriza (REFACTOR)

# Paso 2: Verificar que el fix no rompió nada
/verify quick

# Paso 3: Si hay dudas de seguridad
/code-review "src/services/PaymentService.ts"

# Paso 4: Verificación completa
/verify pre-pr

# Paso 5: Guardar aprendizaje sobre el patrón del bug
/learn-eval

Workflow 3: Refactor y Limpieza

# Paso 1: Checkpoint del estado actual (antes de refactor)
/checkpoint "before-auth-refactor"

# Paso 2: Limpiar código muerto
/refactor-clean "src/auth/"

# Paso 3: Verificar que nada se rompió
/verify

# Paso 4: Si algo falló, el checkpoint nos ayuda a diagnosticar
# /sessions show para ver el estado anterior

# Paso 5: Calidad del código refactorizado
/quality-gate "src/auth/"

# Paso 6: Actualizar codemaps (la estructura cambió)
/update-codemaps

Workflow 4: Auditoría de Seguridad

# Paso 1: Code review con foco en seguridad
/code-review

# Paso 2: Verificación completa con secrets scan
/verify full

# Paso 3: Evaluar contra criterios de seguridad
/eval "no SQL injection, no hardcoded secrets, all inputs validated, no XSS"

# Paso 4: Si hay issues, usar build-fix para los errores de TypeScript
/build-fix

# Paso 5: Distillar las reglas de seguridad aprendidas
/rules-distill

Workflow 5: Release Preparation

# Paso 1: Verificación completa del estado actual
/verify pre-pr

# Paso 2: Quality gate con criterios estrictos
/quality-gate strict

# Paso 3: Cobertura de tests
/test-coverage

# Paso 4: Análisis de contexto y budget
/context-budget --analyze

# Paso 5: Actualizar toda la documentación
/update-docs
/update-codemaps

# Paso 6: Checkpoint del release
/checkpoint "release-v2.4.0"

# Paso 7: Promover a staging
/promote staging

# Paso 8: Después de validar en staging, promover a producción
/promote production

17. Diferencia Commands vs Skills vs Agents

flowchart TD
    Q[¿Qué necesito?] --> A{¿Invocación manual\ndesde el chat?}
    A -->|Sí| B{¿Flujo simple\ncon args opcionales?}
    A -->|No, es sub-proceso| C{¿Reutilizable en\nmúltiples contextos?}

    B -->|Sí| D[Command\n/mi-comando]
    B -->|No, muy complejo| E{¿Necesita estado\npersistente?}

    C -->|Sí| F[Skill\n.claude/skills/]
    C -->|No, específico| G[Inline en otro Command]

    E -->|Sí| H[Agent\n.claude/agents/]
    E -->|No| I[Command con\nprompt detallado]

Tabla comparativa

CaracterísticaCommandSkillAgent
Invocación/nombre en chatInterno, por otrosInterno, por otros
Estado persistenteNoNoSí (puede)
ArgumentosTexto libre ($ARGUMENTS)EstructuradoEstructurado
ComplejidadBaja-mediaMedia-altaAlta
ReutilizaciónPor el usuarioPor el sistemaPor el sistema
Ubicación.claude/commands/.claude/skills/.claude/agents/

18. Comandos y Token Cost

El uso de slash commands tiene un costo de tokens asociado. Entender este costo ayuda a elegir el comando correcto para cada situación.

Costo relativo por comando

CategoríaComandosCosto tokens
Lectura/análisis/code-review, /verify quick, /instinct-statusBajo
Planificación/plan, /multi-planMedio
Implementación/tdd, /build-fix, /e2eMedio-Alto
Multi-agente/orchestrate, /multi-executeAlto
Loops autónomos/loop-start con muchas iteracionesMuy Alto

Estrategias para optimizar el costo

  1. Usa /verify quick durante desarrollo, full solo antes de commit
  2. Usa /claw para operaciones repetitivas donde el token cost importa
  3. Usa /context-budget para identificar qué está consumiendo tokens innecesariamente
  4. Usa /model-route para asegurarte de usar el modelo correcto (Haiku para tareas simples)
  5. Mantén los codemaps actualizados para que Claude no necesite leer archivos enteros

19. Comandos en Plugin vs Manual Install

Namespacing

Cuando instalas ECC como plugin de Claude Code, los comandos tienen un namespace:

# Forma completa (siempre funciona)
/everything-claude-code:plan "add auth"
/everything-claude-code:tdd
/everything-claude-code:verify

# Forma corta (funciona si no hay conflicto)
/plan "add auth"
/tdd
/verify

Cuando instalas manualmente (copiando archivos a .claude/commands/), los comandos son directamente accesibles sin namespace.

Resolución de conflictos

Si tienes un comando local y uno de ECC con el mismo nombre, el local tiene prioridad. Esto es intencional: te permite sobrescribir el comportamiento de ECC para tu proyecto específico.

.claude/commands/plan.md      ← Local: tiene prioridad
~/.claude/commands/plan.md    ← Global (ECC): se usa si no hay local

Listar comandos disponibles

# Ver todos los comandos disponibles (incluye ECC)
# En Claude Code, escribe / y verás el autocompletado

# O ver los archivos directamente
ls ~/.claude/commands/
ls .claude/commands/

20. Mejores Prácticas

  1. Empieza siempre con /plan antes de implementar features no triviales. Los tokens invertidos en planificación ahorran mucho más en correcciones.

  2. Usa /verify antes de cada commit, no solo antes del PR. Detecta problemas temprano cuando son más baratos de resolver.

  3. Encadena comandos en el orden correcto: plan → tdd → code-review → verify. Cambiar el orden reduce la efectividad.

  4. Usa /checkpoint antes de refactors grandes. No es un sustituto de git, sino un complemento que guarda contexto que git no captura.

  5. Ejecuta /learn al final de sesiones productivas, no al final de sesiones donde las cosas no salieron bien — los patrones de error también se pueden aprender, pero requiere más cuidado.

  6. Usa /quality-gate con thresholds específicos de tu proyecto en lugar de los defaults. Un threshold de 80% de cobertura puede ser adecuado para algunos proyectos pero insuficiente para otros.

  7. Usa comandos language-specific (/go-review, /rust-review) en lugar de /code-review genérico cuando trabajas en lenguajes específicos — tienen conocimiento más profundo del lenguaje.

  8. Mantén /update-codemaps ejecutado frecuentemente en proyectos que cambian rápido. Claude trabaja mejor cuando tiene una vista actualizada del proyecto.

  9. Usa /model-route --analyze antes de tareas costosas para asegurarte de que estás usando el modelo apropiado.

  10. Configura /harness-audit antes de habilitar loops autónomos (/loop-start). Los loops sin configuración adecuada pueden gastar tokens innecesariamente.

  11. Crea comandos propios para workflows repetitivos de tu proyecto. Cualquier secuencia de pasos que ejecutes más de 3 veces merece un command.

  12. Usa /aside para capturar decisiones de arquitectura durante la sesión en lugar de agregarlas manualmente a la documentación.

  13. Ejecuta /rules-distill periódicamente (cada semana o dos) para que las convenciones del proyecto se reflejen en el comportamiento de Claude.

  14. Usa /prompt-optimize en prompts que ejecutas frecuentemente. Una optimización del 50% en tokens se multiplica por cada uso.

  15. Configura /setup-pm al inicio de cada proyecto nuevo. Muchos comandos dependen de saber el package manager correcto.

21. Anti-patrones

1. Usar /orchestrate para tareas simples

Mal:

/orchestrate "fix the typo in line 42 of README"

Bien: simplemente editar el archivo directamente o pedirle a Claude que lo haga.

2. Ejecutar /verify full en cada guardado

/verify full ejecuta el test suite completo. Úsalo con deliberación, no como reemplazo del formateo automático al guardar.

3. Ignorar el WAIT de /plan

/plan "add auth"
# Plan presentado...
"ok, empieza a implementar sin esperar mi confirmación"

El WAIT de /plan existe por una razón: revisar el plan antes de que empiece la implementación ahorra tokens y evita trabajo innecesario.

4. Usar /tdd sin entender el código a testear

TDD funciona mejor cuando tienes claro el comportamiento esperado. Si no tienes claro qué debe hacer el código, primero usa /plan.

5. Crear un Command cuando necesitas un Skill

Si la operación necesita ser invocada por otros agentes o tiene lógica compleja, es un Skill, no un Command.

6. No actualizar codemaps después de refactors grandes

Claude puede confundirse sobre la estructura del proyecto si los codemaps están desactualizados. Ejecuta /update-codemaps después de cualquier refactor significativo.

7. Usar /multi-execute para tareas secuenciales sin dependencias

Si las tareas son puramente secuenciales (B siempre después de A, sin paralelismo posible), /orchestrate o simplemente ejecutarlas en orden es más eficiente.

8. Ignorar los WARNINGs de /verify

Los warnings no bloquean el PR, pero se acumulan. Un proyecto con 50 warnings activos es difícil de mantener.

9. Ejecutar /loop-start sin condiciones de parada claras

Un loop sin condición de parada clara puede iterar indefinidamente. Siempre especifica cuándo debe detenerse.

10. Usar /code-review como sustituto de /verify

/code-review analiza calidad del código; /verify verifica que funciona. Son complementarios, no intercambiables.

22. Ejercicios Prácticos

Ejercicio 1: Workflow básico de feature

Objetivo: Practicar el ciclo completo plan → tdd → verify

Tarea: Implementa una función calculateDiscount(price, discountCode) que aplica descuentos basados en códigos.

# Paso 1: Planifica
/plan "implement calculateDiscount function that applies percentage discounts based on codes: SAVE10=10%, SAVE20=20%, HALFPRICE=50%"

# Paso 2: Implementa con TDD
/tdd

# Paso 3: Verifica
/verify

Criterio de éxito: Coverage >= 80%, todos los tests pasan, /verify green.

Ejercicio 2: Debugging con build-fix

Objetivo: Usar /build-fix para resolver errores de TypeScript

Setup: Introduce intencionalmente un error de tipo en un archivo TypeScript y ejecuta /build-fix.

Observa: Cómo el agente identifica la causa raíz vs. los síntomas.

Ejercicio 3: Aprender del código existente

Objetivo: Practicar el ciclo learn → instinct-status → evolve

# Después de una sesión de trabajo:
/learn

# Revisa lo que aprendió:
/instinct-status

# Si hay instincts de alta confianza, evolucionarlos:
/evolve

Ejercicio 4: Crear tu primer Command

Objetivo: Crear un slash command personalizado para tu proyecto

Tarea: Crea un command /mi-proyecto:setup que:

  1. Instale dependencias
  2. Configure las variables de entorno desde .env.example
  3. Ejecute las migraciones de DB
  4. Verifique que todo esté correcto

Ubicación: .claude/commands/setup.md

Ejercicio 5: Multi-agente básico

Objetivo: Usar /orchestrate para una tarea que span múltiples dominios

Tarea:

/orchestrate "add a new 'notifications' feature: backend endpoint, frontend component, and database table"

Observa: Cómo el orchestrator divide el trabajo, qué agentes lanza, cómo sintetiza los resultados.

23. Referencia Rápida — Todos los Comandos

ComandoDescripción
/asideRegistra nota o contexto sin ejecutar acción
/build-fixAnaliza y corrige errores de build automáticamente
/checkpointGuarda estado de verificación como punto de restauración
/clawEjecuta tarea con NanoClaw (optimización de tokens)
/code-reviewReview de calidad: seguridad, performance, mantenibilidad
/context-budgetAnaliza y optimiza el uso del context window
/cpp-buildCorrige errores de build en proyectos C++
/cpp-reviewReview de código C++: RAII, memory, UB
/cpp-testGenera tests C++ con Google Test / Catch2
/devfleetGestiona fleet de agentes en paralelo
/docsBusca y presenta documentación relevante
/e2eGenera tests E2E con Playwright (Page Object Model)
/evalEvalúa estado actual contra criterios de éxito
/evolvePromueve instincts de alta confianza a skills
/go-buildCorrige errores de build en proyectos Go
/go-reviewReview idiomático de código Go
/go-testTDD workflow para Go con table-driven tests
/gradle-buildCorrige errores de build Gradle/Java
/harness-auditAudita configuración del harness de ECC
/instinct-exportExporta instincts a archivo JSON compartible
/instinct-importImporta instincts desde archivo JSON o perfil
/instinct-statusMuestra instincts con scores de confianza
/kotlin-buildCorrige errores de build Kotlin/Gradle
/kotlin-reviewReview de código Kotlin: nullability, coroutines
/kotlin-testGenera tests Kotlin con JUnit5/Kotest
/learnExtrae patrones de la sesión y guarda como instincts
/learn-evalExtrae y evalúa calidad antes de guardar instincts
/loop-startInicia loop de ejecución autónomo con condiciones de parada
/loop-statusMuestra estado actual del loop en ejecución
/model-routeRutea tarea al modelo óptimo según complejidad y costo
/multi-backendOrquesta cambios en múltiples servicios backend
/multi-executeEjecuta plan multi-fase con agentes especializados
/multi-frontendOrquesta cambios en múltiples apps frontend
/multi-planPlanificación colaborativa con múltiples modelos
/multi-workflowWorkflow general multi-agente
/orchestrateCoordina múltiples agentes especializados en paralelo
/planCrea plan de implementación, espera confirmación antes de codear
/pm2Gestiona servicios Node.js con PM2
/projectsGestiona y cambia entre múltiples proyectos
/promotePromueve cambios al siguiente stage (staging/production)
/prompt-optimizeOptimiza prompts para reducir tokens y mejorar claridad
/pruneLimpia código muerto, dependencias sin uso, branches viejos
/python-reviewReview de código Python: PEP8, type hints, seguridad
/quality-gateChecks de calidad con thresholds configurables
/refactor-cleanElimina código muerto, imports sin uso, duplicados
/resume-sessionContinúa sesión guardada anteriormente
/rules-distillDestila patrones del codebase en reglas para CLAUDE.md
/rust-buildCorrige errores de borrow checker y Cargo en Rust
/rust-reviewReview de código Rust: ownership, lifetimes, unsafe
/rust-testGenera tests Rust: unit, integration, property tests
/save-sessionGuarda estado de sesión actual para reanudar después
/sessionsLista, inspecciona y restaura sesiones anteriores
/setup-pmDetecta y configura el package manager del proyecto
/skill-createAnaliza git history y genera skills reutilizables
/skill-healthVerifica que los skills instalados sean válidos
/tddWorkflow TDD: RED→GREEN→REFACTOR con 80%+ coverage
/test-coverageAnaliza cobertura y genera tests faltantes
/update-codemapsRegenera mapas de arquitectura y dependencias del proyecto
/update-docsActualiza documentación para reflejar el estado actual
/verifySuite completa: build, types, lint, tests, secrets, logs

24. Checklist y Resumen

Checklist de Comandos Esenciales

Antes de empezar a usar ECC en un proyecto nuevo:

Para cada feature nueva:

Mantenimiento periódico:

Resumen de Conceptos Clave

Los slash commands de ECC son la interfaz de alto nivel para invocar agentes especializados. Cada comando es un archivo Markdown en .claude/commands/ con frontmatter YAML que define el comportamiento del agente.

El mecanismo central es $ARGUMENTS — el texto después del nombre del comando que se interpola en el prompt del agente antes de enviarlo.

Los comandos se organizan en categorías según su función:

La clave para usar ECC efectivamente es entender cuándo usar qué comando y en qué orden encadenarlos. El workflow canónico — plan → tdd → code-review → verify — no es arbitrario: cada comando construye sobre el resultado del anterior y el costo de encontrar problemas decrece en cada paso.

← Volver al listado de tecnologías ← Índice de Everything Claude Code