Los prompts del sistema definen el comportamiento, las capacidades y el estilo de respuesta de Claude. El Claude Agent SDK proporciona tres formas de personalizar los prompts del sistema: usando estilos de salida (configuraciones persistentes basadas en archivos), agregando al prompt de Claude Code, o usando un prompt completamente personalizado.

​
Entendiendo los prompts del sistema

Un prompt del sistema es el conjunto de instrucciones inicial que da forma a cómo se comporta Claude a lo largo de una conversación.
Comportamiento predeterminado: El Agent SDK usa un prompt del sistema vacío por defecto para máxima flexibilidad. Para usar el prompt del sistema de Claude Code (instrucciones de herramientas, pautas de código, etc.), especifica systemPrompt: { preset: "claude_code" } en TypeScript o system_prompt="claude_code" en Python.
El prompt del sistema de Claude Code incluye:
  • Instrucciones de uso de herramientas y herramientas disponibles
  • Pautas de estilo y formato de código
  • Configuraciones de tono de respuesta y verbosidad
  • Instrucciones de seguridad y protección
  • Contexto sobre el directorio de trabajo actual y el entorno

​
Métodos de modificación

​
Método 1: Estilos de salida (configuraciones persistentes)

Los estilos de salida son configuraciones guardadas que modifican el prompt del sistema de Claude. Se almacenan como archivos markdown y pueden reutilizarse a través de sesiones y proyectos.

​
Creando un estilo de salida

import { writeFile, mkdir } from 'fs/promises'
import { join } from 'path'
import { homedir } from 'os'

async function createOutputStyle(name: string, description: string, prompt: string) {
  // Nivel de usuario: ~/.claude/output-styles
  // Nivel de proyecto: .claude/output-styles
  const outputStylesDir = join(homedir(), '.claude', 'output-styles')
  
  await mkdir(outputStylesDir, { recursive: true })
  
  const content = `---
name: ${name}
description: ${description}
---

${prompt}`
  
  const filePath = join(outputStylesDir, `${name.toLowerCase().replace(/\s+/g, '-')}.md`)
  await writeFile(filePath, content, 'utf-8')
}

// Ejemplo: Crear un especialista en revisión de código
await createOutputStyle(
  'Code Reviewer',
  'Asistente exhaustivo de revisión de código',
  `Eres un revisor de código experto.

Para cada envío de código:
1. Verifica errores y problemas de seguridad
2. Evalúa el rendimiento
3. Sugiere mejoras
4. Califica la calidad del código (1-10)`
)

​
Usando estilos de salida

Una vez creados, activa los estilos de salida a través de:
  • CLI: /output-style [nombre-del-estilo]
  • Configuraciones: .claude/settings.local.json
  • Crear nuevo: /output-style:new [descripción]

​
Método 2: Usando systemPrompt con append

Puedes usar el preset de Claude Code con una propiedad append para agregar tus instrucciones personalizadas mientras preservas toda la funcionalidad incorporada. 
import { query } from "@anthropic-ai/claude-agent-sdk"

const messages = []

for await (const message of query({
  prompt: "Ayúdame a escribir una función de Python para calcular números de fibonacci",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: "Siempre incluye docstrings detallados y type hints en el código Python."
    }
  }
})) {
  messages.push(message)
  if (message.type === 'assistant') {
    console.log(message.message.content)
  }
}

​
Método 3: Prompts del sistema personalizados

Puedes proporcionar una cadena personalizada como systemPrompt para reemplazar completamente el predeterminado con tus propias instrucciones. 
import { query } from "@anthropic-ai/claude-agent-sdk"

const customPrompt = `Eres un especialista en codificación Python.
Sigue estas pautas:
- Escribe código limpio y bien documentado
- Usa type hints para todas las funciones
- Incluye docstrings comprensivos
- Prefiere patrones de programación funcional cuando sea apropiado
- Siempre explica tus decisiones de código`

const messages = []

for await (const message of query({
  prompt: "Crea un pipeline de procesamiento de datos",
  options: {
    systemPrompt: customPrompt
  }
})) {
  messages.push(message)
  if (message.type === 'assistant') {
    console.log(message.message.content)
  }
}

​
Comparación de los tres enfoques

CaracterísticaEstilos de SalidasystemPrompt con appendsystemPrompt Personalizado
Persistencia✅ Guardado como archivos❌ Solo sesión❌ Solo sesión
Reutilización✅ A través de proyectos❌ Duplicación de código❌ Duplicación de código
Gestión✅ CLI + archivos⚠️ En código⚠️ En código
Herramientas predeterminadas✅ Preservadas✅ Preservadas❌ Perdidas (a menos que se incluyan)
Seguridad incorporada✅ Mantenida✅ Mantenida❌ Debe agregarse
Contexto del entorno✅ Automático✅ Automático❌ Debe proporcionarse
Nivel de personalización⚠️ Reemplazar predeterminado⚠️ Solo adiciones✅ Control completo
Control de versiones✅ Sí✅ Con código✅ Con código
Descubrimiento✅ /output-style❌ No descubrible❌ No descubrible
Nota: “Con append” significa usar systemPrompt: { type: "preset", preset: "claude_code", append: "..." } en TypeScript o system_prompt={"type": "preset", "preset": "claude_code", "append": "..."} en Python.

​
Casos de uso y mejores prácticas

​
Cuándo usar estilos de salida

Mejor para:
  • Cambios de comportamiento persistentes a través de sesiones
  • Configuraciones compartidas en equipo
  • Asistentes especializados (revisor de código, científico de datos, DevOps)
  • Modificaciones complejas de prompts que necesitan versionado
Ejemplos:
  • Crear un asistente dedicado de optimización SQL
  • Construir un revisor de código enfocado en seguridad
  • Desarrollar un asistente de enseñanza con pedagogía específica

​
Cuándo usar systemPrompt con append

Mejor para:
  • Agregar estándares o preferencias específicas de codificación
  • Personalizar formato de salida
  • Agregar conocimiento específico del dominio
  • Modificar verbosidad de respuesta
  • Mejorar el comportamiento predeterminado de Claude Code sin perder instrucciones de herramientas

​
Cuándo usar systemPrompt personalizado

Mejor para:
  • Control completo sobre el comportamiento de Claude
  • Tareas especializadas de una sola sesión
  • Probar nuevas estrategias de prompts
  • Situaciones donde las herramientas predeterminadas no son necesarias
  • Construir agentes especializados con comportamiento único

​
Combinando enfoques

Puedes combinar estos métodos para máxima flexibilidad:

​
Ejemplo: Estilo de salida con adiciones específicas de sesión

import { query } from "@anthropic-ai/claude-agent-sdk"

// Asumiendo que el estilo de salida "Code Reviewer" está activo (vía /output-style)
// Agregar áreas de enfoque específicas de sesión
const messages = []

for await (const message of query({
  prompt: "Revisa este módulo de autenticación",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: `
        Para esta revisión, prioriza:
        - Cumplimiento OAuth 2.0
        - Seguridad de almacenamiento de tokens
        - Gestión de sesiones
      `
    }
  }
})) {
  messages.push(message)
}

​
Ver también