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.

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

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

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

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)`
);

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.

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);
  }
}

Método 4: Indicaciones del sistema personalizadas

Puedes proporcionar una cadena personalizada como systemPrompt para reemplazar completamente la predeterminada con tus 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);
  }
}

Comparación de los cuatro enfoques

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

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);
}

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