Modificación de indicaciones del sistema

Elija entre el preset claude_code y una indicación del sistema personalizada, y personalice el comportamiento con CLAUDE.md, estilos de salida, append, o una indicación completamente personalizada.

Las indicaciones del sistema definen el comportamiento, las capacidades y el estilo de respuesta de Claude. Comience con el preset claude_code para herramientas de codificación tipo CLI o IDE donde un humano observa y dirige el trabajo. Escriba su propia indicación para agentes con una superficie, identidad o modelo de permisos diferente.

Cómo funcionan las indicaciones del sistema

Una indicación del sistema es el conjunto inicial de instrucciones que forma cómo se comporta Claude durante toda una conversación. El SDK del Agente tiene tres puntos de partida para ella:

• Predeterminado mínimo: cuando no establece systemPrompt en TypeScript o system_prompt en Python, el SDK utiliza una indicación mínima que cubre la invocación de herramientas pero omite el resto del contenido del preset claude_code, incluidas sus instrucciones de seguridad y protección y su contexto sobre el directorio de trabajo y el entorno. Esto difiere de claude -p, que utiliza la indicación del sistema de Claude Code de forma predeterminada. Si está migrando desde la CLI y desea un comportamiento coincidente, establezca el preset claude_code.
• Preset claude_code: la indicación del sistema que utiliza la CLI de Claude Code, con instrucciones de uso de herramientas, instrucciones de seguridad y protección, y contexto sobre el directorio de trabajo y el entorno. Establezca systemPrompt: { type: "preset", preset: "claude_code" } en TypeScript o system_prompt={"type": "preset", "preset": "claude_code"} en Python, opcionalmente con append para agregar sus propias instrucciones al final.
• Cadena personalizada: una indicación que usted escribe. El SDK envía solo lo que proporciona.

Decida sobre un punto de partida

El factor decisivo es cuán estrechamente su agente se asemeja a Claude Code: un agente de codificación que opera en un repositorio, con un humano observando la salida en streaming y dirigiendo el trabajo. Cuanto más se aleje su producto de eso, más querrá escribir su propia indicación.

"Diferente de Claude Code" generalmente significa uno de los siguientes:

• Superficie diferente: la salida no se lee en una terminal por la persona que la activó. Las interfaces de chat, los consumidores de salida estructurada y la automatización no codificadora cada una necesita una indicación que coincida con cómo se representa y revisa su salida. La automatización de codificación desatendida, como un trabajo de CI que corrige errores de lint o revisa diffs, aún se ajusta al preset porque el trabajo en sí es para lo que se escribió el preset.
• Identidad diferente: el agente no debe presentarse a sí mismo como Claude Code. Un bot de soporte, un asistente de análisis de datos, o cualquier agente específico del dominio necesita su propio nombre, alcance y persona.
• Modelo de permisos diferente: el agente se ejecuta de forma autónoma sin que un humano apruebe cada paso, u opera en un conjunto estrecho de recursos. La indicación de Claude Code asume que un humano está en el bucle con acceso a un conjunto completo de herramientas.
• Tareas no codificadoras: la mayoría de la indicación de Claude Code es orientación de codificación. Para agentes de investigación, contenido u operaciones, esa orientación compite con las instrucciones que realmente necesita.

La tabla de comparación muestra qué preserva cada método de personalización.

Personalizar el comportamiento del agente

append y una cadena de indicación personalizada cada uno cambian la indicación del sistema directamente, y un estilo de salida cambia las instrucciones que Claude Code da a Claude para cada respuesta. CLAUDE.md toma un camino diferente: el SDK lo lee e inyecta su contenido en la conversación como contexto del proyecto, por lo que forma el comportamiento junto con cualquier indicación del sistema que elija. Skills, hooks, y permissions también forman el comportamiento fuera de la indicación del sistema y se cubren en sus propias páginas.

Archivos CLAUDE.md para instrucciones a nivel de proyecto

Los archivos CLAUDE.md proporcionan a Claude contexto e instrucciones persistentes del proyecto. El SDK inyecta su contenido en la conversación y deja la indicación del sistema sin tocar, por lo que funcionan con cualquier configuración de indicación del sistema. Para saber qué poner en CLAUDE.md, dónde colocarlo y cómo escribir instrucciones efectivas, consulte Cuándo agregar a CLAUDE.md y el resto de Cómo Claude recuerda su proyecto. Esta sección cubre lo específico del SDK: cómo se carga CLAUDE.md.

El SDK lee CLAUDE.md cuando la fuente de configuración coincidente está habilitada: 'project' carga CLAUDE.md o .claude/CLAUDE.md desde el directorio de trabajo, y 'user' carga ~/.claude/CLAUDE.md. Las opciones predeterminadas de query() habilitan ambas fuentes, por lo que CLAUDE.md se carga automáticamente. Si establece settingSources en TypeScript o setting_sources en Python explícitamente, incluya las fuentes que necesita. La carga de CLAUDE.md se controla mediante fuentes de configuración, no por el preset claude_code.

Cargar CLAUDE.md con el SDK

Para cargar CLAUDE.md, establezca settingSources para incluir el nivel donde vive su CLAUDE.md. El ejemplo a continuación carga un CLAUDE.md a nivel de proyecto junto con el preset claude_code, por lo que Claude tiene tanto la indicación del agente de codificación como las convenciones de su proyecto:

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

const messages = [];

for await (const message of query({
prompt: "Add a new React component for user profiles",
options: {
systemPrompt: {
type: "preset",
preset: "claude_code" // Use Claude Code's system prompt
},
settingSources: ["project"] // Loads CLAUDE.md from project
}
})) {
messages.push(message);
}

// Now Claude has access to your project guidelines from CLAUDE.md

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

messages = []


async def main():
async for message in query(
prompt="Add a new React component for user profiles",
options=ClaudeAgentOptions(
system_prompt={
"type": "preset",
"preset": "claude_code",  # Use Claude Code's system prompt
},
setting_sources=["project"],  # Loads CLAUDE.md from project
),
):
messages.append(message)


asyncio.run(main())

# Now Claude has access to your project guidelines from CLAUDE.md

Cuando ejecuta cualquiera de los ejemplos, el SDK transmite mensajes mientras Claude trabaja: un mensaje de inicialización del sistema, mensajes del asistente, mensajes del usuario que llevan resultados de herramientas, y un mensaje de resultado final con el resultado de la sesión.

CLAUDE.md es persistente en todas las sesiones de un proyecto, se comparte con su equipo a través de git, y se descubre automáticamente sin cambios de código. No se carga si pasa un array settingSources vacío.

Estilos de salida para configuraciones persistentes

Los estilos de salida son configuraciones guardadas de instrucciones que cambian el rol, tono y formato de salida de Claude. Se almacenan como archivos markdown y se pueden reutilizar en sesiones y proyectos.

Crear un estilo de salida

Un estilo de salida es un archivo markdown con frontmatter para metadatos, seguido del contenido de la indicación. Guárdelo en ~/.claude/output-styles/ para un estilo a nivel de usuario disponible en cada proyecto, o .claude/output-styles/ en su repositorio para un estilo a nivel de proyecto que pueda confirmar y compartir con su equipo.

Un estilo de salida personalizado deja las instrucciones de ingeniería de software del preset claude_code fuera y usa las suyas propias. Para mantenerlas y superponer sus instrucciones encima, establezca keep-coding-instructions: true en el frontmatter. Esas instrucciones solo están en la indicación del sistema completa de Claude Code, por lo que la configuración no tiene efecto en una sesión en la indicación del sistema más corta, que activa o desactiva con CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT. Manténgalas cuando su agente aún esté realizando trabajo de ingeniería de software. Déjelas fuera cuando esté reemplazando el rol completamente.

El ejemplo a continuación define una persona de revisión de código que mantiene las instrucciones de codificación, ya que revisar código aún se beneficia de la orientación de seguridad y calidad de código de Claude Code. Guárdelo como ~/.claude/output-styles/code-reviewer.md para hacerlo disponible en todos los proyectos:

---
name: Code Reviewer
description: Thorough code review assistant
keep-coding-instructions: true
---

You are an expert code reviewer.

For every code submission:
1. Check for bugs and security issues
2. Evaluate performance
3. Suggest improvements
4. Rate code quality (1-10)

Activar un estilo de salida

Una vez creado, active los estilos de salida a través de:

• CLI: ejecute /config y seleccione un estilo de salida

• Configuración: establezca outputStyle en .claude/settings.local.json

• TypeScript SDK: establezca outputStyle dentro del objeto settings en línea pasado a query(), o apunte settings a un archivo de configuración que lo establezca. outputStyle no es un campo Options de nivel superior:

  const options = { settings: { outputStyle: "Explanatory" } };
  

El SDK de Python no tiene una opción para seleccionar un estilo de salida mediante programación. Para implementaciones solo de código donde no puede escribir en .claude/settings.local.json, use append o una cadena de indicación personalizada en su lugar.

Nota para usuarios del SDK: Los estilos de salida se cargan cuando incluye settingSources: ['user'] o settingSources: ['project'] (TypeScript) / setting_sources=["user"] o setting_sources=["project"] (Python) en sus opciones.

Agregar al preset `claude_code`

Puede usar el preset de Claude Code con una propiedad append para agregar sus instrucciones personalizadas mientras preserva toda la funcionalidad integrada.

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

const messages = [];

for await (const message of query({
prompt: "Help me write a Python function to calculate fibonacci numbers",
options: {
systemPrompt: {
type: "preset",
preset: "claude_code",
append: "Always include detailed docstrings and type hints in Python code."
}
}
})) {
messages.push(message);
if (message.type === "assistant") {
console.log(message.message.content);
}
}

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage

messages = []


async def main():
async for message in query(
prompt="Help me write a Python function to calculate fibonacci numbers",
options=ClaudeAgentOptions(
system_prompt={
"type": "preset",
"preset": "claude_code",
"append": "Always include detailed docstrings and type hints in Python code.",
}
),
):
messages.append(message)
if isinstance(message, AssistantMessage):
print(message.content)


asyncio.run(main())

Mejorar el almacenamiento en caché de indicaciones entre usuarios y máquinas

De forma predeterminada, dos sesiones que usan el mismo preset claude_code y texto append aún no pueden compartir una entrada de caché de indicación si se ejecutan desde diferentes directorios de trabajo. Esto se debe a que el preset incrusta contexto por sesión en la indicación del sistema antes de su texto append: el directorio de trabajo, si es un repositorio de git, la plataforma, el shell activo, la versión del SO, y rutas de memoria automática. Cualquier diferencia en ese contexto produce una indicación del sistema diferente y un error de caché. El contenido de CLAUDE.md no afecta el caché de indicación del sistema porque el SDK lo inyecta en la conversación, no en la indicación del sistema.

Para hacer que la indicación del sistema sea idéntica en todas las sesiones, establezca excludeDynamicSections: true en TypeScript o "exclude_dynamic_sections": True en Python. El contexto por sesión se mueve al primer mensaje del usuario, dejando solo el preset estático y su texto append en la indicación del sistema para que las configuraciones idénticas compartan una entrada de caché en usuarios y máquinas.

El siguiente ejemplo empareja un bloque append compartido con excludeDynamicSections para que una flota de agentes que se ejecutan desde diferentes directorios pueda reutilizar la misma indicación del sistema almacenada en caché:

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

for await (const message of query({
prompt: "Triage the open issues in this repo",
options: {
systemPrompt: {
type: "preset",
preset: "claude_code",
append: "You operate Acme's internal triage workflow. Label issues by component and severity.",
excludeDynamicSections: true
}
}
})) {
// ...
}

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
async for message in query(
prompt="Triage the open issues in this repo",
options=ClaudeAgentOptions(
system_prompt={
"type": "preset",
"preset": "claude_code",
"append": "You operate Acme's internal triage workflow. Label issues by component and severity.",
"exclude_dynamic_sections": True,
},
),
):
...


asyncio.run(main())

Compensaciones: el directorio de trabajo, la bandera de repositorio de git, la plataforma, el shell activo, la versión del SO, y rutas de memoria automática aún llegan a Claude, pero como parte del primer mensaje del usuario en lugar de la indicación del sistema. Las instrucciones en el mensaje del usuario tienen un peso marginalmente menor que el mismo texto en la indicación del sistema, por lo que Claude puede depender menos de ellas al razonar sobre el directorio actual o rutas de memoria automática. Habilite esta opción cuando la reutilización de caché entre sesiones sea más importante que el contexto de entorno máximamente autorizado.

Para la bandera equivalente en modo CLI no interactivo, consulte --exclude-dynamic-system-prompt-sections.

Indicaciones del sistema personalizadas

Puede proporcionar una cadena personalizada como systemPrompt para reemplazar completamente la predeterminada con sus propias instrucciones.

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

const customPrompt = `You are a Python coding specialist.
Follow these guidelines:
- Write clean, well-documented code
- Use type hints for all functions
- Include comprehensive docstrings
- Prefer functional programming patterns when appropriate
- Always explain your code choices`;

const messages = [];

for await (const message of query({
prompt: "Create a data processing pipeline",
options: {
systemPrompt: customPrompt
}
})) {
messages.push(message);
if (message.type === "assistant") {
console.log(message.message.content);
}
}

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage

custom_prompt = """You are a Python coding specialist.
Follow these guidelines:
- Write clean, well-documented code
- Use type hints for all functions
- Include comprehensive docstrings
- Prefer functional programming patterns when appropriate
- Always explain your code choices"""

messages = []


async def main():
async for message in query(
prompt="Create a data processing pipeline",
options=ClaudeAgentOptions(system_prompt=custom_prompt),
):
messages.append(message)
if isinstance(message, AssistantMessage):
print(message.content)


asyncio.run(main())

En Python, cargue una indicación personalizada grande desde un archivo con system_prompt={"type": "file", "path": "..."} en lugar de pasarla como una cadena. El SDK de Python pasa una indicación de cadena como un argumento de línea de comandos al subproceso CLI, por lo que una indicación que excede el límite de longitud de argumento del SO falla en el desove del proceso antes de que se envíe cualquier solicitud de API. En Linux el error es Argument list too long. Consulte SystemPromptFile para los umbrales de plataforma y el comportamiento de Windows.

Almacenar en caché la parte estática de una indicación personalizada

En el SDK de TypeScript, puede pasar una indicación personalizada como una matriz de cadenas en lugar de una cadena, con el marcador SYSTEM_PROMPT_DYNAMIC_BOUNDARY entre la parte estática y el resto. Úselo cuando su indicación combine instrucciones que son iguales en cada solicitud con contexto que cambia por solicitud, como el cliente o el ticket que maneja el agente. Cuando pasa ambas partes como una cadena, un cambio en la parte por solicitud cambia toda la indicación del sistema, por lo que las instrucciones estáticas pierden el caché también. Esta forma no está disponible en el SDK de Python, cuya opción system_prompt acepta una cadena, un preset, o un archivo.

Para dividir la indicación, importe SYSTEM_PROMPT_DYNAMIC_BOUNDARY desde @anthropic-ai/claude-agent-sdk y páselo como su propio elemento de matriz entre las dos partes. El SDK envía las cadenas antes del marcador como un bloque de texto y las cadenas después como un segundo bloque, cada uno con su propio punto de ruptura de caché. En el ejemplo a continuación, un agente de soporte carga sus instrucciones de triaje desde un archivo y recibe detalles sobre un ticket en cada solicitud, por lo que las instrucciones permanecen almacenadas en caché mientras los detalles del ticket cambian:

import { readFile } from "node:fs/promises";
import { query, SYSTEM_PROMPT_DYNAMIC_BOUNDARY } from "@anthropic-ai/claude-agent-sdk";

// Identical on every request
const instructions = await readFile("triage-instructions.md", "utf8");
// Different on every request
const ticketContext = "Customer plan: Enterprise. Other open tickets from this customer: 3.";

for await (const message of query({
  prompt: "Triage ticket 4821",
  options: {
    systemPrompt: [instructions, SYSTEM_PROMPT_DYNAMIC_BOUNDARY, ticketContext]
  }
})) {
  // ...
}

Rastrear tokens de caché describe los campos cache_creation_input_tokens y cache_read_input_tokens en cada mensaje de resultado.

El SDK ensambla los bloques de la matriz de la siguiente manera:

• El SDK une las cadenas en cada lado del marcador con una línea en blanco entre ellas y elimina el marcador en sí, por lo que el texto del marcador no llega a Claude.
• Si incluye el marcador más de una vez, el primero es la división y el SDK elimina los demás.
• Si deja el marcador fuera, el SDK une todas las cadenas en un bloque, igual que pasar una cadena.

Cambiar la indicación de una sesión existente

De forma predeterminada, Claude Code construye la indicación del sistema una vez, en la primera solicitud de una sesión, con su texto append o indicación personalizada incluida, y la registra en la sesión. Hasta que la sesión se compacte, cada solicitud posterior usa esa indicación registrada, incluso después de que regrese a la sesión con resume o continue. Si pasa un append o indicación personalizada diferente en esa llamada posterior, entra en vigor una vez que la sesión se compacta o en una nueva sesión.

Si inicia Claude Code en modo bare pasando --bare a través de extraArgs o estableciendo CLAUDE_CODE_SIMPLE=1, el registro se desactiva a menos que establezca snapshot: true en la forma de objeto de systemPrompt. El registro de un append o indicación personalizada de forma predeterminada requiere Claude Code v2.1.265 o posterior, que el SDK del Agente TypeScript agrupa desde v0.3.265. Antes de Claude Code v2.1.268, las sesiones que no obtienen banderas de características, incluyendo sesiones en Amazon Bedrock, Google Cloud's Agent Platform, y Microsoft Foundry, reconstruían la indicación en cada solicitud y snapshot no tenía efecto.

Para reconstruir la indicación en cada solicitud en su lugar, establezca snapshot: false en la forma de objeto de systemPrompt en el SDK de TypeScript: { type: "preset", preset: "claude_code", append, snapshot: false } o { type: "custom", prompt, snapshot: false }. Use esta forma mientras itera en la redacción de la indicación, o cuando su aplicación cambia append entre llamadas que reanudan la misma sesión. El campo snapshot requiere @anthropic-ai/claude-agent-sdk v0.3.257 o posterior.

Comparación de los cuatro enfoques

Los cuatro métodos de personalización difieren en dónde residen, cómo se comparten y qué preservan del preset claude_code.

"Con append" significa usar systemPrompt: { type: "preset", preset: "claude_code", append: "..." } en TypeScript o system_prompt={"type": "preset", "preset": "claude_code", "append": "..."} en Python. CLAUDE.md no cambia el prompt del sistema en sí: el SDK inyecta su contenido en la conversación como contexto del proyecto.

Combinar enfoques

Los enfoques se componen. Un estilo de salida persistente o CLAUDE.md establece el comportamiento de larga duración, y append superpone instrucciones específicas de la sesión sin tocar la configuración guardada.

Combinar un estilo de salida con adiciones específicas de la sesión

El ejemplo a continuación asume que un estilo de salida Code Reviewer ya está activo. El bloque append superpone áreas de enfoque específicas de la sesión sobre la persona, de modo que una única sesión de revisión puede priorizar OAuth y almacenamiento de tokens sin cambiar el estilo de salida guardado:

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

// Assuming "Code Reviewer" output style is active (via /config or settings)
// Add session-specific focus areas
const messages = [];

for await (const message of query({
prompt: "Review this authentication module",
options: {
systemPrompt: {
type: "preset",
preset: "claude_code",
append: `
For this review, prioritize:
- OAuth 2.0 compliance
- Token storage security
- Session management
`
}
}
})) {
messages.push(message);
}

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

# Assuming "Code Reviewer" output style is active (via /config or settings)
# Add session-specific focus areas
messages = []


async def main():
async for message in query(
prompt="Review this authentication module",
options=ClaudeAgentOptions(
system_prompt={
"type": "preset",
"preset": "claude_code",
"append": """
For this review, prioritize:
- OAuth 2.0 compliance
- Token storage security
- Session management
""",
}
),
):
messages.append(message)


asyncio.run(main())

Ver también

• Estilos de salida: crear, gestionar y compartir estilos de salida para la CLI, incluido el formato de archivo y las ubicaciones de almacenamiento
• Cómo Claude recuerda su proyecto: qué poner en CLAUDE.md, dónde colocarlo y cómo escribir instrucciones de proyecto efectivas
• Referencia del SDK de TypeScript: el tipo Options completo, incluidos systemPrompt, settingSources y settings
• Referencia del SDK de Python: el tipo ClaudeAgentOptions completo, incluidos system_prompt y setting_sources
• Configuración: la referencia de settings.json, incluido dónde se almacenan los estilos de salida y otras configuraciones