Arquitectura Command → Agent → Skill

Arquitectura de tres capas Command → Agent → Skill

User input / command trigger
       │
       ▼
┌──────────────┐    Command (entry point) 
│  /command    │    .claude/commands/*.md
└──────┬───────┘
       │ Agent tool
       ▼
┌──────────────┐    Agent (executor) 
│  Agent       │    .claude/agents/*.md
└──────┬───────┘
       │ Preload/invoke Skill
       ▼
┌──────────────┐    Skill (knowledge) 
│  Skill       │    .claude/skills/*/SKILL.md
└──────────────┘

• Command — Punto de entrada del usuario. Orquesta el orden de llamada a los Agents. 82 integrados personalizados

• Agent — Ejecutor de contexto independiente. Puede ejecutarse en paralelo. 5 integrados personalizados

• Skill — Paquete de instrucciones reutilizable. Se carga o se invoca. 10 integrados personalizados

Comparación

Guía de decisión: ¿Necesitas orquestar flujos de múltiples pasos encadenando múltiples Agentes → Comando. ¿Necesitas contexto independiente, ejecución paralela, aislamiento de herramientas → Agente. ¿Necesitas paquetes de instrucciones reutilizables cargadas en múltiples escenarios → Habilidad.

Relaciones y casos de uso

Por qué importa el Harness

Fórmula de calidad de salida: quality = f(effective_context, model_capability, iteration_loops) El Harness impacta directamente el “contexto efectivo” y los “ciclos de iteración”.

Harness: 10 capacidades principales

“¿Habilidades, Comandos, Subagentes todos se convierten en prompts al final, entonces, ¿bastan los prompts fuertes?” — Técnicamente cierto, prácticamente falso. Aquí está lo que hace el Harness en capas que los prompts no pueden alcanzar:

User input: "Write a recursive flatten function"     ← (a) ~6 tokens

What the model actually sees:                       ← (b) ~15,000 tokens
  ├── CLAUDE.md (Project specs)
  ├── Matched .claude/rules/*.md (paths trigger)
  ├── Modular system prompt fragments (110+)
  ├── Tool definitions
  ├── Environment context (cwd, git status, platform)
  ├── Previous conversation turns
  ├── Files read via Read/Grep
  └── User's 6-token request

Subagentes

5 Tipos Integrados

Frontmatter de Agente Personalizado (16 Campos)

Sistema de Comandos (82 Integrados)

Claude Code tiene 82 comandos de barra integrados, organizados en 11 categorías. Los comandos personalizados se colocan en .claude/commands/*.md.

Comandos personalizados: Colóquelos en .claude/commands/*.md, soporta 16 campos de frontmatter (name, description, argument-hint, arguments, context, etc.). Use “!`command``` para inyección dinámica de contexto.

Patrones de Orquestación

Animación del flujo completo de orquestación del Weather Reporter

User: /weather-orchestrator
       │
       ▼
┌──────────────────────────┐
│  weather-orchestrator    │  ← Command (entry point) 
│  1. Ask temperature unit C/F   │
│  2. Call weather-agent   │
│  3. Call svg-creator     │
└──────┬───────────────────┘
       ▼
┌──────────────────────────┐
│  weather-agent           │  ← Agent
│  preload: weather-fetcher │  ← Skill (preloaded) 
└──────┬───────────────────┘
       ▼
┌──────────────────────────┐
│  weather-svg-creator     │  ← Skill (invoked) 
│  output: weather.svg         │
└──────────────────────────┘

Sistema de Tareas

El sistema de seguimiento de tareas integrado de Claude Code admite creación, consultas, actualizaciones y gestión de dependencias. Funciona con Subagentes y Skills.

4 Herramientas Principales

Ciclo de Vida de la Tarea

pending → in_progress → completed
                 ↘ deleted

Dependencias

• addBlocks — Marca “la tarea especificada no puede comenzar hasta que esta tarea se complete”
• addBlockedBy — Marca “esta tarea debe esperar a que la tarea especificada se complete antes de comenzar”
• Forma un DAG (Grafo Dirigido Acíclico), asegurando el orden de ejecución

Variable de Entorno: CLAUDE_CODE_TASK_LIST_ID identifica la lista de tareas actual, el archivo se persiste en ~/.claude/tasks/.

Sistema de Skills

Aspecto clave: Una Skill es una carpeta (no solo un archivo Markdown). Puede contener scripts, datos, recursos, plantillas de configuración — cualquier cosa que un Agente pueda descubrir, leer y manipular. SKILL.md es el punto de entrada, pero no el panorama completo. Consulta Orquestación para ver un ejemplo real.

Las Skills se encuentran en .claude/skills/<name>/SKILL.md con autodescubrimiento y activación. Al inicio de la sesión, Claude escanea todos los campos description de las skills disponibles para coincidir con la tarea actual.

• Carga Progresiva de Información — Dile a Claude qué archivos están en la carpeta a través de SKILL.md; lee los detalles solo cuando sea necesario. Evita cargar toda la información a la vez y desperdiciar contexto.

• La Descripción es para el Modelo — El campo description no es un resumen — es una descripción de la condición de activación. Escribe claramente “cuándo debe usarse esta skill”, y Claude coincidirá automáticamente.

9 Patrones de Configuración

2 Modos de Carga

• Modo Preload (Skills de Agente) — Cargadas a través del campo skills: del Agente. Se inyectan automáticamente al inicio del Agente.

• Modo Invoke (Skills Invocadas) — Activadas a través de la herramienta Skill o /skill-name. Claude también puede coincidir e invocar automáticamente.

9 Categorías de Uso

Extraídas de cientos de skills internas de Anthropic (Thariq, 2026.03). Una buena skill pertenece a una categoría; las skills que abarcan múltiples generalmente necesitan dividirse.

16 Campos de Frontmatter

10 Skills Integradas

Sistema de Hooks

Scripts de automatización basados en eventos del ciclo de vida. Configurados en .claude/settings.json o en el frontmatter del Agente.

4 Tipos de Hook

Limitación del frontmatter del Agente: Solo 6 eventos de Hook están disponibles en los Agentes: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, Stop, SubagentStop. Los otros 21 eventos solo están disponibles en la sesión principal.

27 Eventos del Ciclo de Vida

Agrupados por función. Todos los eventos soportan las opciones async y timeout.

Ejemplos de Configuración

Los Hooks se configuran en Configuración, o mediante frontmatter de Skill para activación según necesidad.

{
  "hooks": {
    "Stop": [{
      "type": "command",
      "command": "python3 .claude/hooks/scripts/hooks.py --event Stop"
    }],
    "PostToolUse": [{
      "type": "command",
      "command": "python3 .claude/hooks/scripts/hooks.py --event PostToolUse"
    }]
  }
}

Uso Avanzado de Herramientas

Prompt-to-Code (PTC) — Cambio de Paradigma

En lugar de introducir instrucciones en el prompt del sistema, PTC las compila en reglas de código ejecutable que se ejecutan en un sandbox. Resultado: prompts más cortos, razonamiento más preciso, ~37% de ahorro de tokens.

{
  "type": "code_execution_20250825",
  "name": "data_processor",
  "allowed_callers": ["code_execution_20250825"],
  "input_schema": {
    "type": "object",
    "properties": {
      "task": { "type": "string" }
    }
  }
}

Patrones Avanzados de PTC

• Procesamiento por Lotes — Itera sobre múltiples registros en una sola llamada PTC, reduciendo las invocaciones de herramientas. Ideal para traducción por lotes, clasificación, etc.

• Terminación Temprana — Agrega verificaciones condicionales en el código para return inmediatamente cuando se cumple el umbral. Evita computación innecesaria.

• Ramificación Condicional — Selecciona dinámicamente diferentes ramas de procesamiento según el tipo de entrada, en lugar de definir herramientas separadas para cada una.

Restricciones de PTC

Filtrado Dinámico de Herramientas

Los resultados de Web Search / Web Fetch son preprocesados por código antes de entrar al contexto, en lugar de inyectarse en crudo. Requiere el header beta anthropic-beta: code-execution-web-tools-2026-02-09.

Búsqueda de Herramientas

Marca las herramientas poco utilizadas con defer_loading: true; el modelo las busca y carga bajo demanda, reduciendo las definiciones de herramientas en ~85%.

// Tool definitionsExample
{
  "name": "specialized_analyzer",
  "defer_loading": true,
  "description": "..."
}

// Claude Code environment variable
ENABLE_TOOL_SEARCH=auto:5  // Keep 5 common tools, defer the rest

Ejemplos de Uso de Herramientas

Agrega un array input_examples (1-5 elementos) a las definiciones de herramientas con muestras de datos reales. La precisión de las llamadas del modelo salta del 72% al 90%.

{
  "name": "query_database",
  "input_examples": [
    { "sql": "SELECT * FROM users WHERE active = true LIMIT 10" },
    { "sql": "SELECT COUNT(*) FROM orders WHERE date > '2026-01-01'" }
  ]
}

Disponibilidad en Claude Code

Prioridad para usuarios de CLI: Configura primero Ejemplos de Uso de Herramientas y Búsqueda de Herramientas en CLAUDE.md (ENABLE_TOOL_SEARCH=auto:5). Estos proporcionan el mayor beneficio para usuarios de CLI. PTC y Filtrado Dinámico son principalmente para escenarios de integración profunda con SDK/API.

Prioridad de Configuración de 5 Niveles

Métodos de Entrega de Configuración Gestionada

Configuración Central

Las reglas de denegación siempre tienen la máxima prioridad — una denegación en cualquier nivel sobrescribe todas las reglas de permiso. Las configuraciones de tipo array se fusionan y se deduplican entre niveles, no se reemplazan.

Prioridad Interna de la Capa Gestionada

Dentro de la capa gestionada, las fuentes se utilizan en este orden (solo una fuente, sin fusión entre capas):

Cambio en v2.1.126: /config ahora persiste los cambios en ~/.claude/settings.json en lugar de mantenerlos solo en memoria. Las ediciones mediante la interfaz interactiva de Configuración sobreviven a los reinicios.

Modos de Permisos

Configurar a través de la clave permissions en Configuración.

Sintaxis de Permisos de Herramientas

Prefijos de Ruta

Reglas de Coincidencia

• Comandos compuestos: Se dividen por &&, ||, ;, |, cada subcomando coincide de forma independiente. Bash(safe-cmd *) no cubre safe-cmd && other-cmd
• Posición del comodín: * puede aparecer como prefijo, sufijo o infijo. Bash(* install) coincide con npm install; Bash(git * main) coincide con git push main
• Límite de palabra: Bash(ls *) (con espacio) no coincide con lsof; Bash(ls*) (sin espacio) coincide con ambos
• Enlaces simbólicos: allow requiere que tanto el enlace simbólico como el destino estén ambos en directorios permitidos; deny se activa con cualquiera de los dos
• Envoltorios de procesos: timeout, time, nice, nohup se eliminan antes de la coincidencia. watch, find -exec siempre muestran prompt

Configuración Global vs de Proyecto

• Global ~/.claude/ — settings.json Configuración global CLAUDE.md Todas las instrucciones del proyecto Ideal para: preferencias personales, configuración general, alias de shell

• Proyecto .claude/ — settings.json Compartido por el equipo (commit) settings.local.json Sobrescritura personal (git-ignored) CLAUDE.md Instrucciones del proyecto agents/ Definiciones de SubAgent skills/ Definiciones de habilidades commands/ Comandos personalizados

6 Dimensiones de Configuración

Estructura de Directorios

~/.claude/                          .claude/
├── settings.json      ← Global settings    ├── settings.json      ← Team shared
├── settings.local.json               ├── settings.local.json ← Personal override
├── CLAUDE.md          ← Global instructions    ├── CLAUDE.md          ← Project instructions
├── mcp.json           ← Global MCP    ├── agents/            ← Subagent definitions
├── agents/            ← Global agents    │   ├── reviewer.md
│   ├── explorer.md                   │   └── coder.md
│   └── researcher.md                 ├── skills/            ← Skill definitions
├── skills/            ← Global skills    │   ├── lint-check/
│   └── deploy-check/                 │   │   └── SKILL.md
├── commands/          ← Global commands    │   └── test-runner/
│   └── review.md                     │       └── SKILL.md
├── plans/             ← Plan files    ├── commands/          ← Custom commands
├── tasks/             ← Task persistence  │   └── commit.md
├── memory/            ← Auto memory    ├── rules/             ← Conditional rules
└── plugins/           ← Plugin installs    │   ├── tests.md
                                      │   └── security.md
                                      └── mcp.json           ← Project MCP

6 Principios de Diseño

Características Solo Globales

• allowedPlugins / deniedPlugins — Lista de permitidos/bloqueados de plugins
• managedSettings — Configuración a nivel de organización implementada por TI
• autoUpdatesChannel — Control del canal de actualizaciones
• cleanupPeriodDays — Limpieza automática de sesiones
• pluginRegistry — Fuente de plugins personalizada
• plansDirectory — Directorio global de archivos de planes
• autoMemoryEnabled — Activación del sistema de memoria

Especificación de CLAUDE.md

CLAUDE.md es la configuración de mayor impacto en Claude Code. Un CLAUDE.md bien estructurado mejora la calidad del resultado más que cualquier ajuste de Configuración.

4 Ubicaciones de almacenamiento

Carga condicional de .claude/rules/

• Con frontmatter paths: — Carga diferida solo cuando se opera en las rutas coincidentes. Ideal para reglas específicas del framework, por ejemplo, paths: ["src/**/*.test.ts"] se carga solo al editar archivos de prueba.

• Sin frontmatter — Cargado en cada sesión, equivalente a CLAUDE.md. Mejor para reglas de todo el proyecto.

Directrices de escritura

• Mantener por debajo de 200 líneas: el cumplimiento disminuye más allá de este límite
• Escribir el POR QUÉ y no el QUÉ: el código ya explica el QUÉ; documentar restricciones ocultas, invariantes sutiles, soluciones alternativas para errores específicos
• Las instrucciones negativas son más efectivas: “no usar el patrón X” es más claro que “usar el patrón Y”
• No declarar lo obvio que el código ya expresa: el valor de CLAUDE.md es sacar a Claude de su pensamiento predeterminado
• No guardar patrones de código, instantáneas de arquitectura o historial de git: estos se pueden derivar del código
• Incluir restricciones específicas del proyecto: dependencias de orden de compilación, versiones de bibliotecas incompatibles conocidas, procesos de despliegue especiales

claudeMdExcludes

Usa la configuración claudeMdExcludes para omitir archivos CLAUDE.md no deseados:

{
  "claudeMdExcludes": [
    "**/vendor/**/CLAUDE.md",
    "**/node_modules/**/CLAUDE.md"
  ]
}

La exclusión se aplica solo a la memoria de usuario, proyecto y local; los archivos de políticas gestionadas no pueden ser excluidos.

Mecanismo de carga en monorepositorios

Mecanismo de carga de CLAUDE.md en monorepositorios (original de Boris Cherny)

• Carga de ancestros — Al inicio, recorre hacia arriba y carga inmediatamente todos los archivos CLAUDE.md. Inmediato

• Carga de descendientes — Los archivos CLAUDE.md de los subdirectorios se cargan solo cuando se opera en ese directorio. Diferido

Comparación de escenarios

Asumamos la estructura de monorepositorio: frontend/CLAUDE.md, backend/CLAUDE.md, api/CLAUDE.md, raíz CLAUDE.md.

Escenario 1: Iniciar desde la raíz cd /mymonorepo && claude

Escenario 2: Iniciar desde el directorio del componente cd /mymonorepo/frontend && claude

Mejor práctica: Convenciones compartidas en la raíz CLAUDE.md, instrucciones específicas del componente en el CLAUDE.md del componente. Preferencias personales en CLAUDE.local.md (git-ignored).

Memoria Automática

El sistema de memoria automática de Claude Code persiste información entre sesiones. Los archivos de memoria se almacenan en el directorio .claude/ del proyecto o en el directorio global ~/.claude/, organizados en formato YAML frontmatter + Markdown.

4 Tipos de Memoria

Estructura del Archivo de Memoria

Cada memoria es un archivo Markdown independiente que usa YAML frontmatter:

---
name: feedback-testing
description: Testing preferences and corrections
metadata:
  type: feedback
---

Integration tests must use a real database, not mocks.
**Why:** Last quarter a migration failed due to mock/production environment divergence. 

[[testing-patterns]]  ← link to related memory

Índice MEMORY.md

Todas las memorias se gestionan a través del archivo índice MEMORY.md, mantenido por debajo de 200 líneas. Formato de índice por línea:

- [Title](filename.md) — one-line summary

Qué NO Guardar

• Patrones de código, arquitectura, rutas de archivo — derivables del código
• Historial de Git, cambios recientes — git log es la fuente autoritativa
• Soluciones de depuración — la corrección está en el código, el contexto en el mensaje del commit
• Contenido ya cubierto en CLAUDE.md
• Detalles de tareas efímeras — use Tarea o Plan en su lugar

Configuración

Memoria del Agente 3 Ámbitos

Con Subagentes, la Memoria puede persistir conocimiento entre agentes.

Mantenga el archivo índice MEMORY.md por debajo de 200 líneas.

Servicios MCP

Servicios MCP Comunes

Claves de Configuración de MCP

Ejemplo de Configuración

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-context7"]
    },
    "always-on-server": {
      "type": "http",
      "url": "https://mcp.example.com",
      "alwaysLoad": true
    }
  }
}

Características Clave

• alwaysLoad (v2.1.121) — Establezca "alwaysLoad": true en la configuración del servidor para cargar todas las herramientas inmediatamente en lugar de una detección diferida. Solo para conjuntos pequeños de herramientas necesarias en cada turno.

• Recarga en Caliente (v2.1.139) — /mcp Reconectar relee .mcp.json sin reiniciar la sesión. También inyecta CLAUDE_PROJECT_DIR en el entorno del servidor stdio.

Expansión de Variables de Entorno

Use la sintaxis ${ENV_VAR} en .mcp.json para hacer referencia a variables de entorno, evitando secretos codificados:

{
  "mcpServers": {
    "my-api": {
      "url": "https://mcp.example.com/mcp?token=${MCP_API_TOKEN}"
    }
  }
}

workspace es un nombre de servidor MCP reservado (v2.1.128). Los servidores definidos por el usuario con este nombre se omitirán con una advertencia.

Los servidores compatibles con OAuth completan la autenticación automáticamente (siguiendo RFC 9728), sin necesidad de configuración manual de apiKeyHelper.

Flujo de Trabajo RPI

Investigación → Planificación → Implementación, cada fase tiene una puerta de validación. Orquesta múltiples roles de agentes a través de Subagentes.

Step 1: RESEARCH   → RESEARCH.md (GO / NO-GO) 
Step 2: PLAN       → PLAN.md + pm.md + ux.md + eng.md
Step 3: IMPLEMENT  → IMPLEMENT.md (phased, each phase has test gates) 

8 Roles de Agente

3 Comandos

rpi/{feature-slug}/
├── REQUEST.md              # Feature description
├── research/RESEARCH.md    # GO/NO-GO analysis
├── plan/
│   ├── PLAN.md             # Implementation roadmap (3-5 phases) 
│   ├── pm.md               # Product requirements document
│   ├── ux.md               # UX design draft
│   └── eng.md              # Technical specification
└── implement/IMPLEMENT.md  # Implementation log (per-phase verification) 

Método CRISPY

C — Clarify      Define requirements
R — Research     Technical research
I — Ideate       Brainstorm solutions
S — Structure    Architecture design
P — Plan         Create plan
Y — Yield        Produce implementation
  + Iterate      Iterate & refine

CRISPY es una evolución de RPI, que añade las fases de Ideación y Estructuración, enfatizando que el diseño de la solución importa más que la implementación.

Colaboración Multi-Modelo (Claude + Codex)

Flujo de trabajo de colaboración en 4 pasos multi-modelo con Claude Code (Opus) + Codex CLI (GPT)

STEP 1: PLAN          Claude Code Opus · Plan Mode
STEP 2: QA REVIEW     Codex CLI GPT · Review plan, insert findings
STEP 3: IMPLEMENT     Claude Code Opus · Phase-by-phase implementation
STEP 4: VERIFY        Codex CLI GPT · Verify against plan

**Idea central:**Diferentes modelos se revisan entre sí. Codex adjunta anotaciones de “Codex Finding” sin reescribir el plan original.

Equipos de Agentes

Flujo de colaboración multi-agente de Equipos de Agentes

Coordina múltiples agentes a través de una lista de tareas compartida (TaskCreate/TaskUpdate). Ideal para grandes refactors que se pueden descomponer en subtareas independientes.

Patrón de Coordinación de Equipo

Tomemos la Orquestación de Hora como ejemplo — tres roles construyen en paralelo, compartiendo un contrato de datos {time, timezone, formatted}:

Lista de Componentes de Equipos de Agentes

---
name: time-agent
description: Get current Dubai time (Asia/Dubai, UTC+4) 
tools: Bash
model: haiku
color: blue
maxTurns: 3
skills: time-fetcher
---
Use Bash to execute `TZ='Asia/Dubai' date`, return time/timezone/formatted fields. 

---
description: Get Dubai time and generate SVG time card
model: haiku
---
1. Agent(time-agent) → fetch {time, timezone, formatted}
2. Skill(time-svg-creator) → generate SVG card
Note: Must execute sequentially, cannot parallelize. 

---
name: time-fetcher
description: Fetch current Dubai time via bash
user-invocable: false
---
Command: TZ='Asia/Dubai' date '+%Y-%m-%d %H:%M:%S %Z'
Return format: { time: "HH:MM:SS", timezone: "GST (UTC+4)", formatted: "full output" }

---
name: time-svg-creator
description: Create Dubai time SVG card
allowed-tools: Write, Read
---
Receive time/timezone/formatted, generate self-contained SVG card. 
Output: agent-teams/output/dubai-time.svg + output.md

Tareas Programadas

# CronCreate Parameters
cron: "*/5 * * * *"     # Standard 5-field cron (local timezone) 
prompt: "Check CI status"   # Prompt executed on trigger
recurring: true          # true=recurring, false=one-shot
durable: true            # true=persist to file

Orientado a Objetivos

Descompone automáticamente y realiza seguimiento del progreso con el sistema de tareas.

1. El usuario establece un objetivo
2. Claude lo descompone en subtareas y crea una lista de tareas
3. Implementa paso a paso, actualizando el estado en cada paso
4. Solicita la intervención del usuario cuando se bloquea

Consejos de Objetivos de la Comunidad

Gestión de Sesiones

La Degradación de Contexto comienza a aparecer alrededor de ~300-400k. Revertir > Corregir.

Análisis de Degradación del Rendimiento de LLM

Fluctuaciones diarias en la calidad de salida del LLM

Pila de Inferencia de 9 Capas (Pesos Congelados ≠ Comportamiento Congelado)

┌──────────────────────────────────────────────┐
│  User session context              ← In-session degradation    │
│  System Prompt                    ← Periodically updated      │
│  Post-Training (RLHF/fine-tuning)  ← Can update silently    │
│  Sampling params (temperature/top-p) ← Server-adjustable    │
│  Speculative Decoding (draft model) ← Quality fluctuation      │
│  MoE routing / batch composition   ← ±8-14% variance   │
│  Hardware routing (TPU/GPU/Trainium)← Different failure modes  │
│  Quantization level (FP16/INT8/INT4)← May change under load │
│  Compiler & runtime (XLA:TPU/CUDA) ← Confirmed bugs  │
├──────────────────────────────────────────────┤
│  Model weights (frozen) ← This layer does not change                    │
└──────────────────────────────────────────────┘

Hallazgos Clave

Post-Mortem de Anthropic 2025.9: 3 Errores de Infraestructura

Error #1 — Error de Enrutamiento de Ventana de Contexto

Error #2 — Corrupción de Salida de TPU

Error #3 — Mala Compilación del Compilador XLA:TPU (El Más Complejo)

Claude se ejecuta en tres plataformas de hardware diferentes (AWS Trainium, NVIDIA GPU, Google TPU), cada una con diferentes modos de fallo, compiladores y comportamiento de precisión. Tus solicitudes pueden llegar a hardware diferente en días diferentes.

Varianza de Enrutamiento MoE (Investigación de Scale AI)

En la arquitectura MoE (Mezcla de Expertos), la composición de consultas de otros usuarios en el lote determina a qué expertos se enruta tu solicitud — y esta composición no es determinista.

Ejemplo específico: el mismo modelo obtuvo un 77% en resistencia a jailbreak un día y un 63% al siguiente — una fluctuación de 14 puntos sin errores, sin cambios.

Actualizaciones de Prompt del Sistema y Post-Entrenamiento

Estudio de Stanford (2023) — y Su Controversia

El estudio fundamental de Chen/Zaharia/Zou encontró que la precisión de GPT-4 en “juicio de números primos” cayó del 97.6% al 2.4% (Mar→Jun 2023), pero tuvo problemas metodológicos:

• La versión de marzo usaba temperature 0.0, la versión de junio usaba temperature 1.0 — una variable de confusión fundamental
• Solo 500 consultas por tarea — tamaño de muestra demasiado pequeño
• Los “problemas matemáticos” eran en realidad preguntas de sí/no, el patrón de respuestas del modelo cambió en lugar de disminuir su capacidad matemática
• Los cambios pueden ser actualizaciones de seguridad post-entrenamiento intencionales, no degradación involuntaria

Factores Psicológicos

Análisis Comparativo de Codex 5.3

Cuando Claude sufre degradación a corto plazo, Codex 5.3 puede parecer significativamente mejor, por las siguientes razones:

1. Ajuste al Objetivo del Producto — Codex está optimizado para la generación de código, produciendo mejores resultados de programación incluso con la misma fuerza de modelo
2. Diferencias en la Estrategia de Razonamiento — Cada proveedor ajusta independientemente la latencia/profundidad de razonamiento/valores predeterminados de decodificación
3. Aislamiento de la Ruta de Servicio — Diferentes capas de enrutamiento/compiladores/pipelines de release, el fallo de uno no afecta al otro
4. Momento del Release — Un proveedor a mitad de release mientras otro está estable puede crear una gran divergencia temporal de calidad

Clasificación de Hipótesis de Degradación

Recomendaciones Prácticas

1. Bloquear snapshots del modelo cuando estén disponibles (en lugar de usar alias flotantes)
2. Almacenar metadatos de solicitudes (ID del modelo, parámetros, latencia, tasas de error)
3. Ejecutar pruebas canary fijas diarias, alertar sobre regresiones
4. Restablecer o compactar sesiones largas después de múltiples fallos
5. Mantener rutas de proveedor/modelo de respaldo
6. Separar la “calidad del modelo” de la “fiabilidad del servicio” en los paneles internos

**La acción más importante:**Cuando la calidad parezca degradada, usa /compact o inicia una nueva sesión. Esta es la acción individual más efectiva — la mayoría del “Claude se volvió tonto” es contaminación del contexto, no degradación del modelo.

Importancia del Harness

Concepto erróneo común: skill/command/subagent/hook terminan todos como prompts, por lo que escribir buenos prompts es suficiente. **Esto es incorrecto.**A nivel de ingeniería, el Harness es un sistema de construcción de prompts + sistema de ejecución determinista + sistema de arquitectura de contexto.

10 Capacidades del Harness (no pueden replicarse con prompts)

La calidad de salida = f(contexto efectivo, capacidad del modelo, ciclos de iteración). Los usuarios controlan solo una pequeña fracción del contexto efectivo; el harness controla el resto y todo el ciclo de iteración. Los prompts sólidos son necesarios pero no suficientes.

Comparación de Browser MCP

Flujo de trabajo recomendado

# Install command
npx playwright install
claude mcp add playwright -s user -- npx @playwright/mcp@latest
claude mcp add chrome-devtools -s user -- npx chrome-devtools-mcp@latest

Playwright tiene la mayor eficiencia de tokens (186.3k restantes), Chrome DevTools la menor (181k restantes). Una diferencia de ~5.3k tokens.

Descubrimiento de Skills en Monorepo

El mecanismo de descubrimiento/carga de Skills es diferente al de CLAUDE.md: CLAUDE.md recorre hacia arriba (carga de ancestros), mientras que Skills utilizan autodescubrimiento de directorios anidados (descubrimiento de descendientes), y solo se cargan bajo demanda cuando se editan archivos en el directorio correspondiente. Consulta Mecanismo de Carga en Monorepo.

Ubicaciones Estándar de Skills

Comparación de Carga: CLAUDE.md vs Skills

El presupuesto de caracteres por defecto es de 15,000 caracteres, ajustable mediante la variable de entorno SLASH_COMMAND_TOOL_CHAR_BUDGET. Usa /context para verificar si se excluyeron habilidades debido a límites de presupuesto.

• Los flujos de trabajo generales van en la raíz .claude/skills/
• Las habilidades específicas del paquete van en el paquete correspondiente .claude/skills/
• Las habilidades de operaciones peligrosas deben configurar disable-model-invocation: true
• Usa prefijos de nombres de paquetes para evitar confusiones (ej. frontend-review, backend-deploy)

Uso y Límites

Comandos de Monitoreo

Optimización de Costos

• Usa model: haiku para tareas simples
• effort: low reduce el razonamiento
• El agente en segundo plano evita el bloqueo
• Los usuarios con clave API usan --max-budget-usd para controlar costos
• Configura el límite mensual de extra-usage para evitar cargos inesperados

Modo Rápido (/fast) cuenta como uso extra desde el primer token, sin consumir la cuota incluida en el plan de suscripción. Debes habilitar y financiar el extra-usage para usarlo.

Verbos del Spinner

La animación de carga de Claude Code utiliza 179 verbos aleatorios. Los más comunes:

Ruta de Aprendizaje

Un viaje de aprendizaje completo construyendo un Weather Reporter desde cero, a través de 5 fases principales · 37 diapositivas:

Orden de Fases (reordenado por dependencias cognitivas)

Mapeo LEVELS (6 niveles)

const LEVELS = {
  context:     '🔴 Context Window',   // context-window.jpeg, context.jpg
  claude_md:   '🟠 CLAUDE.md',   // Project instruction system
  agents:      '🟡 Agent System',     // Built-in + custom agents
  skills:      '🟢 Skills System',     // Skills framework
  commands:    '🔵 Commands System',     // Commands orchestration
  workflow:    '🟣 Full Workflow'    // End-to-end integration
}

Esquema de 37 Diapositivas

Reutilización de Recursos

Contabilidad del Rediseño

• goToSlide() objetivo: los 37 sitios de llamada necesitan actualizar los números de índice
• Atributo data-level: el marcador de nivel de cada diapositiva necesita mapeo a LEVELS
• Componente de navegación: los botones anterior/siguiente necesitan vinculación al nuevo orden de diapositivas
• Barra de progreso: indicador de progreso de 5 segmentos se mapea a 5 fases

Comienza de forma simple → compón gradualmente → orquestación completa. No construyas una arquitectura compleja desde el principio. El orden de las fases está reorganizado por dependencias cognitivas: primero comprende “quién” (Agents), luego “qué pueden hacer” (Skills), luego el “entorno” (Context), luego las “reglas” (CLAUDE.md), finalmente la “orquestación” (Commands).

SDK vs Prompts del Sistema CLI

La CLI de Claude Code y el SDK de Agentes utilizan diferentes estrategias de prompts del sistema:

Diferencias Clave

El SDK proporciona un tipo de prompt modular, permitiendo que las descripciones de herramientas se añadan individualmente, ahorrando muchos tokens en comparación con la carga completa de la CLI.

Preguntas de Mil Millones

13 preguntas profundas sin respuesta de la comunidad — si tienes respuestas, estas son perspectivas de mil millones.

Memoria e Instrucciones (4 preguntas)

1. ¿Qué debería contener CLAUDE.md? — ¿Qué incluir, qué excluir?
2. Si CLAUDE.md existe, ¿aún necesitas constitution.md o rules.md?
3. ¿Con qué frecuencia se debería actualizar CLAUDE.md? ¿Cómo saber si está desactualizado?
4. ¿Por qué Claude sigue ignorando instrucciones en CLAUDE.md — incluso con MUST en mayúsculas?

Agentes, Habilidades y Flujos de Trabajo (6 preguntas)

1. ¿Cuándo usar Command vs Agent vs Skill — cuándo es mejor el Claude Code nativo?
2. ¿Con qué frecuencia deberían actualizarse los agentes/comandos/flujos de trabajo a medida que los modelos se actualizan?
3. Subagentes de propósito general vs específicos por rol/función — ¿una persona detallada realmente mejora la calidad?
4. ¿Usar el modo plan integrado de Claude Code, o construir comandos/agentes de planificación personalizados para aplicar flujos de trabajo de equipo?
5. ¿Cómo coexisten las habilidades personales y las habilidades de la comunidad? ¿Quién tiene prioridad en caso de conflicto?
6. La pregunta definitiva:¿Puedes convertir una base de código existente a especificación, eliminar el código y hacer que la IA regenere solo desde la especificación?

Especificaciones y Documentación (3 preguntas)

1. ¿Debería cada característica en el repositorio tener un archivo de especificación?
2. ¿Con qué frecuencia deberían actualizarse las especificaciones para mantenerse vigentes?
3. Al implementar una nueva característica, ¿cómo manejar los impactos en cascada en las especificaciones de otras características?

Las respuestas a estas preguntas determinarán la dirección de las mejores prácticas de Ingeniería Agéntica. Si tienes perspectivas, esta es la frontera.

Boris Cherny — 13 Reglas

Boris Cherny — Ingeniero Principal de Claude Code

Boris Cherny es ingeniero principal de Claude Code en Anthropic, donde lidera el desarrollo de las herramientas de codificación agénticas utilizadas por cientos de miles de desarrolladores. Es autor de Programming TypeScript (O’Reilly) y conferencista frecuente sobre flujos de trabajo de desarrollo asistido por IA. Las 13 reglas a continuación destilan su guía más repetida en charlas, demos y comentarios de PRs — los mismos consejos que da a los compañeros que se incorporan a Claude Code.

15 Funciones Ocultas

15 funciones menos conocidas de Claude Code de Boris Cherny (Meta), cada una cambiando significativamente la forma en que lo usas.

12 Consejos de Personalización

10 Consejos Avanzados

Consejos de Revisión de Código

Test Time Compute: La Revisión de Código hace que el modelo “piense de nuevo” en un contexto independiente, aumentando la salida en un 200%. La revisión paralela multi-agente (seguridad + rendimiento + arquitectura) produce mayor calidad que una revisión individual.

Estadísticas de PR (Datos Reales de Boris Cherny)

Boris tiene aproximadamente 100% de código nuevo escrito por IA, los humanos revisan y guían la dirección. La clave son los commits independientes por archivo para un historial más claro.

2 Consejos de Merge

6 Consejos de Eficiencia para Opus 4.7

6 métodos centrales de mejora de eficiencia resumidos por Boris Cherny tras el lanzamiento de Opus 4.7.

Mejor Práctica del Modo Auto: Usar con effort: high y /focus, dejar que el Agent trabaje de forma autónoma con alta profundidad de razonamiento, reportando solo los puntos clave de decisión.

Thariq — Diseño de Skills

Thariq Koya es ingeniero del equipo de Claude Code en Anthropic, donde se enfoca en diseño de skills, gestión de sesiones y flujos de trabajo agénticos prácticos. Las secciones a continuación destilan su guía más citada — de las revisiones internas de skills de Anthropic (marzo 2026) y sus notas de campo sobre el uso real de Claude Code. Son los mismos patrones que sigue al diseñar skills para equipos en producción.

Thariq — Consejos Prácticos

Gestión de Sesión — Guía Profunda

Marco profundo de gestión de sesión de Thariq: comprensión de la degradación del contexto, estrategias de ramificación, recolección de basura de subagentes.

Deterioro del Contexto: Aproximadamente en 300k-400k tokens el modelo empieza a “olvidar” conversaciones anteriores, la calidad de la salida disminuye significativamente. Esto no es un error, sino una propiedad matemática de la atención.

5 Estrategias de Ramificación

• EstrategiaEscenarioDescripción continueContinuar desde el últimoRestaurar el contexto completo para continuar la conversación rewindVolver a un puntoDeshacer hasta el paso especificado y reiniciar clearInicio nuevoLimpiar el contexto, empezar desde cero compactComprimir y retenerComprimir inteligentemente reteniendo información clave subagentEjecución aisladaEnviar subagente, sin contaminación del contexto principal

Tabla de Decisiones Clave

• EscenarioAcción Recomendada Contexto > 50%/compact o enviar subagente Dirección incorrectarewind al punto de divergencia, no corregir en el lugar Baja calidad después de compactarUsar /compact [brief] con instrucciones de resumen, o directamente clear + CLAUDE.md Necesidad de preservar historialEl subagente maneja nuevas tareas, la conversación principal se mantiene ligera Sobrecarga de contexto del subagenteLos subagentes tienen GC integrado — se recolectan automáticamente tras la finalización, sin impacto en la sesión principal

Compactar vs Inicio Nuevo: Si el historial de conversación es muy relevante (ej. cadena de depuración), usa compact + brief; si el tema ha cambiado completamente, clear y reconstruir contexto desde CLAUDE.md es más eficiente. Causa típica de un compactado deficiente: instrucciones de compresión vagas que provocan la pérdida de restricciones clave.

83 Consejos Categorizados

De prácticas de la comunidad y recomendaciones oficiales, organizados en 16 categorías de herramientas. Referencias principales: convenciones de CLAUDE.md, paralelismo de Subagentes, Flujo de Trabajo RPI.

Videos Destacados

Boris Cherny × Ryan Peterman — Historia profesional del creador de Claude Code Principiante

Boris Cherny × Lenny's Podcast — Nacimiento de Claude Code y filosofía de producto Producto

Karpathy × AI Engineer — De Vibe Coding a Ingeniería Agentic Avanzado

Matt Pocock Workshop — Taller práctico de 2 horas sobre Claude Code Tutorial

Comandos Comunes (82 integrados)

Opciones de CLI (16 categorías)

Referencia completa de las opciones de inicio de CLI, organizadas por función.

Variables de Entorno

Plantillas de Configuración

# Project Name

## Tech Stack
- Frontend: React + TypeScript
- Backend: Node.js + Express

## Coding Conventions
- File naming: kebab-case
- Components: functional + hooks
- Testing: Vitest

## Constraints
- Do not use any type
- Do not skip tests
- API must have error handling

{
  "permissions": {
    "allow": ["Bash(npm run *)","Bash(git status)","Read","Grep","Glob"],
    "deny": ["Bash(rm -rf *)","Bash(git push --force)"]
  }
}

---
name: my-agent
description: Perform specific task
tools: "Bash,Read,Write,Edit,Grep"
model: sonnet
maxTurns: 20
memory: project
---

# My Agent
1. Read relevant files
2. Analyze code
3. Implement changes
4. Verify results

---
name: my-skill
description: What to do
arguments: filename
allowed-tools: "Read,Write,Edit"
paths: "src/**/*.ts"
---

Process $filename: 
1. Read → 2. Transform → 3. Write back

Hoja de Referencia de Flujos de Trabajo