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

​
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. El prompt del sistema predeterminado 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 experto revisor de código.

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 appendSystemPrompt

La opción appendSystemPrompt agrega tus instrucciones personalizadas al prompt del sistema predeterminado mientras preserva toda la funcionalidad incorporada. 
import { query } from "@anthropic-ai/claude-code"

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: {
    appendSystemPrompt: "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: Usando customSystemPrompt

La opción customSystemPrompt reemplaza todo el prompt del sistema predeterminado con tus instrucciones personalizadas. 
import { query } from "@anthropic-ai/claude-code"

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: {
    customSystemPrompt: customPrompt
  }
})) {
  messages.push(message)
  if (message.type === 'assistant') {
    console.log(message.message.content)
  }
}

​
Comparación de los tres enfoques

CaracterísticaEstilos de SalidaappendSystemPromptcustomSystemPrompt
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

​
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 appendSystemPrompt

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

​
Cuándo usar customSystemPrompt

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

​
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-code"

// 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: {
    appendSystemPrompt: `
      Para esta revisión, prioriza:
      - Cumplimiento OAuth 2.0
      - Seguridad de almacenamiento de tokens
      - Gestión de sesiones
    `
  }
})) {
  messages.push(message)
}

​
Ver también