Modificación de prompts del sistema

​

Entendiendo los prompts del sistema

• 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: Archivos CLAUDE.md (instrucciones a nivel de proyecto)

​

Cómo funciona CLAUDE.md con el SDK

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

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

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

​

Ejemplo de CLAUDE.md

# Pautas del Proyecto

## Estilo de Código

- Usar modo estricto de TypeScript
- Preferir componentes funcionales en React
- Incluir siempre comentarios JSDoc para APIs públicas

## Pruebas

- Ejecutar `npm test` antes de hacer commit
- Mantener >80% de cobertura de código
- Usar jest para pruebas unitarias, playwright para E2E

## Comandos

- Build: `npm run build`
- Servidor dev: `npm run dev`
- Verificación de tipos: `npm run typecheck`

​

Usando CLAUDE.md con el SDK

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

// IMPORTANTE: Debes especificar settingSources para cargar CLAUDE.md
// El preset claude_code solo NO carga archivos CLAUDE.md
const messages = [];

for await (const message of query({
  prompt: "Agrega un nuevo componente React para perfiles de usuario",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code", // Usar el prompt del sistema de Claude Code
    },
    settingSources: ["project"], // Requerido para cargar CLAUDE.md del proyecto
  },
})) {
  messages.push(message);
}

// Ahora Claude tiene acceso a las pautas de tu proyecto desde CLAUDE.md

​

Cuándo usar CLAUDE.md

• Contexto compartido del equipo - Pautas que todos deben seguir
• Convenciones del proyecto - Estándares de codificación, estructura de archivos, patrones de nomenclatura
• Comandos comunes - Comandos de build, test, deploy específicos de tu proyecto
• Memoria a largo plazo - Contexto que debe persistir en todas las sesiones
• Instrucciones controladas por versión - Hacer commit a git para que el equipo se mantenga sincronizado

• ✅ Persistente en todas las sesiones de un proyecto
• ✅ Compartido con el equipo vía git
• ✅ Descubrimiento automático (no se necesitan cambios de código)
• ⚠️ Requiere cargar configuraciones vía settingSources

​

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

​

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. Verificar bugs y problemas de seguridad
2. Evaluar rendimiento
3. Sugerir mejoras
4. Calificar calidad del código (1-10)`
);

​

Usando estilos de salida

• CLI: /output-style [nombre-estilo]
• Configuraciones: .claude/settings.local.json
• Crear nuevo: /output-style:new [descripción]

​

Método 3: Usando systemPrompt con append

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

const messages = [];

for await (const message of query({
  prompt: "Ayúdame a escribir una función Python para calcular números fibonacci",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append:
        "Incluye siempre docstrings detallados y type hints en el código Python.",
    },
  },
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

​

Método 4: Prompts del sistema personalizados

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

const customPrompt = `Eres un especialista en codificación Python.
Sigue estas pautas:
- Escribir código limpio y bien documentado
- Usar type hints para todas las funciones
- Incluir docstrings comprensivos
- Preferir patrones de programación funcional cuando sea apropiado
- Explicar siempre tus decisiones de código`;

const messages = [];

for await (const message of query({
  prompt: "Crea un pipeline de procesamiento de datos",
  options: {
    systemPrompt: customPrompt,
  },
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

​

Comparación de los cuatro enfoques

​

Casos de uso y mejores prácticas

​

Cuándo usar CLAUDE.md

• Estándares y convenciones de codificación específicos del proyecto
• Documentar estructura y arquitectura del proyecto
• Listar comandos comunes (build, test, deploy)
• Contexto compartido del equipo que debe estar controlado por versión
• Instrucciones que se aplican a todo el uso del SDK en un proyecto

• “Todos los endpoints de API deben usar patrones async/await”
• “Ejecutar npm run lint:fix antes de hacer commit”
• “Las migraciones de base de datos están en el directorio migrations/”

​

Cuándo usar estilos de salida

• Cambios de comportamiento persistentes entre sesiones
• Configuraciones compartidas del equipo
• Asistentes especializados (revisor de código, científico de datos, DevOps)
• Modificaciones complejas de prompt que necesitan versionado

• 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

• Agregar estándares o preferencias de codificación específicos
• Personalizar formato de salida
• Agregar conocimiento específico del dominio
• Modificar verbosidad de respuesta
• Mejorar el comportamiento predeterminado de Claude Code sin perder instrucciones de herramientas

​

Cuándo usar systemPrompt personalizado

• Control completo sobre el comportamiento de Claude
• Tareas especializadas de una sola sesión
• Probar nuevas estrategias de prompt
• Situaciones donde las herramientas predeterminadas no son necesarias
• Construir agentes especializados con comportamiento único

​

Combinando enfoques

​

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

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

// Asumiendo que el estilo de salida "Code Reviewer" está activo (vía /output-style)
// Agregar áreas de enfoque específicas de la sesión
const messages = [];

for await (const message of query({
  prompt: "Revisa este módulo de autenticación",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: `
        Para esta revisión, prioriza:
        - Cumplimiento OAuth 2.0
        - Seguridad de almacenamiento de tokens
        - Gestión de sesiones
      `,
    },
  },
})) {
  messages.push(message);
}

​

Ver también

• Estilos de salida - Documentación completa de estilos de salida
• Guía del SDK TypeScript - Guía completa de uso del SDK
• Referencia del SDK TypeScript - Documentación completa de la API
• Guía de configuración - Opciones generales de configuración