Guía de Estudio · Claude Certified Architect

Tema 0 · Fundamentos

Conceptos base que necesitas dominar

Antes de entrar a los dominios específicos del examen, hay 6 conceptos transversales que aparecen en TODAS las preguntas. Si no los manejas bien, te vas a equivocar incluso cuando sepas la teoría del dominio.

📡1. La API de Claude es completamente stateless

Cada llamada a la API de Claude es independiente. Claude NO recuerda nada entre requests. No hay session_id, no hay memoria server-side, no hay base de datos automática.

Si quieres una conversación multi-turno, tú debes pasar el historial completo en el array messages de cada request. Esto explica por qué las conversaciones largas se vuelven caras y lentas: cada turno acumula más tokens.

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": "Eres un asistente útil.",
  "messages": [
    {"role": "user", "content": "Hola, me llamo Miguel"},
    {"role": "assistant", "content": "¡Hola Miguel!"},
    {"role": "user", "content": "¿Cómo me llamo?"}  # Sin los anteriores, Claude NO sabría
  ]
}

⚠️

Trampa frecuente

Si tu app no incluye los mensajes anteriores en cada llamada, Claude pierde todo el contexto. Síntoma típico: el modelo pregunta cosas que el usuario ya respondió hace 2 turnos.

🛑2. stop_reason — cómo saber por qué Claude terminó

Cada respuesta de Claude incluye un campo stop_reason que indica POR QUÉ paró de generar. Es la única forma confiable de detectar el fin de un turno (NUNCA parsear el texto).

Valor	Significado	Qué hacer
`"end_turn"`	Claude terminó voluntariamente	Mostrar resultado al usuario
`"tool_use"`	Claude quiere llamar una herramienta	Ejecutar la tool, devolver `tool_result`
`"max_tokens"`	Se acabaron los tokens permitidos	Respuesta truncada — aumentar límite o dividir tarea
`"stop_sequence"`	Se generó una secuencia que TÚ definiste	Procesar según tu lógica
`"refusal"`	Claude se negó por razones de seguridad	Reformular el prompt

⚡ Implementación correcta del loop agente

El patrón estándar es: 1) Mandar request. 2) Si stop_reason === "tool_use", ejecutar la tool y devolver el resultado en un nuevo mensaje user. 3) Si stop_reason === "end_turn", terminar y mostrar. 4) Repetir.

⚠️

Antipatrones comunes

NO parsear el texto buscando "Done" o "Listo". NO usar max_iterations=5 como mecanismo principal de parada (solo como safety net). NO confiar en el contenido textual para saber si Claude terminó.

🎭3. Cómo funciona el system prompt

El system prompt define el rol, las restricciones y el comportamiento de Claude. Tiene 3 características importantes:

1

Va en el campo system de la request, NO en el array messages. Es un parámetro separado.

2

Tiene prioridad sobre los mensajes del usuario. Si el usuario pide algo que el system prohíbe, Claude se niega.

3

Se incluye automáticamente en cada llamada (no en messages), pero cuenta hacia los tokens. Un system prompt de 2,800 tokens es caro de mantener.

⚠️ Trampa importante — asociaciones no intencionadas

Una instrucción mal redactada en el system prompt puede crear comportamiento incorrecto. Ejemplo: si pones "siempre verifica al cliente primero", Claude va a llamar a get_customer incluso cuando el usuario pregunta por el stock, donde no aplica. Sé específico sobre cuándo aplican las reglas.

📏4. Tokens, ventana de contexto y "lost-in-the-middle"

Claude no procesa texto, procesa tokens (fragmentos de palabras). Aproximadamente 1 token ≈ 4 caracteres en español. La ventana de contexto es el TOTAL de tokens que Claude puede ver en una sola request: system + messages + tools + tool_results.

Componentes que llenan tu ventana

System prompt (1 vez)

Todo el historial de messages (crece cada turno)

Definiciones de tools (1 vez)

Cada tool_result (crece con cada tool call)

El output que Claude genera (cuenta hacia max_tokens)

Los 3 problemas críticos del contexto

Lost-in-the-middle: Claude lee bien lo del inicio y el final, pero pierde lo del medio. Pon lo importante al principio o al final.

Acumulación de tool results: si un tool devuelve 40 campos y solo necesitas 5, esos 35 extra contaminan tu contexto.

Sumarización progresiva: al condensar el historial pierdes valores exactos. "$89.99" se vuelve "aproximadamente $90".

🔧5. Tool use y JSON Schema

Claude puede llamar funciones externas (tools) que TÚ defines. El modelo no las ejecuta — solo genera una solicitud estructurada para llamarlas. Tu código las ejecuta y devuelve el resultado.

Una tool se define con 3 cosas: name, description (lo más importante: así Claude decide cuándo usarla), e input_schema en JSON Schema.

{
  "name": "get_customer",
  "description": "Busca un cliente por email o ID. Devuelve perfil completo (nombre, email, historial de pedidos, estado). Usa esta tool ANTES de lookup_order para verificar identidad. Acepta email (user@domain.com) o customer_id numérico.",
  "input_schema": {
    "type": "object",
    "properties": {
      "email": {"type": "string"},
      "customer_id": {"type": "integer"}
    },
    "required": []
  }
}

💡 Por qué la descripción importa tanto

Claude decide qué tool usar leyendo la description. Si pones "Retrieves customer information", Claude va a confundirse cuando haya 3 tools similares. Si pones una descripción detallada con casos de uso y comparaciones contra otras tools, la selección es 95%+ confiable.

⚖️6. Errores sintácticos vs semánticos en salida estructurada

Cuando usas JSON Schema con tool_use, eliminas completamente los errores sintácticos (JSON malformado, tipos incorrectos, faltan llaves). Eso ya no es problema.

Pero hay otra capa: los errores semánticos. El JSON está bien escrito pero los valores son incorrectos. Para eso necesitas otro nivel de validación.

Tipo de error	Ejemplo	Solución
Sintáctico	JSON inválido, tipo erróneo	`tool_use` con JSON Schema lo elimina 100%
Semántico	Total = 150, pero suma de items = 145	Validación con Pydantic, retry con feedback
De fabricación	Inventó un campo que no estaba en el doc	Marcar campo como `["string", "null"]` nullable

⚡ Patrón "self-correction"

Para detectar contradicciones internas, haz que Claude extraiga TANTO el valor declarado COMO el calculado, y emita una bandera conflict_detected cuando difieran. Así no escondes errores.

🗺️Mapa de los 5 dominios del examen

El examen evalúa 5 áreas con pesos distintos. Estudia los dominios proporcional a su peso:

D1 · Agentes · 27%

D2 · MCP · 18%

D3 · Claude Code · 20%

D4 · Prompts · 20%

D5 · Contexto · 15%

D1 — Agentes y orquestación

D2 — MCP y tools

D3 — Claude Code

D4 — Prompts

D5 — Contexto y confiabilidad

Tema 1 · Dominio 1 · 27%

Arquitectura de agentes y orquestación

El dominio más pesado. Aquí se cubre cómo construir agentes autónomos con Claude Agent SDK: el ciclo agente, sistemas multiagente hub-and-spoke, hooks para garantías determinísticas, y manejo de errores en producción.

🔄1. El ciclo agente (Agentic Loop)

Un agente no es solo una respuesta de Claude. Es un loop iterativo donde Claude decide qué hacer, ejecuta, recibe feedback, y decide de nuevo. Este enfoque se llama model-driven: el modelo, no tu código, decide qué tool llamar a continuación.

# Pseudocódigo del ciclo agente
messages = [{"role": "user", "content": user_request}]

while True:
    response = claude.messages.create(
        model="claude-sonnet-4-6",
        messages=messages,
        tools=tools
    )

    if response.stop_reason == "end_turn":
        return response.content  # Terminó voluntariamente

    if response.stop_reason == "tool_use":
        tool_calls = extract_tool_calls(response)
        tool_results = [execute_tool(call) for call in tool_calls]
        messages.append({"role": "assistant", "content": response.content})
        messages.append({"role": "user", "content": tool_results})
        continue

¿Por qué model-driven y no decision tree?

Un árbol de decisión hardcoded ("si pregunta sobre devolución → call X → Y → Z") falla en cuanto el caso real no encaja en el árbol. Claude maneja casos no previstos porque razona sobre qué tool aplicar. Tu trabajo es definir buenas tools con buenas descriptions, no programar todas las rutas.

⚠️

Antipatrones del ciclo agente

1) Parsear el texto del assistant para detectar finalización ("Tarea completada" en la respuesta). 2) Usar max_iterations=5 como mecanismo PRINCIPAL de parada. 3) Reintentos infinitos dentro de un subagente. La señal correcta de fin SIEMPRE es stop_reason === "end_turn".

⚙️2. Configurar un agente con AgentDefinition

En Claude Agent SDK, un agente se define con un objeto AgentDefinition que tiene 4 campos clave:

agent = AgentDefinition(
    name="customer_support",
    description="Procesa solicitudes de clientes sobre devoluciones, disputas y problemas de cuenta",
    system_prompt="""Eres un agente de soporte. Antes de cualquier acción:
    1. Verifica la identidad del cliente con get_customer
    2. Si hay un pedido involucrado, llama a lookup_order
    3. Para reembolsos > $500, escala con escalate_to_human""",
    allowed_tools=["get_customer", "lookup_order", "process_refund", "escalate_to_human"]
)

⚡ Principio de privilegios mínimos

allowed_tools debe contener solo lo necesario. Estudios muestran que agentes con 18 tools tienen 65% de precisión de selección; con 4-5 tools, sube a 90%+. Distribuye tools entre agentes especializados, no metas todo en uno.

🌐3. Sistemas multiagente — patrón hub-and-spoke

Cuando una tarea es muy grande para un solo agente (investigación con búsqueda + análisis + síntesis), divides en coordinador + subagentes. Toda la comunicación pasa por el coordinador — los subagentes no se hablan entre sí.

         Coordinador
        /     |      \
   Subagent1  Subagent2  Subagent3
   (web)      (docs)     (síntesis)

⚠️ Principio CRÍTICO — contexto aislado

Los subagentes NO heredan el historial del coordinador. Cada uno tiene su propia conversación. Todo el contexto que necesiten debe pasarse explícitamente en el prompt del Task. Esto es la fuente del 80% de errores en sistemas multiagente.

❌ Incorrecto

Task: "Analiza el documento"

El subagente no sabe qué documento, qué buscar, ni qué formato devolver.

✓ Correcto

Task: """Analiza el siguiente documento.

Documento: [texto completo]
Búsqueda previa: [resultados web]
Formato salida: JSON con campos
{claims, sources, dates}"""

Todo lo necesario está en el prompt.

⚡ Paralelización con Task

El coordinador puede llamar varios Task en una sola respuesta y los subagentes se ejecutan en paralelo. Esto es la diferencia entre 30 segundos (secuencial) y 5 segundos (paralelo) para una investigación de 5 fuentes.

🪝4. Hooks — cuando necesitas garantías determinísticas

Los prompts son probabilísticos. Aunque digas "nunca proceses reembolsos sobre $500", el modelo cumple ~95% de las veces. Para el 5% restante necesitas algo determinístico: hooks.

Un hook es código que se ejecuta en puntos específicos del ciclo del agente. Hay 2 tipos principales:

PreToolUse — antes de ejecutar

@hook("PreToolUse")
def enforce_limit(call):
    if call.name == "process_refund" \
       and call.args.amount > 500:
        return redirect_to_escalation(call)

Bloquea la llamada antes de que ocurra. Útil para compliance, validaciones, redirects.

PostToolUse — antes de pasar el resultado al modelo

@hook("PostToolUse", tool="lookup_order")
def trim_order(result):
    return {
        "order_id": result["order_id"],
        "status": result["status"],
        "total": result["total"]
    }  # 35 campos descartados

Transforma el resultado de la tool antes de que Claude lo vea. Útil para trimming y normalización.

⚡ Regla de oro: hooks vs prompts

Cuando un error tiene consecuencias financieras, legales o de seguridad, usa hooks (determinístico). Si es preferencia de formato o sugerencia, prompts (probabilístico) bastan. Hooks = garantía 100%. Prompts = ~95%.

🧩5. Cómo descomponer tareas complejas

Hay dos formas de partir un trabajo grande:

Pipeline fijo (prompt chaining)

Pasos predefinidos en secuencia:

Documento
  → Extracción metadata
  → Extracción datos
  → Validación
  → Enriquecimiento
  → Salida final

Cuándo usarlo

Tareas predecibles, repetitivas, con todos los pasos conocidos. Ejemplo: pipeline de extracción de facturas.

Descomposición dinámica

Las subtareas se deciden en runtime:

# "Agrega tests a base legacy"
Mapear estructura
→ 3 módulos sin tests
→ Priorizar pagos (alto riesgo)
→ Descubrir API externa
→ Adaptación: mock primero

Cuándo usarlo

Tareas abiertas, exploratorias, donde no sabes de antemano cuántos pasos vas a necesitar.

⚡ Caso especial: revisión de código multi-pasada

Para PRs de 10+ archivos, una sola pasada causa dilución de atención (análisis profundo en algunos, superficial en otros). Mejor patrón: 1) Pasada por-archivo (problemas locales). 2) Pasada de integración (problemas entre archivos).

🔧6. Manejo de errores en sistemas multiagente

Cuando un subagente falla, el coordinador necesita información suficiente para decidir: ¿reintentar? ¿cambiar el query? ¿escalar? ¿continuar sin esta sección? Un error genérico "Operation failed" no permite ninguna decisión inteligente.

Las 4 categorías de error que debes distinguir

Categoría	Ejemplo	¿Retry?	Acción
Transient	Timeout, 503, fallo red	Sí	Backoff exponencial
Validation	Input inválido, falta campo	No	Corregir input antes de retry
Business	Política violada, límite excedido	No	Explicar al usuario, ofrecer alternativa
Permission	Sin permisos de acceso	No	Escalar a humano

Error estructurado de un subagente (patrón correcto)

{
  "status": "partial_failure",
  "failure_type": "timeout",
  "errorCategory": "transient",
  "isRetryable": true,
  "attempted_query": "AI music 2024",
  "partial_results": [
    {"title": "Music AI Report", "url": "...", "relevance": 0.8}
  ],
  "alternative_approaches": [
    "Búsqueda más específica: 'AI music composition'",
    "Usar fuente alternativa"
  ],
  "coverage_impact": "Sin cobertura: producción musical"
}

⚡ Recuperación local + propagación

Patrón estándar: 1-2 reintentos locales dentro del subagente para errores transient. Si fallan, propagar al coordinador con error estructurado. El coordinador decide: ¿usar resultados parciales? ¿invitar otro subagente? ¿anotar gap en cobertura?

⚠️

Antipatrón: supresión silenciosa

NUNCA hagas que un fallo se vea como "sin resultados" (lista vacía). El coordinador piensa que la búsqueda fue exitosa pero no encontró nada, cuando en realidad nunca ocurrió. Distingue siempre "vacío legítimo" de "fallo de acceso".

📁7. Sesiones: --resume y fork_session

Cuando un agente trabaja durante varias horas o días, necesitas persistir el estado. Claude Agent SDK ofrece dos mecanismos:

--resume <session-name>

Reanuda una sesión nombrada con el contexto guardado. Útil para investigaciones largas que abarcan varios días. Riesgo: si los archivos o el estado del sistema cambiaron desde la sesión anterior, los resultados de las tools en el historial pueden estar obsoletos y llevar a conclusiones equivocadas.

fork_session

Crea una rama independiente desde un punto común. Las dos ramas heredan el contexto hasta el fork y luego se desarrollan independientemente. Útil para comparar dos enfoques (ej. Redux vs Context API) sin perder el trabajo de exploración.

⚡ Cuándo NO reanudar y mejor empezar fresca

Si pasaron muchos días o si los archivos clave cambiaron, iniciar una sesión nueva con un resumen estructurado ("Esto descubrimos: A, B, C...") es más confiable que --resume con datos viejos que pueden contradecir el estado actual del código.

Tema 2 · Dominio 2 · 18%

Model Context Protocol (MCP) y diseño de herramientas

MCP es el protocolo abierto para conectar sistemas externos a Claude. Cubre diseño de tools, JSON Schema, errores estructurados, y cuándo usar Resources vs Tools.

🔌1. Qué es MCP y los 3 tipos de recursos

Model Context Protocol es un protocolo abierto (open standard) que permite a Claude conectarse a sistemas externos de forma estandarizada. En lugar de programar integraciones one-off, configuras servidores MCP y Claude las usa automáticamente.

MCP define 3 tipos de recursos. La diferencia es crítica para el examen:

🔧 Tools

Funciones que ejecutan acciones: CRUD en BD, llamadas a APIs, comandos. Modifican estado.

📚 Resources

Datos pasivos que el agente puede leer para contexto: documentación, esquemas BD, catálogos. No modifican estado.

📝 Prompts

Plantillas predefinidas para tareas comunes que el agente puede instanciar.

⚡ Cuándo usar Resources en lugar de Tools

Si tu agente necesita saber qué issues existen en Jira antes de actuar, hacer 10 llamadas list_issues es ineficiente. Mejor expone un Resource con el catálogo de issues — el agente lo lee una vez y tiene todo el "mapa" sin llamadas exploratorias.

⚙️2. Cómo configurar un servidor MCP

Los servidores MCP se declaran en un archivo JSON. Hay 2 niveles:

Archivo	Alcance	VCS	Cuándo usarlo
`.mcp.json` (raíz repo)	Proyecto, equipo	Sí, commit	Integraciones del equipo (GitHub, Jira)
`~/.claude.json`	Personal, home	No	Experimentos personales

Estructura de .mcp.json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "jira": {
      "command": "npx",
      "args": ["-y", "mcp-server-jira"],
      "env": { "JIRA_TOKEN": "${JIRA_TOKEN}" }
    }
  }
}

⚡ Variables de entorno para secretos

El archivo .mcp.json se commitea en git (todo el equipo lo ve), pero los tokens NO. Usa ${GITHUB_TOKEN} — Claude resuelve la variable en runtime desde tu ambiente local.

💡

Preferencia: comunitario sobre propio

Para integraciones estándar (GitHub, Jira, Slack), prefiere servidores MCP comunitarios que ya existen y están mantenidos. Construye tu propio servidor MCP solo para workflows únicos del equipo.

📝3. Tool descriptions — el arte de la selección confiable

La description de una tool es el mecanismo principal por el que Claude decide cuándo usarla. Una mala description es la causa #1 de selección errónea de tools.

❌ Descripción mínima

"description": "Retrieves customer information"

Claude no sabe: ¿busca por email o ID? ¿qué devuelve? ¿cuándo usarla vs alternativas?

✓ Descripción completa

"description": "Busca un cliente por email o ID. Devuelve perfil con nombre, email, historial de pedidos, estado de cuenta. USA esta tool ANTES de lookup_order para verificar identidad. Acepta email (user@domain.com) o customer_id numérico."

Especifica formato, devolución, orden de uso y comparación con otras tools.

Una buena description SIEMPRE incluye:

1

Qué hace exactamente y qué devuelve

2

Formato de entrada y ejemplos de valores válidos

3

Casos límite y limitaciones conocidas

4

Cuándo usar esta tool vs alternativas similares (clave para evitar confusión)

⚠️

Trampa: descripciones que se solapan

Si tienes analyze_content y analyze_document con descripciones casi idénticas, Claude elegirá al azar. Renombra para eliminar solapamiento (ej. extract_web_results vs analyze_local_file) o haz las descripciones claramente distintas.

📐4. JSON Schema — decisiones de diseño que importan

El input_schema define la estructura de los parámetros. Hay 4 decisiones de diseño que cambian drásticamente el comportamiento de Claude:

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": ["bug", "feature", "docs", "unclear", "other"]
    },
    "category_detail": {
      "type": ["string", "null"],
      "description": "Detalles si category = 'other' o 'unclear'"
    },
    "severity": {
      "type": "string",
      "enum": ["critical", "high", "medium", "low"]
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    }
  },
  "required": ["category", "severity"]
}

Las 4 reglas de diseño

Decisión	Efecto en Claude
required solo lo SIEMPRE disponible	Required fuerza al modelo a inventar si no encuentra el dato
nullable `["string", "null"]`	El modelo devuelve `null` en vez de inventar
enum con "other" + detail	Permite categorizar sin perder casos atípicos
enum con "unclear"	Un "no sé" honesto > una categoría errónea

🎯5. tool_choice — controlar la selección

A veces necesitas más control que solo "Claude decide". Para eso existe tool_choice:

Valor	Comportamiento	Cuándo usarlo
`{"type": "auto"}`	Claude decide: usar tool o responder con texto	Default, mayoría de casos
`{"type": "any"}`	Claude DEBE llamar alguna tool (la que sea)	Garantizar salida estructurada
`{"type": "tool", "name": "X"}`	Claude DEBE llamar la tool X específicamente	Forzar primer paso del pipeline
`{"type": "none"}`	Claude solo responde con texto, sin tools	Modo conversación pura

⚡ Caso práctico de tool_choice: "any"

Tienes 3 tools de extracción (extract_invoice, extract_receipt, extract_contract) y quieres garantizar que Claude SIEMPRE devuelva datos estructurados sin importar el tipo de documento. any es perfecto: Claude elige la apropiada pero TIENE que usar una.

⚠️6. Errores en MCP — el patrón estructurado

Cuando una tool MCP falla, devuelve un objeto con isError: true. Pero el contenido del error es CRÍTICO — un error genérico le impide al agente decidir cómo recuperarse.

❌ Error genérico (antipatrón)

{
  "isError": true,
  "content": "Operation failed"
}

El agente no sabe: ¿transient? ¿escalar? ¿reintentar? Va a quedarse atorado.

✓ Error estructurado

{
  "isError": true,
  "content": {
    "errorCategory": "transient",
    "isRetryable": true,
    "message": "Timeout en API tras 30s",
    "attempted_query": "order_id=12345",
    "partial_results": null,
    "alternative_approaches": ["Reducir batch"]
  }
}

El agente sabe exactamente qué pasó y qué hacer.

⚡ Caso especial — retry interno vs propagación

Para errores de tipo transient (timeout, 503), maneja el retry adentro de la tool con backoff exponencial. Para errores de sintaxis o validación (input inválido) que NUNCA van a funcionar, devuélvelos inmediatamente sin retry. Esto evita perder tiempo en errores que nunca tendrán éxito.

🔐7. Patrón avanzado — token de confirmación para acciones críticas

Cuando una tool puede causar daño irreversible (eliminar un usuario, mover dinero), necesitas garantías arquitectónicas de que se ejecutó una preview antes. Un parámetro dry_run: boolean NO es suficiente — el modelo lo va a omitir el 5% de las veces.

Solución: dividir la acción en 2 tools acopladas por un token de uso único:

# Tool 1: preview — devuelve detalles + token
preview_remove_member(user_id="USR-123")
# → {"impact": "...", "confirmation_token": "tk_xa9bz3"}

# Tool 2: execute — REQUIERE el token
execute_remove_member(user_id="USR-123", token="tk_xa9bz3")
# → falla si el token no se generó hace <5 min con los mismos parámetros

⚡ Por qué este patrón es superior

Hace arquitectónicamente imposible ejecutar sin preview previa. La tool de execute literalmente requiere un token que solo la tool de preview puede generar. No depende de instrucciones al modelo, ni de hooks externos, ni de heurísticas temporales. Es la única forma de garantizar al 100% que cada acción crítica fue previsualizada.

Tema 3 · Dominio 3 · 20%

Claude Code — configuración y flujos de trabajo

Cómo configurar Claude Code en un proyecto real: la jerarquía CLAUDE.md, importación modular @path, reglas con paths globs, skills, plan mode, CLI para CI/CD y gestión de sesiones.

📂1. Jerarquía CLAUDE.md (los 3 niveles)

CLAUDE.md es donde le das instrucciones persistentes a Claude Code. Existe en 3 niveles, cada uno con un alcance distinto:

Nivel	Ubicación	Alcance	VCS
Usuario	`~/.claude/CLAUDE.md`	Solo tú, en todos tus proyectos	No (local)
Proyecto	`.claude/CLAUDE.md` o `CLAUDE.md` en raíz	Todo el equipo del proyecto	Sí (git)
Directorio	`CLAUDE.md` dentro de subdirs	Trabajo en ese directorio específico	Sí

⚠️ Error típico del examen

"Un nuevo miembro del equipo no recibe las instrucciones del proyecto" — causa: están en ~/.claude/CLAUDE.md (nivel usuario, local) en lugar de .claude/CLAUDE.md (proyecto, versionado).

🔗2. Sintaxis @path — instrucciones modulares

Un CLAUDE.md monolítico de 500 líneas es difícil de mantener. La sintaxis @path permite importar otros archivos, lo que hace tu configuración modular:

# CLAUDE.md del proyecto

## Estándares de codificación
Los estándares se describen en @./standards/coding-style.md

## Testing
Requisitos en @./standards/testing-requirements.md

## Contexto del proyecto
@README.md
@package.json

Reglas de la sintaxis

@ directo antes del path (sin espacio)

Se soportan paths relativos y absolutos

Relativos se resuelven respecto al archivo que los contiene

Profundidad máxima: 5 niveles de imports anidados

📋3. .claude/rules/ con paths — convenciones condicionales

CLAUDE.md aplica a TODA la conversación. Pero a veces quieres reglas que apliquen solo a ciertos archivos. Para eso existe .claude/rules/:

# .claude/rules/testing.md
---
paths: ["**/*.test.tsx", "**/*.test.ts"]
---

Tests deben usar bloques describe/it.
Usa factories de datos en lugar de hardcoded.
No mockees la DB — usa BD de prueba.

⚡ Cómo funciona la carga condicional

Esta regla se carga solo cuando Claude está editando un archivo que coincide con el glob. Si trabajas en src/api/handler.ts, no se carga. Si trabajas en src/components/Button.test.tsx, sí. Ahorra contexto al no cargar reglas irrelevantes.

Cuándo usar .claude/rules/ vs CLAUDE.md de directorio

Caso	Solución
Convenciones para archivos dispersos en muchos dirs (tests, migraciones)	`.claude/rules/` con globs
Convenciones vinculadas a un directorio específico (todo en `src/api/`)	CLAUDE.md de directorio

🎯4. Skills — comandos extendidos invocables

Un skill es un comando reutilizable que se invoca con /nombre. Vive en .claude/skills/<nombre>/SKILL.md. La estructura básica:

# .claude/skills/code-review/SKILL.md
---
name: code-review        # requerido, lowercase + guiones
description: Reviews PRs for bugs, security, and style.
             Use when reviewing pull requests.
allowed-tools: ["Read", "Grep", "Glob"]   # opcional, restringe
model: sonnet              # opcional, fuerza modelo
context: fork             # opcional, ejecuta aislado
argument-hint: "PR URL or path"
---

Analiza el código y reporta:
- Bugs lógicos
- Vulnerabilidades de seguridad
- Violaciones del style guide

Para cada problema, indica archivo:línea y severity.

Los 4 campos opcionales del frontmatter

Campo	Para qué sirve
`allowed-tools`	Restringe qué tools puede usar el skill (seguridad — no puede borrar archivos si no está en la lista)
`model`	Fuerza un modelo específico (ej. sonnet para revisión, opus para tareas complejas)
`context: fork`	Ejecuta el skill en un subagente aislado, no contamina la sesión principal con salida verbosa
`argument-hint`	Pista que solicita al usuario cuando invoca sin argumentos

⚠️ Jerarquía de prioridad (MEMORIZAR)

Si hay skills con el mismo nombre en distintos niveles, gana en este orden: Enterprise → Personal → Project → Plugins. La idea: las orgs pueden imponer compliance que ningún user puede sobrescribir.

🗺️5. Plan Mode vs ejecución directa

Por default Claude Code ejecuta cambios inmediatamente. Para tareas grandes o ambiguas eso es peligroso. Plan Mode es un modo donde Claude SOLO explora y propone un plan, sin hacer cambios:

	Plan Mode	Ejecución directa
Tools permitidas	Read, Grep, Glob (exploración)	+ Write, Edit, Bash (modificación)
Output	Plan textual aprobable	Cambios reales en archivos
Reversible	Sí (no cambia nada)	Necesitas git para revertir

Cuándo usar Plan Mode

Cambios a gran escala (decenas de archivos)

Múltiples enfoques válidos (decisiones arquitectónicas)

Codebase desconocida que necesitas entender primero

Migraciones de bibliotecas que afectan 45+ archivos

⚡ Patrón recomendado: combinar ambos

1) Plan Mode para explorar y diseñar. 2) Apruebas el plan. 3) Ejecución directa para implementar el plan aprobado. No uses Plan Mode para bugs simples con stack trace claro — ahí ejecución directa es más rápida.

⚙️6. Claude Code CLI para CI/CD

Para integrar Claude Code en pipelines de CI (GitHub Actions, GitLab CI), necesitas el modo no-interactivo:

# Modo correcto para CI
claude -p "Revisa este PR para problemas de seguridad" \
  --output-format json \
  --json-schema '{"type": "object", ...}'

-p (o --print): procesa, imprime a stdout, termina. NO espera input.

--output-format json: salida en JSON estructurado para parsing programático.

--json-schema: valida la salida contra un schema. Garantiza estructura.

⚠️ Trampa: aislamiento generación vs revisión

La misma sesión de Claude que generó código es menos efectiva para revisarlo: retiene el contexto de razonamiento y es menos propenso a cuestionar sus propias decisiones. Para revisión en CI, usa una instancia independiente sin el contexto del código generado.

⚡ Prevenir comentarios duplicados en re-revisiones

Cuando un PR recibe nuevos commits y vuelves a correr la revisión, vas a duplicar comentarios. Solución: pasa los resultados de la revisión anterior en el contexto e instruye: "Reporta SOLO problemas nuevos o no arreglados".

💾7. Comandos integrados: /compact, /memory, fork_session

/compact

Sumariza el historial anterior y libera ventana de contexto. Útil en sesiones largas con mucha salida verbosa de tools. Riesgo: pierde valores numéricos exactos, fechas y detalles específicos durante la sumarización.

/memory

Abre tu CLAUDE.md para edición. Útil para guardar notas, preferencias o contexto que quieres que persista entre sesiones (convenciones del proyecto, comandos frecuentes, decisiones de diseño).

fork_session

Crea una rama de sesión independiente desde el contexto actual. Útil para comparar dos enfoques sin perder el trabajo previo: "¿Y si refactor con Redux vs Context API?" — fork al punto de exploración, desarrolla ambos en paralelo.

⚡ Subagente Explore — proteger tu contexto

Cuando tu sesión principal está llena pero necesitas explorar 30 archivos más, usa el subagente Explore. Aísla la salida verbosa en su propio contexto y solo devuelve un resumen al main. Previene agotamiento de ventana en tareas multifase.

Tema 4 · Dominio 4 · 20%

Ingeniería de prompts y salida estructurada

Técnicas para que Claude se comporte de forma predecible: few-shot, criterios explícitos, prompt chaining, validación con retry, self-correction, y manejo de conversaciones largas.

🎓1. Few-shot prompting — enseñar con ejemplos

El few-shot prompting consiste en mostrarle a Claude 2-4 ejemplos de input/output dentro del prompt. Es más efectivo que descripciones textuales porque:

Una instrucción como "sé más preciso" se interpreta de muchas formas

Un ejemplo concreto muestra inequívocamente el formato y la lógica esperados

El modelo generaliza el patrón a casos nuevos (no solo repite los ejemplos)

Los 5 usos típicos de few-shot

1. Escenarios ambiguos

"Mi pedido está roto"
→ get_customer + lookup_order + verificar
roto puede ser dañado, necesita ver detalles

"Dame un gerente"
→ escalate_to_human inmediato
solicitud explícita, no intentar resolver

2. Formato exacto de salida

Muestra el JSON con todos los campos y valores tipo. Claude lo replica.

3. Aceptable vs problemático

data.filter(x => x.active) ✓
data.filter(x => x.active == true) ✗
(usar === estricto)

4. Múltiples formatos de doc

Citas inline: "(Smith, 2023)" → diferente extracción
Bibliografía: "[1]" → diferente extracción

5. Medidas informales

"dos puñados de arroz"
→ {amount: "~100g", precision: "approximate"}
Reglas textuales no cubren toda la variedad — few-shot sí

⚡ Reglas de normalización

Combina few-shot con reglas explícitas: "Fechas siempre ISO 8601, 'ayer' → fecha absoluta. Moneda: valor + código."

✏️2. Criterios explícitos vs instrucciones vagas

"Sé conservador" y "reporta con cuidado" son instrucciones que cada modelo interpreta distinto. Los criterios explícitos eliminan ambigüedad:

❌ Vago

# Verifica los comentarios del código.
# Sé conservador, reporta solo hallazgos
# de alta confianza.

¿Qué cuenta como "alta confianza"? ¿Qué problemas reportar y cuáles no?

✓ Criterios explícitos

# Marca un comentario como problemático
# SOLO SI:
# 1. Contradice el comportamiento real
# 2. Referencia función/variable no existente
# 3. TODO/FIXME para bug ya arreglado
#
# NO marques:
# - Comentarios estilísticamente obsoletos
# - Imprecisiones menores de lenguaje
# - Ausencia de comentarios (es otra categoría)

No queda ambigüedad. El modelo aplica el criterio mecánicamente.

Definir severidad con ejemplos

CRITICAL: Bloqueo en runtime para usuarios
  Ejemplo: NullPointerException al procesar pago

HIGH: Vulnerabilidad de seguridad
  Ejemplo: SQL injection, XSS, falta de permisos

MEDIUM: Error lógico sin efecto inmediato
  Ejemplo: Clasificación incorrecta, off-by-one

LOW: Calidad del código
  Ejemplo: Duplicación, algoritmo subóptimo

🔄3. Validación + retry-with-feedback

Cuando extraes datos estructurados, no basta con validar. Si falla, hay que retry inteligente que pase el contexto del error al modelo:

1. Extraer datos del documento
2. Validar (Pydantic, JSON Schema, reglas de negocio)
3. Si falla → retry con CONTEXTO del error:

   retry_prompt = f"""
   Documento original: {original_doc}

   Extracción anterior (incorrecta):
   {previous_extraction}

   Error específico:
   El campo 'total' = 150, pero la suma de
   'line_items' = 145. Verifica los valores.
   """

✓ Cuándo retry SÍ ayuda

• Errores de formato (fecha mal formada)
• Errores de estructura (campo mal colocado)
• Discrepancias aritméticas (puede reverificar)

❌ Cuándo retry NO ayuda

• Info ausente en la fuente (retry no la creará)
• Contexto externo no pasado al modelo
• Errores semánticos por fabricación pura

⚡ Pydantic — el patrón de validación

Pydantic es la librería estándar para validación en Python. Te da 4 cosas: 1) Validación de estructura (tipos, requeridos). 2) Validación semántica con validadores custom (suma items = total). 3) Ciclos de retry: al error, formas mensaje con el detalle y pides al modelo que corrija. 4) Auto-generación de JSON Schema para tool_use — única fuente de verdad para tu schema.

🪞4. Self-correction — detectar contradicciones internas

A veces el modelo extrae datos que se contradicen entre sí (el total declarado no coincide con la suma de items). Si pides solo el "total", no detectas el problema. Self-correction es un patrón donde Claude extrae ambos valores y marca el conflicto:

{
  "stated_total": "$150.00",
  "calculated_total": "$145.00",
  "conflict_detected": true,
  "line_items": [
    {"name": "Widget A", "price": 75.00},
    {"name": "Widget B", "price": 70.00}
  ]
}

⚡ Beneficio

El downstream sabe que hay un conflicto antes de procesar. Puede revisar manualmente, escalar al humano, o aplicar lógica de resolución específica. Mejor que ignorar y pasar datos inconsistentes al siguiente paso.

🔗5. Prompt chaining — dividir tareas complejas

Cuando una tarea tiene muchos pasos, mandar todo en un solo prompt diluye la atención del modelo. Prompt chaining divide en pasos secuenciales enfocados:

Paso 1: Analizar auth.ts (solo problemas locales)
       → Lista de issues en auth.ts

Paso 2: Analizar database.ts (solo problemas locales)
       → Lista de issues en database.ts

Paso 3: Pasada de integración (dependencias entre archivos)
       → Issues cross-archivo: tipos inconsistentes,
         dependencias cíclicas

⚡ Por qué funciona mejor que un solo prompt

• Evita dilución de atención: cuando das 14 archivos a la vez, el modelo analiza profundo unos y superficial otros
• Calidad consistente: cada archivo recibe el mismo nivel de análisis
• Separa análisis local de cross-archivo: problemas distintos requieren atención distinta

💬6. Conversaciones largas — los 5 problemas y sus soluciones

En conversaciones de muchos turnos surgen problemas específicos. Aquí los 5 patrones más importantes:

🔁 Drift de instrucciones

Síntoma: las primeras 10-15 respuestas siguen el system prompt, después se desvían. Causa: el ratio system prompt / assistant history disminuye con el tiempo. Solución: inyectar recordatorios en mensajes user cada 4-5 turnos. NO aumentar el system prompt.

✍️ Pre-fill del assistant

Síntoma: el assistant abre cada respuesta con "¡Claro!" o "Con gusto". Causa: patrones de generación aprendidos. Solución: prellenar el inicio de la respuesta del assistant con texto directo. Opera a nivel de GENERACIÓN, no de instrucciones. Es determinístico.

📥 Inyectar contexto en tiempo real

Necesitas inyectar info externa mientras el usuario chatea (ej. webhook avisa que el paquete fue enviado). Solución: prefijar la info al siguiente mensaje user. NO modificar system prompt (requiere reconstruir sesión).

❓ Manejo de ambigüedad

"¿Puedes ayudar con el informe?" — si haces 4 preguntas seguidas, 40% abandona. Solución: hacer suposiciones razonables, declararlas EXPLÍCITAMENTE, ofrecer ajustes. "Asumo que es el informe Q3 en PDF. Si es otro, dímelo."

⚖️ Contradicciones del usuario

"Riesgo MUY BAJO" + "MAXIMIZAR retornos" — son objetivos incompatibles. Solución: sacar la contradicción a la luz y pedir aclaración. NO usar la más reciente. NO recomendar algo neutral sin abordar el conflicto. NO hacer ambas recomendaciones por separado.

📦7. Message Batches API — procesamiento asincrónico

Para procesar volúmenes grandes (10,000 documentos) sin urgencia, la Batch API te da 50% de ahorro en costo:

Característica	Valor
Ahorro vs API sincrónica	50% del costo
Ventana de procesamiento	Hasta 24 horas (sin SLA de latencia)
Tool calling multi-turn	NO soportado (una request = una response)
Correlación	Campo `custom_id` por solicitud

Cuándo Batch vs Sincrónica

Caso	API	Por qué
Verificación pre-merge de PR	Sync	Dev espera resultado, 24h inaceptable
Reporte nocturno de deuda técnica	Batch	Listo en la mañana, ahorro 50%
Revisión de código interactiva	Sync	Necesita respuesta inmediata
Procesar 10,000 facturas	Batch	Procesamiento masivo, ahorro significativo

⚡ Manejo de fallos parciales

Si mandas un batch de 100 docs y 5 fallan (context limit exceeded), identifica los fallidos por custom_id, divide los documentos largos en fragmentos, y reenvía solo los 5 fallidos. No reproceses todo.

Tema 5 · Dominio 5 · 15%

Gestión de contexto y confiabilidad en producción

Cómo mantener información crítica intacta en conversaciones largas: case facts, scratchpads, trimming, delegación, provenance, escalada a humano y calibración de confianza.

📌1. "Case facts" — el bloque permanente

Cuando una conversación dura 30 turnos, la sumarización del historial pierde precisión: "$89.99" se vuelve "aproximadamente $90". Para casos de soporte donde los detalles importan, el patrón estándar es mantener un bloque estructurado de hechos clave que se incluye en CADA prompt:

=== CASE FACTS (actualizado en cada turno) ===
Customer ID: CUST-12345
Order ID: ORD-67890
Order Date: 2025-01-15
Order Amount: $89.99
Issue: Producto dañado en entrega
Customer Request: Devolución completa
Status: Esperando aprobación de gerente
===

⚡ Por qué funciona

Este bloque se inyecta en CADA prompt independientemente de cómo se haya resumido el historial conversacional. Mientras el historial puede decir "discutimos un pedido", el case facts mantiene el ID exacto, el monto exacto, la fecha exacta. Cero pérdida de precisión.

✂️2. Trimming de resultados de herramientas

Si lookup_order devuelve 40 campos pero solo necesitas 5 para la tarea actual, los 35 extra están desperdiciando ventana de contexto. Trimming con un hook PostToolUse soluciona esto:

@hook("PostToolUse", tool="lookup_order")
def trim_order_fields(result):
    return {
        "order_id": result["order_id"],
        "status": result["status"],
        "total": result["total"],
        "items": result["items"],
        "return_eligible": result["return_eligible"]
    }
    # 35 campos descartados antes de que Claude los vea

⚡ Trimming es determinístico, no probabilístico

Pedirle al modelo "ignora los campos irrelevantes" NO funciona porque los campos igual ocupan tokens en su contexto. El hook trim los elimina ANTES de que Claude los vea — ahorra contexto Y reduce ruido.

🎯3. Posicionamiento estratégico — el efecto "lost-in-the-middle"

Los modelos de lenguaje procesan el inicio y el final de un texto largo de forma confiable, pero pierden información del medio. Esto es bien documentado y aplica a Claude. Para reportes largos, organiza así:

[CONCLUSIONES CLAVE — al INICIO]
Se descubrieron 3 vulnerabilidades críticas...

[RESULTADOS DETALLADOS — en el medio]
=== Archivo auth.ts ===
...
=== Archivo database.ts ===
...

[INSTRUCCIONES DE ACCIÓN — al FINAL]
Prioridad: arreglar vulnerabilidades en auth.ts
antes del merge a producción.

⚡ Aplicación práctica

Si vas a darle a Claude 50 páginas de documentación, pon el resumen ejecutivo y los puntos críticos al inicio, los detalles al medio (donde menos se procesan), y las instrucciones de acción al final. NO pongas información crítica en el medio del documento.

📝4. Scratchpad files — memoria entre sesiones

Durante una investigación larga de una codebase, el agente puede ir guardando hallazgos en un archivo scratchpad. Cuando el contexto se degrada o empiezas una nueva sesión, el agente lee el scratchpad en lugar de re-investigar todo:

# investigation-scratchpad.md

## Hallazgos clave

- Clase PaymentProcessor en src/payments/processor.ts
  hereda de BaseProcessor
- Método refund() se llama desde 3 lugares:
  OrderController, AdminPanel, CronJob
- API externa PaymentGateway tiene rate limit
  de 100 req/min
- Migración #47 agregó campo refund_reason
  (NOT NULL) — fecha 2024-12-01

⚡ Diferencia con --resume

El scratchpad es independiente de la sesión: persiste como archivo en el repo. Si los archivos cambian, el agente lo actualiza. Si abres nueva sesión, lo lee. Si pasa una semana, sigue ahí. Más confiable que --resume con datos viejos.

📚5. Provenance — preservar el origen de la información

Cuando agregas información de múltiples fuentes (búsqueda web, análisis de docs, síntesis), se pierde la conexión "afirmación → fuente". Esto es problemático: si el reporte final dice "$3.2 mil millones", ¿de dónde viene? ¿De qué año? ¿Qué metodología?

❌ Sin atribución

"El mercado de AI en música se valúa
en $3.2 mil millones."

Imposible verificar, citar o cuestionar.

✓ Con provenance completo

{
  "claim": "$3.2B mercado AI música",
  "source_url": "https://...",
  "source_name": "AI Music Report 2024",
  "publication_date": "2024-06-15",
  "confidence": 0.9
}

Cada claim verificable, citable, datable.

Manejo de datos en conflicto

Si dos fuentes dan valores diferentes para el mismo dato, NO selecciones arbitrariamente:

{
  "claim": "% música AI en streaming",
  "values": [
    {
      "value": "12%",
      "source": "Spotify Annual Report 2024",
      "date": "2024-03",
      "methodology": "Auto-classification"
    },
    {
      "value": "8%",
      "source": "Music Industry Survey",
      "date": "2024-07",
      "methodology": "Encuesta a 500 sellos"
    }
  ],
  "conflict_detected": true,
  "possible_explanation": "Diferencia en metodología y período"
}

⚡ Sobre las fechas en provenance

Sin fechas, una diferencia temporal real se interpreta como contradicción. "Fuente A: 10%, Fuente B: 15%" parece contradicción. Con fechas: "Fuente A (2023): 10%, Fuente B (2024): 15%" se ve como crecimiento del 5% anual. Las fechas convierten contradicciones falsas en tendencias reales.

🚨6. Human-in-the-loop (HITL) — cuándo y cómo escalar

Algunos casos NUNCA deberían resolverse automáticamente. La pregunta es: ¿cómo detectarlos confiablemente? No todos los triggers son iguales.

Triggers CONFIABLES

Situación	Acción
Cliente dice explícitamente "dame un gerente"	Escalada INMEDIATA, sin intentar resolver
La política no cubre la solicitud	Escalar (ej. comparación de precios con competencia)
Agente no logra progreso tras intentos razonables	Escalar para evitar loops
Operación financiera sobre umbral	Vía hook, NO prompt
Múltiples coincidencias al buscar cliente	Pedir IDs adicionales, NO adivinar

⚠️ Triggers que parecen útiles pero NO funcionan

1) Análisis de sentimiento — el sentimiento del cliente NO correlaciona con complejidad del caso. Cliente enojado puede tener pregunta trivial.
2) Auto-evaluación de confianza del modelo (1-10) — el modelo está mal calibrado, tiene falsa confianza en decisiones equivocadas.
3) Clasificador automático — requiere datos de entrenamiento que tal vez no existan.

El handoff estructurado al humano

Cuando escalas, el operador humano NO tiene acceso al historial de conversación — solo ve el resumen JSON que tú generas. Debe ser completo y autosuficiente:

{
  "customer_id": "CUST-12345",
  "customer_name": "Juan Pérez",
  "issue_summary": "Devolución por producto dañado",
  "order_id": "ORD-67890",
  "root_cause": "Producto llegó dañado, fotos adjuntas",
  "actions_taken": [
    "Cliente verificado vía get_customer",
    "Pedido confirmado vía lookup_order",
    "Ofrecí reemplazo, cliente insiste en devolución"
  ],
  "refund_amount": "$89.99",
  "recommended_action": "Aprobar devolución completa",
  "escalation_reason": "Cliente solicitó hablar con gerente"
}

📊7. Calibración de confianza y muestreo estratificado

Para sistemas de extracción de datos en producción, necesitas saber cuándo confiar en el resultado y cuándo enviarlo a revisión humana. El patrón es routing por confianza:

1

El modelo emite un confidence score por campo extraído

2

Se calibran los umbrales usando un dataset de validación etiquetado

3

Alta confianza + precisión estable → procesamiento automático

4

Baja confianza o fuente ambigua → revisión humana

⚠️ Trampa: precisión agregada engaña

Tu sistema reporta 97% de precisión global. Suena bien. Pero ese 97% puede ocultar que en cierto tipo de documento tienes 40% de errores. Muestreo estratificado: analiza precisión POR tipo de documento y POR campo, no solo el agregado. Si no, las fallas críticas se esconden detrás del promedio.

⚡ Coverage annotations en síntesis final

Cuando algunos subagentes fallan (timeout, no encontró info), el reporte final debe anotar explícitamente qué secciones tienen cobertura completa y cuáles parcial. Ejemplo: "Música (COBERTURA PARCIAL — timeout). Cobertura limitada por timeout del agente de búsqueda." Esto preserva valor del trabajo Y mantiene honestidad.

Tema 6 · Referencia rápida

Glosario alfabético — términos clave

Definiciones cortas de los ~70 términos más importantes para el examen. Si quieres repasar rápido antes de un quiz, este es el lugar.

📖Glosario A–Z

Agent SDK

Framework oficial de Anthropic para construir agentes. Componentes: AgentDefinition, Sessions, Hooks, Subagentes via Task.

AgentDefinition

Objeto de configuración del agente: name, description, system_prompt, allowed_tools. Principio de privilegios mínimos.

allowed-tools (SKILL.md)

Frontmatter opcional que restringe las tools mientras el skill está activo. Ej: ["Read", "Grep"].

allowed_tools (AgentDefinition)

Lista de tools permitidas. Coordinador necesita "Task". Subagente especialista NO. Máximo 4-5 por agente.

"any" (tool_choice)

Fuerza a Claude a llamar UNA tool (la que sea). Para salida estructurada garantizada con múltiples tools.

"auto" (tool_choice)

Claude decide: usar tool o texto. Default.

Batch API

Procesamiento asincrónico. 50% ahorro, hasta 24h, sin tool calling multi-turn, custom_id para correlación.

Built-in agents

Explore, Plan, Verify. NO pueden usar skills.

Business error

Violación de política, límite excedido. NO retryable. Explicar al usuario.

Case facts

Bloque estructurado de hechos clave incluido en CADA prompt. Independiente de sumarización.

CLAUDE.md

3 niveles: usuario (~/.claude/, local), proyecto (.claude/, en VCS), directorio (subdirs).

Claude Code CLI

Modo no-interactivo con -p. Único correcto para CI/CD. Soporta --output-format json.

/compact

Comando que sumariza historial y libera contexto. Pierde valores numéricos exactos.

Confidence calibration

Field-level scores + datasets de validación + routing automático/humano por umbrales.

Context aislado (subagent)

Subagentes NO heredan historial del coordinador. Pasarlo explícito en el prompt del Task.

Coverage annotations

En reporte final, anotar secciones con cobertura completa vs parcial. Honestidad.

Custom subagent

Definido en .claude/agents/<name>.md. Único tipo que puede usar skills (si los lista en frontmatter).

custom_id

Campo en Batch API para vincular request/response. Permite reenviar solo los fallidos.

Drift de instrucciones

En convs largas, el modelo se desvía del system prompt. Solución: recordatorios cada 4-5 turnos.

end_turn

Único valor confiable de stop_reason que confirma terminación voluntaria del modelo.

Enterprise skills

Desplegados vía managed settings. Prioridad MÁS ALTA. Para compliance obligatorio.

errorCategory

Campo en errores MCP estructurados: transient / validation / business / permission.

Few-shot prompting

2-4 ejemplos input/output en el prompt. Más efectivo que descripciones textuales.

fork_session

Crea rama de sesión independiente desde un punto común. Para comparar enfoques.

Handoff estructurado

Resumen JSON al escalar a humano. Operador NO ve transcripción, solo el resumen.

Hooks (Agent SDK)

PreToolUse y PostToolUse. Determinístico 100% vs prompts probabilísticos.

Hooks vs Prompts

Hooks para reglas críticas (finanzas, legal, seguridad). Prompts para preferencias.

HITL

Human-in-the-loop. Patrón donde el agente escala decisiones críticas a humano.

Hub-and-spoke

Arquitectura multiagente: coordinador central + subagentes radiales. Toda comunicación vía coordinador.

isError: true

Bandera en respuesta de tool MCP indicando fallo. Debe acompañarse de errorCategory, isRetryable, message.

isRetryable

Bool en errores estructurados. Permite al coordinador decidir si reintentar.

JSON Schema

Define tool_use inputs. Required solo lo SIEMPRE disponible (sino fuerza fabricación). Nullable para opcionales.

Lost-in-the-middle

Los modelos pierden info del medio. Inicio y final tienen mejor retención.

max_tokens

Límite de tokens en respuesta. stop_reason="max_tokens" = truncada.

MCP

Model Context Protocol. 3 tipos: Tools (acciones), Resources (datos pasivos), Prompts (plantillas).

.mcp.json

Config MCP a nivel proyecto, en VCS. Usa ${VAR} para secretos (no plaintext).

/memory

Comando Claude Code que abre CLAUDE.md. Persiste entre sesiones.

Modo planificación (Plan Mode)

Claude investiga con Read/Grep/Glob, propone plan SIN hacer cambios.

paths (rules)

Campo YAML en .claude/rules/ con glob patterns. Carga condicional según archivo editado.

@path (CLAUDE.md)

Importación modular en CLAUDE.md. Max 5 niveles de imports anidados.

Permission error

Sin permisos de acceso. NO retryable. Escalar.

Personal skills

En ~/.claude/skills/. Solo tú, en todos tus proyectos. NO se comparten.

Plugin skills

Distribuidos vía marketplaces. Prioridad MÁS BAJA en la jerarquía.

PostToolUse hook

Intercepta resultado de tool ANTES de pasarlo al modelo. Útil para trimming y normalización.

PreToolUse hook

Intercepta llamadas a tool ANTES de ejecutar. Útil para bloquear acciones críticas.

Pre-fill del assistant

Prellenar inicio de respuesta. Previene saludos repetitivos a nivel de generación.

Priority hierarchy (skills)

Enterprise → Personal → Project → Plugins. Mismo nombre = Enterprise gana siempre.

Progressive disclosure

SKILL.md menor a 500 líneas. Recursos extra en scripts/, references/, assets/.

Project skills

En .claude/skills/ del repo. Compartidos vía git al clonar.

Prompt caching

Reutilización de prefijos. TTL de 5 min. Reduce costo/latencia.

Prompt chaining

Dividir tarea compleja en pasos secuenciales enfocados. Evita dilución de atención.

Provenance

Preservación del origen: claim + source URL + fecha + confianza. Necesario para datos en conflicto.

Pydantic

Validación de estructura y semántica. Ciclos de retry. Auto-gen de JSON Schema para tool_use.

--resume

Reanuda sesión nombrada. Riesgo: si archivos cambiaron, resultados pueden estar obsoletos.

Resources (MCP)

Datos pasivos accesibles para contexto. Diferente de Tools (que ejecutan acciones).

Retry-with-feedback

Reintentar con CONTEXTO del error específico. NO el mismo prompt idéntico.

Scratchpad files

Archivos con hallazgos clave en investigación larga. Persistente entre sesiones.

Self-correction

Patrón donde el modelo extrae valor declarado Y calculado + flag conflict_detected.

SKILL.md

Case-sensitive: mayúsculas "SKILL", minúsculas ".md". Exacto.

Skills

Folders con SKILL.md. Activan on-demand por semantic match. Al inicio solo cargan name + description.

stop_reason

end_turn (fin voluntario), tool_use, max_tokens, stop_sequence, pause_turn, refusal.

Subagente

NO hereda contexto del coordinador. Custom subagents pueden usar skills (si los listan). Built-in NO.

Sumarización progresiva

Pierde números, fechas, porcentajes al condensar historial. Solución: case facts.

System prompt

Campo "system" separado de messages. Prioridad sobre user. Cuidar asociaciones no intencionadas.

Task (tool)

Tool para generar subagentes. Coordinador debe incluirla en allowed_tools. Permite paralelización.

tool_choice

auto / any / tool (específica) / none. Control sobre tool calling.

Tool descriptions

Mecanismo PRINCIPAL de selección. Mínimas = poco confiable. Incluir formato, ejemplos, cuándo vs alternativas.

Transient error

Timeout, 503, fallo de red. Retryable con backoff exponencial.

Trimming

Hook PostToolUse que reduce campos de resultado de tool. Ahorra contexto y reduce ruido.

Validation error

Formato inválido, falta campo. NO retryable directo — cambiar input antes de retry.