Quería un agente simple: monitorizar un directorio src/, detectar cambios en archivos .ts, ejecutar los tests afectados y reportar el resultado. Sin configurar watchers externos. Sin CI. Solo Claude haciendo el trabajo.
El prompt inicial fue así de directo:
claude "Monitoriza el directorio src/. Cuando detectes cambios en archivos .ts,
ejecuta los tests relacionados con npx jest y reporta el resultado con un resumen
de qué pasó y qué falló."Claude Code tiene acceso a Bash y Read tools de serie. Sabe ejecutar comandos y leer archivos. El agente funcionó en el primer intento — no porque el prompt fuera perfecto, sino porque la tarea encajaba con las herramientas disponibles.
El problema con el agente anterior es que pierde contexto entre sesiones. La solución es un CLAUDE.md en la raíz del proyecto — Claude Code lo lee automáticamente al iniciar.
# Proyecto: API de usuarios
## Stack
- TypeScript + Node.js
- Jest para tests
- PostgreSQL con Drizzle ORM
## Convenciones de tests
- Los tests viven en `src/__tests__/`
- Nombre del archivo: `[feature].test.ts`
- Ejecutar solo los tests del módulo afectado: `npx jest [filename]`
## Reglas del agente
- Si un test falla, busca primero el error en los logs antes de editar código
- No modifiques archivos fuera de `src/`Con este contexto persistente, el agente tiene las instrucciones necesarias para operar correctamente incluso en sesiones nuevas.
El agente tardó unos 3 minutos en configurarse y funcionó de forma fiable durante semanas. La clave no fue la complejidad del prompt sino la claridad: tarea concreta, herramientas conocidas, restricciones explícitas.
Lo que me sorprendió fue la capacidad de Claude para encadenar acciones: detectar el archivo cambiado → identificar qué tests ejecutar → correr los tests → parsear el output → reportar solo los fallos con contexto. Todo eso sin código adicional de mi parte.
Si tienes una tarea que se puede describir en lenguaje natural y ejecutar con comandos de terminal, probablemente puedas automatizarla con Claude Code en menos tiempo del que crees.
]]>CLAUDE.md no es documentación técnica del proyecto. Es un briefing para el agente. Incluye información que Claude necesita para operar bien pero que no puede inferir leyendo el código.
Sí incluir:
No incluir:
# Proyecto
[2-3 frases describiendo qué hace el proyecto y para quién]
## Stack
- Runtime: Node.js 20
- Framework: Next.js 14 App Router
- Base de datos: PostgreSQL vía Drizzle ORM
- Tests: Vitest + Testing Library
## Comandos
```bash
npm run dev # servidor desarrollo en :3000
npm run test # tests en modo watch
npm run test:ci # tests sin watch (para CI)
npm run db:push # sincronizar schema con BDuse@/ (alias configurado en tsconfig)any en TypeScript — usa unknown si necesitassrc/migrations/ — las migraciones se generan automáticamentesrc/lib/vendor/ es código de terceros, no tocarlo
## El error más común: instrucciones vagas
Las instrucciones vagas no ayudan. "Escribe código limpio" o "sigue las mejores prácticas" no le dice nada útil al agente. Sé específico sobre qué significa limpio en tu proyecto.
En lugar de:
Usa buenas prácticas de seguridad.
Escribe:
Validación de inputs: usa Zod en todos los endpoints de API. Nunca construyas queries SQL con concatenación de strings — usa siempre parámetros preparados. Las claves de API van en variables de entorno, nunca hardcodeadas.
## CLAUDE.md en subdirectorios
Claude Code lee todos los CLAUDE.md en la jerarquía de directorios. Puedes tener uno raíz con configuración global y archivos adicionales en subdirectorios para contexto específico:
proyecto/ ├── CLAUDE.md # config global ├── frontend/ │ └── CLAUDE.md # convenciones específicas del frontend └── backend/ └── CLAUDE.md # convenciones del backend
El agente combina todos los contextos relevantes según el directorio donde esté trabajando.
## Actualiza CLAUDE.md cuando el proyecto cambia
CLAUDE.md es un documento vivo. Si cambias el stack, añades una nueva convención o descubres que el agente hace algo que no quieres consistentemente, actualiza el archivo. Es más eficiente que corregirle en cada sesión.
Un CLAUDE.md bien mantenido es la diferencia entre un agente que necesita orientación constante y uno que opera bien desde el inicio.
cache_control. La mayoría de la gente que usa la API de Anthropic no la está usando. Esto es un error.
Cuando haces una llamada a Claude API, pagas por cada token que procesa el modelo — tanto los del prompt como los de la respuesta. Si tienes un system prompt de 2000 tokens que envías en cada request, estás pagando esos 2000 tokens cada vez.
El prompt caching cambia eso. Marcas partes del prompt como cacheables, y Anthropic las almacena en su infraestructura durante 5 minutos. Las peticiones posteriores que usen esa parte cacheada cuestan aproximadamente un 90% menos por ese segmento.
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
system=[
{
"type": "text",
"text": "Eres un asistente experto en código TypeScript...",
"cache_control": {"type": "ephemeral"}
}
],
messages=[{"role": "user", "content": "Explica los generics"}]
)El campo cache_control con type: "ephemeral" le dice a Anthropic: “cachea todo lo que va antes de este punto”.
El caching es más efectivo cuando tienes:
System prompts largos y estables. Un system prompt que define el comportamiento del agente, incluye documentación, o proporciona contexto extenso. Si tu system prompt tiene más de 500 tokens y no cambia entre requests, cachealo.
Documentos o código de referencia. Si estás haciendo Q&A sobre un documento, análisis de código, o cualquier tarea que requiera contexto fijo, ese contexto debería estar cacheado.
Conversaciones largas. Los mensajes anteriores de una conversación pueden cachearse para ahorrar en el re-procesamiento del historial.
El caching NO ayuda si tus prompts cambian constantemente o son cortos (menos de 1024 tokens para Sonnet — ese es el mínimo de tokens para que el cache tenga efecto).
En un proyecto donde usaba Claude para analizar código en un repo, tenía un system prompt de ~3000 tokens que incluía convenciones del proyecto. Sin cache: ~$0.18 por request (solo el system prompt). Con cache: $0.018 en el primer request, $0.003 en los siguientes.
Para 500 requests al día, eso pasa de $90/día a $1.50/día en el coste del system prompt. El ahorro se paga solo en horas.
El cache dura 5 minutos. Si hay un gap de más de 5 minutos entre requests que usen el mismo cache, el siguiente request pagará el precio completo y refrescará el cache. Esto importa si tienes workloads intermitentes.
Para verificar si el cache está funcionando, mira la respuesta de la API — el campo usage incluye cache_creation_input_tokens y cache_read_input_tokens. Si cache_read_input_tokens > 0, el cache está activo.
Implementarlo tarda menos de 10 minutos. No hay razón para no hacerlo.
]]>Un servidor MCP es un proceso que expone un conjunto de herramientas (tools) a través de un protocolo JSON-RPC. Claude Code se conecta a él en el arranque y puede invocar esas herramientas durante la sesión.
Los casos de uso más útiles: conectar Claude con tu base de datos, exponerle APIs internas, darle acceso a servicios que no tiene de serie (Slack, Jira, tu propio CMS).
mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk
npm install -D typescript @types/node ts-node{
"compilerOptions": {
"target": "ES2022",
"module": "CommonJS",
"outDir": "dist",
"strict": true
}
}import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
const server = new Server(
{ name: "my-tools", version: "1.0.0" },
{ capabilities: { tools: {} } }
);
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: "get_timestamp",
description: "Devuelve el timestamp actual en formato ISO",
inputSchema: { type: "object", properties: {}, required: [] },
},
],
}));
server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === "get_timestamp") {
return {
content: [{ type: "text", text: new Date().toISOString() }],
};
}
throw new Error(`Tool not found: ${request.params.name}`);
});
const transport = new StdioServerTransport();
await server.connect(transport);En tu .claude/settings.json:
{
"mcpServers": {
"my-tools": {
"command": "node",
"args": ["./dist/index.js"]
}
}
}Después de npx tsc && claude, Claude Code tiene acceso a tu herramienta get_timestamp. Desde ahí, puedes añadir las herramientas que necesites: queries a base de datos, llamadas a APIs, lectura de archivos de configuración.
El SDK de MCP maneja todo el protocolo. Tu trabajo es solo definir las herramientas y su lógica.
]]>Cuando activas extended thinking, Claude genera un bloque thinking antes del bloque text de la respuesta. Este bloque contiene el razonamiento interno: hipótesis, verificaciones, correcciones de errores. No es un adorno — es el proceso real que mejora la respuesta final.
El thinking consume tokens de salida pero Anthropic lo factura diferente: los tokens de thinking cuestan lo mismo que los de salida normales pero no cuentan para el límite de contexto de la misma forma.
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=16000,
thinking={
"type": "enabled",
"budget_tokens": 10000
},
messages=[{
"role": "user",
"content": "Diseña una arquitectura de microservicios para un e-commerce con 50k usuarios concurrentes."
}]
)
for block in response.content:
if block.type == "thinking":
print("RAZONAMIENTO:", block.thinking)
elif block.type == "text":
print("RESPUESTA:", block.text)El parámetro budget_tokens controla cuántos tokens puede usar el thinking. Más presupuesto = más razonamiento = mejor respuesta (con mayor coste y latencia).
Vale la pena activarlo para:
No hace falta para:
| Tarea | Budget sugerido |
|---|---|
| Análisis de código simple | 2.000 |
| Diseño de arquitectura | 8.000 |
| Problemas matemáticos difíciles | 10.000 |
| Análisis de sistemas complejos | 15.000+ |
El modelo para solo cuando ha llegado a una respuesta satisfactoria, no cuando agota el budget. Si ves que el thinking se corta antes de concluir, sube el budget.
Para producción, usa streaming para no bloquear mientras Claude piensa:
with client.messages.stream(
model="claude-sonnet-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 8000},
messages=[{"role": "user", "content": "..."}]
) as stream:
for event in stream:
if hasattr(event, 'type') and event.type == 'content_block_delta':
# Procesar thinking o text según block_index
passExtended thinking es una de las capacidades más infrautilizadas de Claude. Para los problemas donde la primera respuesta no basta, es el cambio que más impacto tiene en la calidad.
]]>Un solo agente con acceso a todas las herramientas y todo el contexto colapsa rápido. El contexto window se llena, las instrucciones se mezclan, y los errores se propagan sin control. La solución no es prompts más grandes, sino sistemas más pequeños bien coordinados.
El orchestrator recibe la tarea de alto nivel, la descompone y delega a workers especializados. Cada worker tiene un scope limitado y herramientas específicas.
Orchestrator: "Analiza este PR y escribe el reporte"
→ Worker A: revisa cambios de código (tools: Read, Bash/git)
→ Worker B: verifica tests (tools: Bash/npm test)
→ Worker C: redacta reporte (tools: Write)
El orchestrator recibe los outputs y los ensambla. Ningún worker necesita saber qué hacen los demás.
Para procesos donde cada paso depende del anterior. Los datos fluyen de agente en agente, cada uno transformando el output del anterior.
Este patrón es simple pero poderoso para procesos ETL, pipelines de contenido, o cualquier workflow donde el orden importa. El riesgo es que un error en un paso bloquea todo el pipeline — hay que diseñar los handoffs con validación explícita.
Cuando tienes tareas independientes que se pueden ejecutar a la vez. El orchestrator las lanza en paralelo y espera todos los resultados antes de continuar.
La implementación con la API de Claude es directa: múltiples llamadas asíncronas con asyncio.gather() en Python o Promise.all() en JS. El contexto de cada agente es independiente, así que no hay riesgo de interferencia.
Empieza con un agente. Cuando notes que el contexto window se llena o que el agente está mezclando preocupaciones distintas, es el momento de separar. Cada split debería tener una razón concreta — no abstracciones prematuras.
]]>“Eres un experto en X” es demasiado vago. El rol útil incluye contexto específico del dominio y las restricciones que aplican.
En lugar de: "Eres un experto en TypeScript", prueba: "Eres un senior engineer revisando código TypeScript para producción. El codebase usa Node.js 20, strict mode, y Drizzle ORM. Priorizas la seguridad sobre la brevedad." La diferencia en calidad de output es notable.
Si no dices cómo quieres el output, Claude elegirá. A veces elige bien; a menudo no. Especifica: tipo (lista, JSON, código, markdown), longitud aproximada, y qué incluir/excluir.
"Responde con un JSON array. Cada objeto tiene: { error: string, severity: 'low'|'medium'|'high', fix: string }. Sin explicaciones adicionales."
Para razonamiento complejo, pedir el proceso explícitamente mejora la calidad del resultado. "Piensa paso a paso antes de responder" activa un modo de razonamiento más cuidadoso. Es especialmente útil en debugging y análisis de código donde el primer impulso suele ser incorrecto.
Cuando el formato importa (y casi siempre importa), un ejemplo vale más que mil palabras de descripción. Muestra input → output esperado antes de dar la tarea real. Con dos o tres ejemplos, Claude replica el patrón con alta fidelidad.
“No hagas X” es tan importante como “haz Y”. Las restricciones negativas evitan comportamientos por defecto que no quieres: "No expliques el código que generes", "No uses comentarios", "No añadas error handling innecesario".
Sin restricciones explícitas, Claude tiende a ser “helpful” añadiendo cosas que no pediste. En un pipeline automatizado eso es ruido, no valor.
]]>Un hook es un comando shell que Claude Code ejecuta en respuesta a eventos del agente. Eventos disponibles:
PreToolUse — antes de que Claude use una herramientaPostToolUse — después de que Claude use una herramientaNotification — cuando Claude quiere notificarte algoStop — cuando Claude termina una tareaCasos de uso reales: ejecutar el linter después de cada edición, hacer un snapshot de git antes de cambios destructivos, bloquear ediciones en archivos protegidos, enviar notificaciones a Slack cuando el agente termina.
Los hooks se configuran en ~/.claude/settings.json (global) o .claude/settings.json (proyecto):
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "cd $CLAUDE_PROJECT_DIR && npx eslint --fix $CLAUDE_FILE_PATHS 2>/dev/null || true"
}
]
}
]
}
}El matcher es una regex que coincide con el nombre de la herramienta. Write|Edit captura ambas herramientas de edición.
Claude Code expone variables útiles en cada hook:
$CLAUDE_PROJECT_DIR — directorio raíz del proyecto$CLAUDE_FILE_PATHS — archivos afectados por la herramienta (separados por espacio)$CLAUDE_TOOL_NAME — nombre de la herramienta que se ejecutó$CLAUDE_SESSION_ID — ID de la sesión actualPuedes usar el exit code para bloquear acciones. Si el hook retorna exit code 2, Claude Code cancela la acción y muestra el stderr como mensaje de error:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "if echo \"$CLAUDE_FILE_PATHS\" | grep -q 'production.env\\|\\.secrets'; then echo 'Archivo protegido: edición bloqueada' >&2; exit 2; fi"
}
]
}
]
}
}Un pattern útil: hacer commit automático cuando Claude termina, para tener un historial granular de cada cambio del agente:
{
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "cd $CLAUDE_PROJECT_DIR && git diff --quiet || git add -A && git commit -m 'chore: claude agent checkpoint'"
}
]
}
]
}
}Los hooks convierten a Claude Code en un agente auditable y controlado. Con unos pocos comandos shell defines exactamente qué puede y no puede hacer en tu proyecto.
]]>El primer mes lo usé como un autocomplete potente. Pedía código, lo revisaba, lo ajustaba. Productividad razonable pero no espectacular.
El cambio llegó cuando empecé a trabajar con tareas, no con preguntas. En lugar de “escribe una función que haga X”, empecé a describir el objetivo completo: “implementa el endpoint /users/:id con validación de permisos, manejo de errores estándar, y tests”. La diferencia es sustancial — Claude puede mantener el contexto de una tarea completa mejor que de preguntas fragmentadas.
El archivo CLAUDE.md en la raíz del proyecto es lo más valioso que adopté. Incluye:
any en TypeScript”, “los errores van en formato { code, message }”)Sin esto, cada sesión empezaba desde cero. Con esto, Claude tiene el contexto necesario para tomar decisiones correctas sin preguntarme cada vez.
Los hooks de Claude Code (pre-tool, post-tool) permiten automatizar acciones alrededor de las herramientas. Lo uso para: loggear qué archivos modifica, ejecutar el linter automáticamente después de cada Write, y alertar si intenta modificar archivos fuera del scope permitido.
Esto convierte Claude Code de “agente que ejecuta lo que le pides” a “agente con guardarraíles automáticos”.
Después de tres meses, el límite principal no es la calidad de las respuestas — es el contexto window. En proyectos grandes, el contexto se llena y la calidad baja. La solución no es forzar más contexto, es trabajar en sesiones más cortas con tareas más específicas. Una sesión = una tarea bien definida.
]]>El flujo es un ciclo de 3 pasos:
tool_use block con los parámetrosimport anthropic
client = anthropic.Anthropic()
tools = [
{
"name": "get_weather",
"description": "Obtiene el tiempo actual para una ciudad",
"input_schema": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "Nombre de la ciudad"}
},
"required": ["city"]
}
}
]
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
tools=tools,
messages=[{"role": "user", "content": "¿Qué tiempo hace en Madrid?"}]
)Claude puede devolver tool_use en el stop_reason. Tienes que manejar este caso:
if response.stop_reason == "tool_use":
tool_block = next(b for b in response.content if b.type == "tool_use")
tool_name = tool_block.name
tool_input = tool_block.input
# Ejecuta tu función real aquí
result = call_your_function(tool_name, tool_input)
# Devuelve el resultado a Claude
final_response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
tools=tools,
messages=[
{"role": "user", "content": "¿Qué tiempo hace en Madrid?"},
{"role": "assistant", "content": response.content},
{"role": "user", "content": [
{"type": "tool_result", "tool_use_id": tool_block.id, "content": str(result)}
]}
]
)Puedes definir varias herramientas y Claude elegirá la apropiada. Con tool_choice puedes forzar el uso de una herramienta específica o desactivar la selección automática.
# Forzar una herramienta específica
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
tools=tools,
tool_choice={"type": "tool", "name": "get_weather"},
messages=[...]
)Tool use añade latencia y complejidad. Úsalo cuando necesites datos externos en tiempo real, ejecutar acciones con efectos secundarios, o cuando el resultado depende de información que no está en el contexto. Para razonamiento puro o generación de texto, un prompt directo es más rápido y barato.
]]>