Modificación de indicaciones del sistema

Las indicaciones del sistema definen el comportamiento, las capacidades y el estilo de respuesta de Claude. El Claude Agent SDK proporciona tres formas de personalizar las indicaciones del sistema: usando estilos de salida (configuraciones persistentes basadas en archivos), añadiendo a la indicación de Claude Code, o usando una indicación completamente personalizada.

Entendiendo 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.

Comportamiento predeterminado: El Agent SDK utiliza una indicación del sistema mínima por defecto. Contiene solo instrucciones esenciales de herramientas pero omite las directrices de codificación de Claude Code, el estilo de respuesta y el contexto del proyecto. Para incluir la indicación del sistema completa de Claude Code, especifica systemPrompt: { preset: "claude_code" } en TypeScript o system_prompt={"type": "preset", "preset": "claude_code"} en Python.

La indicación del sistema de Claude Code incluye:

Instrucciones de uso de herramientas y herramientas disponibles
Directrices de estilo de código y formato
Configuración 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: Archivos CLAUDE.md (instrucciones a nivel de proyecto)

Los archivos CLAUDE.md proporcionan contexto e instrucciones específicas del proyecto que son leídos automáticamente por el Agent SDK cuando se ejecuta en un directorio. Sirven como "memoria" persistente para tu proyecto.

Cómo funciona CLAUDE.md con el SDK

Ubicación y descubrimiento:

A nivel de proyecto: CLAUDE.md o .claude/CLAUDE.md en tu directorio de trabajo
A nivel de usuario: ~/.claude/CLAUDE.md para instrucciones globales en todos los proyectos

IMPORTANTE: El SDK solo lee archivos CLAUDE.md cuando configuras explícitamente settingSources (TypeScript) o setting_sources (Python):

Incluye 'project' para cargar CLAUDE.md a nivel de proyecto
Incluye 'user' para cargar CLAUDE.md a nivel de usuario (~/.claude/CLAUDE.md)

El preset de indicación del sistema claude_code NO carga automáticamente CLAUDE.md - también debes especificar fuentes de configuración.

Formato de contenido: Los archivos CLAUDE.md usan markdown plano y pueden contener:

Directrices de codificación y estándares
Contexto específico del proyecto
Comandos o flujos de trabajo comunes
Convenciones de API
Requisitos de pruebas

Ejemplo CLAUDE.md

# Project Guidelines

## Code Style

- Use TypeScript strict mode
- Prefer functional components in React
- Always include JSDoc comments for public APIs

## Testing

- Run `npm test` before committing
- Maintain >80% code coverage
- Use jest for unit tests, playwright for E2E

## Commands

- Build: `npm run build`
- Dev server: `npm run dev`
- Type check: `npm run typecheck`

Usando CLAUDE.md con el SDK

Cuándo usar CLAUDE.md

Mejor para:

Contexto compartido en equipo - Directrices que todos deben seguir
Convenciones del proyecto - Estándares de codificación, estructura de archivos, patrones de nomenclatura
Comandos comunes - Comandos de compilación, prueba e implementación específicos de tu proyecto
Memoria a largo plazo - Contexto que debe persistir en todas las sesiones
Instrucciones controladas por versión - Confirmar en git para que el equipo se mantenga sincronizado

Características clave:

✅ Persistente en todas las sesiones en un proyecto
✅ Compartido con el equipo a través de git
✅ Descubrimiento automático (no se necesian cambios de código)
⚠️ Requiere cargar configuración a través de settingSources

Método 2: Estilos de salida (configuraciones persistentes)

Los estilos de salida son configuraciones guardadas que modifican la indicación del sistema de Claude. Se almacenan como archivos markdown y pueden reutilizarse en sesiones y proyectos.

Creando un estilo de salida

Usando estilos de salida

Una vez creados, activa los estilos de salida a través de:

CLI: /output-style [style-name]
Configuración: .claude/settings.local.json
Crear nuevo: /output-style:new [description]

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

Método 3: Usando `systemPrompt` con append

Puedes usar el preset de Claude Code con una propiedad append para añadir tus instrucciones personalizadas mientras preservas toda la funcionalidad integrada.

Método 4: Indicaciones del sistema personalizadas

Puedes proporcionar una cadena personalizada como systemPrompt para reemplazar completamente la predeterminada con tus propias instrucciones.

Comparación de los cuatro enfoques

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)

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 CLAUDE.md

Mejor para:

Estándares de codificación y convenciones específicas del proyecto
Documentación de la estructura y arquitectura del proyecto
Listado de comandos comunes (compilación, prueba, implementación)
Contexto compartido en equipo que debe ser controlado por versión
Instrucciones que se aplican a todo el uso del SDK en un proyecto

Ejemplos:

"Todos los puntos finales de API deben usar patrones async/await"
"Ejecuta npm run lint:fix antes de confirmar"
"Las migraciones de base de datos están en el directorio migrations/"

Importante: Para cargar archivos CLAUDE.md, debes establecer explícitamente settingSources: ['project'] (TypeScript) o setting_sources=["project"] (Python). El preset de indicación del sistema claude_code NO carga automáticamente CLAUDE.md sin esta configuración.

Cuándo usar estilos de salida

Mejor para:

Cambios de comportamiento persistentes entre sesiones
Configuraciones compartidas en equipo
Asistentes especializados (revisor de código, científico de datos, DevOps)
Modificaciones de indicaciones complejas que necesitan control de versión

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:

Añadir estándares de codificación o preferencias específicas
Personalizar el formato de salida
Añadir conocimiento específico del dominio
Modificar la verbosidad de la 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
Prueba de nuevas estrategias de indicaciones
Situaciones donde las herramientas predeterminadas no son necesarias
Construcción de 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

Ver también

Estilos de salida - Documentación completa de estilos de salida
Guía del SDK de TypeScript - Guía completa de uso del SDK
Guía de configuración - Opciones de configuración general

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

// IMPORTANT: You must specify settingSources to load CLAUDE.md
// The claude_code preset alone does NOT load CLAUDE.md files
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"], // Required to load CLAUDE.md from project
  },
})) {
  messages.push(message);
}

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

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

async function createOutputStyle(
  name: string,
  description: string,
  prompt: string
) {
  // User-level: ~/.claude/output-styles
  // Project-level: .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");
}

// Example: Create a code review specialist
await createOutputStyle(
  "Code Reviewer",
  "Thorough code review assistant",
  `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)`
);

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 { 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 { query } from "@anthropic-ai/claude-agent-sdk";

// Assuming "Code Reviewer" output style is active (via /output-style)
// 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);
}

Entendiendo las indicaciones del sistema

Métodos de modificación

Método 1: Archivos CLAUDE.md (instrucciones a nivel de proyecto)

Cómo funciona CLAUDE.md con el SDK

Ejemplo CLAUDE.md

Usando CLAUDE.md con el SDK

Cuándo usar CLAUDE.md

Método 2: Estilos de salida (configuraciones persistentes)

Creando un estilo de salida

Usando estilos de salida

Método 3: Usando systemPrompt con append

Método 4: Indicaciones del sistema personalizadas

Comparación de los cuatro enfoques

Casos de uso y mejores prácticas

Cuándo usar CLAUDE.md

Cuándo usar estilos de salida

Cuándo usar systemPrompt con append

Cuándo usar systemPrompt personalizado

Combinando enfoques

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

Ver también

Método 3: Usando `systemPrompt` con append

Cuándo usar `systemPrompt` con append

Cuándo usar `systemPrompt` personalizado