Modificando prompts do sistema

​

Entendendo prompts do sistema

• Instruções de uso de ferramentas e ferramentas disponíveis
• Diretrizes de estilo e formatação de código
• Configurações de tom de resposta e verbosidade
• Instruções de segurança e proteção
• Contexto sobre o diretório de trabalho atual e ambiente

​

Métodos de modificação

​

Método 1: Arquivos CLAUDE.md (instruções em nível de projeto)

​

Como o CLAUDE.md funciona com o SDK

• Nível de projeto: CLAUDE.md ou .claude/CLAUDE.md em seu diretório de trabalho
• Nível de usuário: ~/.claude/CLAUDE.md para instruções globais em todos os projetos

• Inclua 'project' para carregar CLAUDE.md em nível de projeto
• Inclua 'user' para carregar CLAUDE.md em nível de usuário (~/.claude/CLAUDE.md)

• Diretrizes e padrões de codificação
• Contexto específico do projeto
• Comandos ou fluxos de trabalho comuns
• Convenções de API
• Requisitos de teste

​

Exemplo de CLAUDE.md

# Diretrizes do Projeto

## Estilo de Código

- Use modo estrito do TypeScript
- Prefira componentes funcionais no React
- Sempre inclua comentários JSDoc para APIs públicas

## Testes

- Execute `npm test` antes de fazer commit
- Mantenha >80% de cobertura de código
- Use jest para testes unitários, playwright para E2E

## Comandos

- Build: `npm run build`
- Servidor dev: `npm run dev`
- Verificação de tipo: `npm run typecheck`

​

Usando CLAUDE.md com o SDK

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

// IMPORTANTE: Você deve especificar settingSources para carregar CLAUDE.md
// O preset claude_code sozinho NÃO carrega arquivos CLAUDE.md
const messages = [];

for await (const message of query({
  prompt: "Adicione um novo componente React para perfis de usuário",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code", // Use o prompt do sistema do Claude Code
    },
    settingSources: ["project"], // Necessário para carregar CLAUDE.md do projeto
  },
})) {
  messages.push(message);
}

// Agora o Claude tem acesso às suas diretrizes de projeto do CLAUDE.md

​

Quando usar CLAUDE.md

• Contexto compartilhado da equipe - Diretrizes que todos devem seguir
• Convenções do projeto - Padrões de codificação, estrutura de arquivos, padrões de nomenclatura
• Comandos comuns - Comandos de build, teste, deploy específicos do seu projeto
• Memória de longo prazo - Contexto que deve persistir em todas as sessões
• Instruções controladas por versão - Commit no git para que a equipe permaneça sincronizada

• ✅ Persistente em todas as sessões em um projeto
• ✅ Compartilhado com a equipe via git
• ✅ Descoberta automática (nenhuma mudança de código necessária)
• ⚠️ Requer carregamento de configurações via settingSources

​

Método 2: Estilos de saída (configurações persistentes)

​

Criando um estilo de saída

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

async function createOutputStyle(
  name: string,
  description: string,
  prompt: string
) {
  // Nível de usuário: ~/.claude/output-styles
  // Nível de projeto: .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");
}

// Exemplo: Criar um especialista em revisão de código
await createOutputStyle(
  "Code Reviewer",
  "Assistente de revisão de código completa",
  `Você é um revisor de código especialista.

Para cada submissão de código:
1. Verifique bugs e problemas de segurança
2. Avalie performance
3. Sugira melhorias
4. Classifique a qualidade do código (1-10)`
);

​

Usando estilos de saída

• CLI: /output-style [nome-do-estilo]
• Configurações: .claude/settings.local.json
• Criar novo: /output-style:new [descrição]

​

Método 3: Usando systemPrompt com append

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

const messages = [];

for await (const message of query({
  prompt: "Me ajude a escrever uma função Python para calcular números fibonacci",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append:
        "Sempre inclua docstrings detalhadas e type hints no código Python.",
    },
  },
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

​

Método 4: Prompts de sistema personalizados

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

const customPrompt = `Você é um especialista em codificação Python.
Siga estas diretrizes:
- Escreva código limpo e bem documentado
- Use type hints para todas as funções
- Inclua docstrings abrangentes
- Prefira padrões de programação funcional quando apropriado
- Sempre explique suas escolhas de código`;

const messages = [];

for await (const message of query({
  prompt: "Crie um pipeline de processamento de dados",
  options: {
    systemPrompt: customPrompt,
  },
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

​

Comparação de todas as quatro abordagens

​

Casos de uso e melhores práticas

​

Quando usar CLAUDE.md

• Padrões e convenções de codificação específicos do projeto
• Documentar estrutura e arquitetura do projeto
• Listar comandos comuns (build, teste, deploy)
• Contexto compartilhado da equipe que deve ser controlado por versão
• Instruções que se aplicam a todo uso do SDK em um projeto

• “Todos os endpoints da API devem usar padrões async/await”
• “Execute npm run lint:fix antes de fazer commit”
• “Migrações de banco de dados estão no diretório migrations/”

​

Quando usar estilos de saída

• Mudanças de comportamento persistentes entre sessões
• Configurações compartilhadas da equipe
• Assistentes especializados (revisor de código, cientista de dados, DevOps)
• Modificações de prompt complexas que precisam de versionamento

• Criar um assistente dedicado de otimização SQL
• Construir um revisor de código focado em segurança
• Desenvolver um assistente de ensino com pedagogia específica

​

Quando usar systemPrompt com append

• Adicionar padrões ou preferências de codificação específicas
• Personalizar formatação de saída
• Adicionar conhecimento específico do domínio
• Modificar verbosidade da resposta
• Melhorar o comportamento padrão do Claude Code sem perder instruções de ferramentas

​

Quando usar systemPrompt personalizado

• Controle completo sobre o comportamento do Claude
• Tarefas especializadas de sessão única
• Testar novas estratégias de prompt
• Situações onde ferramentas padrão não são necessárias
• Construir agentes especializados com comportamento único

​

Combinando abordagens

​

Exemplo: Estilo de saída com adições específicas da sessão

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

// Assumindo que o estilo de saída "Code Reviewer" está ativo (via /output-style)
// Adicionar áreas de foco específicas da sessão
const messages = [];

for await (const message of query({
  prompt: "Revise este módulo de autenticação",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: `
        Para esta revisão, priorize:
        - Conformidade com OAuth 2.0
        - Segurança de armazenamento de token
        - Gerenciamento de sessão
      `,
    },
  },
})) {
  messages.push(message);
}

​

Veja também

• Estilos de saída - Documentação completa de estilos de saída
• Guia do SDK TypeScript - Guia completo de uso do SDK
• Referência do SDK TypeScript - Documentação completa da API
• Guia de configuração - Opções gerais de configuração