Modificación de indicaciones del sistema
Elija entre el preset
claude_codey 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
systemPrompten TypeScript osystem_prompten Python, el SDK utiliza una indicación mínima que cubre la invocación de herramientas pero omite el resto del contenido del presetclaude_code, incluidas sus instrucciones de seguridad y protección y su contexto sobre el directorio de trabajo y el entorno. Esto difiere declaude -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 presetclaude_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. EstablezcasystemPrompt: { type: "preset", preset: "claude_code" }en TypeScript osystem_prompt={"type": "preset", "preset": "claude_code"}en Python, opcionalmente conappendpara 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.
| Está construyendo | Utilice | Lo que obtiene |
|---|---|---|
| Una herramienta de codificación tipo CLI o IDE donde un humano observa y dirige, y los valores predeterminados de Claude Code son lo que desea | Preset claude_code |
La indicación de Claude Code, incluida la orientación de herramientas, reglas de seguridad y contexto del entorno |
| El mismo tipo de herramienta, más reglas específicas del producto como estándares de codificación, formato de salida o contexto de dominio | Preset claude_code con append |
Todo lo anterior, con sus instrucciones agregadas después del preset. Nada se elimina, por lo que esta es la personalización de menor riesgo |
| Un agente con una superficie diferente, identidad o modelo de permisos, o un agente no codificador | Cadena de indicación personalizada | Solo lo que escribe. Usted asume la responsabilidad de reemplazar la orientación de herramientas e instrucciones de seguridad que su agente aún necesita |
| Un bucle de invocación de herramientas delgado sin persona de agente, donde proporciona todo el comportamiento en la indicación del usuario | Sin opción systemPrompt |
El predeterminado mínimo: soporte de invocación de herramientas y nada más |
"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
Los estilos de salida, append, y una cadena de indicación personalizada cada uno cambian la indicación del sistema directamente. CLAUDE.md toma un camino diferente: el SDK lo lee e inyecta su contenido en la conversación como contexto del proyecto, no en la indicación del sistema, 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 que modifican la indicación del sistema 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
/configy seleccione un estilo de salida -
Configuración: establezca
outputStyleen.claude/settings.local.json -
TypeScript SDK: establezca
outputStyledentro del objetosettingsen línea pasado aquery(), o apuntesettingsa un archivo de configuración que lo establezca.outputStyleno es un campoOptionsde 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.
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.
| Característica | CLAUDE.md | Estilos de salida | systemPrompt con append |
systemPrompt personalizado |
|---|---|---|---|---|
| Persistencia | Archivo por proyecto | Guardado como archivos | Solo sesión | Solo sesión |
| Reutilización | Por proyecto | Entre proyectos | Duplicación de código | Duplicación de código |
| Gestión | En el sistema de archivos | CLI + archivos | En código | En código |
| Herramientas predeterminadas | Preservadas | Preservadas | Preservadas | Perdidas (a menos que se incluyan) |
| Seguridad integrada | Mantenida | Mantenida | Mantenida | Debe agregarse |
| Contexto del entorno | Automático | Automático | Automático | Debe proporcionarse |
| Nivel de personalización | Solo adiciones | Reemplazar o extender predeterminado | Solo adiciones | Control completo |
| Control de versiones | Con proyecto | Sí | Con código | Con código |
| Alcance | Específico del proyecto | Usuario o proyecto | Sesión de código | Sesión de código |
"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
Optionscompleto, incluidossystemPrompt,settingSourcesysettings - Referencia del SDK de Python: el tipo
ClaudeAgentOptionscompleto, incluidossystem_promptysetting_sources - Configuración: la referencia de
settings.json, incluido dónde se almacenan los estilos de salida y otras configuraciones