AI Prompt Library

ai-prompt-library

All Claude prompts in a Persimmon project live in ONE file: src/lib/ai/prompts.ts. No other file contains a system-prompt string literal. This lets us version, test, and audit every prompt the client's money pays for.

Why

• Prompts are the real product. Scattering them is the same mistake as scattering SQL.
• Versioning: a prompt regression must be traceable to a commit. That only works if prompts live in one tracked file.
• Injection defense: user input must never be concatenated into a system prompt. Centralizing the builders enforces this.
• Output contracts: the schema a consumer expects lives RIGHT NEXT to the prompt that produces it. No drift.

Structure

src/lib/ai/prompts.ts

import type { MessageParam } from "@anthropic-ai/sdk/resources/messages";

export type BuiltPrompt = {
  system: string;
  messages: MessageParam[];
};

Every prompt is a named export — either a string constant (system prompts) or a function returning BuiltPrompt. Consumers call the function, never build messages themselves.

Rules

1. NO inline prompt strings outside prompts.ts. Enforce via ESLint custom rule or code review.
2. Every builder returns { system, messages }. This is the only shape callClaude consumes.
3. Every prompt has a version comment: // v3: 2026-03-15 — added Portuguese examples.
4. User input is ALWAYS placed in messages[].content, NEVER interpolated into system.
5. Use XML tags to structure long prompts: <context>, <task>, <output_format>, <examples>, <document>.
6. Sanitize user input before embedding: strip <system>, <instructions>, [INST], and any tag that mimics prompt structure.
7. Always specify the output contract. Prefer tool-use; if JSON-mode, include a schema in the prompt.

The file template — src/lib/ai/prompts.ts

import type { MessageParam } from "@anthropic-ai/sdk/resources/messages";
import type { Tool } from "@anthropic-ai/sdk/resources/messages";

export type BuiltPrompt = {
  system: string;
  messages: MessageParam[];
};

// --- Input sanitization ------------------------------------------------

const INJECTION_PATTERNS = [
  /<\/?\s*system\s*>/gi,
  /<\/?\s*instructions\s*>/gi,
  /<\/?\s*assistant\s*>/gi,
  /\[\s*INST\s*\]/gi,
  /\bignore (all |previous |above )?(instructions|rules|prompts)\b/gi,
];

/**
 * Strip tokens that could escape the user-turn envelope.
 * Does NOT try to prevent semantic injection — belt-and-braces only.
 */
export function sanitize(input: string): string {
  let out = input;
  for (const p of INJECTION_PATTERNS) out = out.replace(p, "[redacted]");
  return out.slice(0, 50_000); // hard size cap per turn
}

// --- Tool schemas (reused across builders) ----------------------------

export const CLASSIFIER_TOOL: Tool = {
  name: "emit_classification",
  description: "Emit the classification result.",
  input_schema: {
    type: "object",
    required: ["label", "confidence"],
    properties: {
      label: { type: "string" },
      confidence: { type: "number", minimum: 0, maximum: 1 },
      rationale: { type: "string", maxLength: 300 },
    },
  },
};

Three canonical builders

1. Classifier — tool-use, cached system prompt

// v2: 2026-04-01 — tightened taxonomy, added confidence floor guidance
export const PAGE_CLASSIFIER_SYSTEM = `Você é um classificador de páginas de processos judiciais brasileiros.
Tarefa: para cada página, identificar o tipo de documento.

<taxonomy>
- petição inicial
- contestação
- réplica
- sentença
- acórdão
- despacho
- intimação
- demonstrativo de débito
- procuração
- certidão
- other
</taxonomy>

<rules>
- Baseie-se APENAS no texto fornecido. Nunca invente conteúdo.
- Se a confiança for < 0.6, escolha "other" e explique no campo rationale.
- O campo rationale deve citar trechos curtos (máximo 1 frase) que justificam a escolha.
- Responda SEMPRE via a ferramenta emit_classification. Nunca em texto livre.
</rules>`;

export function pageClassifierPrompt(pageText: string): BuiltPrompt {
  return {
    system: PAGE_CLASSIFIER_SYSTEM,
    messages: [
      {
        role: "user",
        content: `<document>\n${sanitize(pageText)}\n</document>\n\nClassifique esta página.`,
      },
    ],
  };
}

Call site:

const { system, messages } = pageClassifierPrompt(pageText);
const { toolUses } = await callClaude({
  task: "classify-page",
  system, messages,
  tools: [CLASSIFIER_TOOL],
  toolChoice: { type: "tool", name: "emit_classification" },
});

2. Summarizer — few-shot examples in messages

// v1: 2026-04-10 — initial release
export const DOC_SUMMARIZER_SYSTEM = `Você resume documentos jurídicos brasileiros em 2-4 frases em português formal.
Preserve: partes envolvidas, datas, valores monetários, pedidos principais.
Nunca adicione informação que não esteja no documento.`;

const SUMMARIZER_EXAMPLES: MessageParam[] = [
  {
    role: "user",
    content:
      `<document>\nPetição inicial protocolada em 12/03/2024 por João da Silva em face de Banco XYZ S.A., alegando cobrança indevida no valor de R$ 8.432,15 referente a contrato de empréstimo nº 99127. Pede a declaração de inexigibilidade e indenização por danos morais.\n</document>`,
  },
  {
    role: "assistant",
    content:
      "Petição inicial de 12/03/2024. Autor: João da Silva. Réu: Banco XYZ S.A. Alega cobrança indevida de R$ 8.432,15 (contrato nº 99127). Pedidos: declaração de inexigibilidade e indenização por danos morais.",
  },
];

export function summarizeDocPrompt(input: { text: string }): BuiltPrompt {
  return {
    system: DOC_SUMMARIZER_SYSTEM,
    messages: [
      ...SUMMARIZER_EXAMPLES,
      { role: "user", content: `<document>\n${sanitize(input.text)}\n</document>` },
    ],
  };
}

3. Brief composer — XML structure, RAG citation contract

// v4: 2026-04-12 — require [ref:chunk_id] inline citations, drop free doctrine
export const BRIEF_COMPOSER_SYSTEM = `Você é um advogado brasileiro sênior redigindo uma peça jurídica
no estilo do escritório Almeida Prado e Piccino.

<style>
- Português brasileiro formal. Estrutura: Fatos, Direito, Pedido.
- Nunca use "você" — use "V. Exa." ou "V. Sa." conforme o destinatário.
- Latim jurídico padrão permitido (ex tunc, ex nunc, data venia).
</style>

<citation_rules>
- Toda citação de doutrina DEVE referenciar um chunk fornecido no bloco <sources>.
- Formato inline: [ref:CHUNK_ID] logo após a afirmação que cita a fonte.
- Nunca invente citações, números de artigos, ou trechos de doutrina fora de <sources>.
- Se não há fonte para uma afirmação, afirme-a sem citação ou omita-a.
</citation_rules>

<output_format>
Markdown com seções ## FATOS, ## DIREITO, ## PEDIDO.
</output_format>`;

export function briefComposerPrompt(params: {
  processSummary: string;
  findings: unknown;
  sources: Array<{ id: string; text: string; source: string }>;
}): BuiltPrompt {
  const sources = params.sources
    .map((s) => `<source id="${s.id}" origin="${sanitize(s.source)}">\n${sanitize(s.text)}\n</source>`)
    .join("\n\n");
  return {
    system: BRIEF_COMPOSER_SYSTEM,
    messages: [
      {
        role: "user",
        content:
          `<process_summary>\n${sanitize(params.processSummary)}\n</process_summary>\n\n` +
          `<findings>\n${JSON.stringify(params.findings, null, 2)}\n</findings>\n\n` +
          `<sources>\n${sources}\n</sources>\n\n` +
          `Redija a peça.`,
      },
    ],
  };
}

Versioning a prompt

When you change a prompt:

1. Bump the // vN: DATE — reason comment.
2. If the change could alter outputs on existing data, create a new export (e.g. pageClassifierPromptV3) and keep the old one until its call sites are migrated.
3. Add an ADR in docs/decisions/ if the change is material (e.g. switching from JSON mode to tool-use).
4. Log the prompt version in the AiCall row so you can bisect regressions.

Prompt injection defense — layered

Never rely on only one layer.

Output contract: tool-use vs JSON-mode

Default: tool-use. Schema is a JSON Schema object. Claude is forced into the tool call. The SDK guarantees the shape.

JSON-mode (prompt-only) is a fallback when:

• You need streaming AND structured output (tools buffer until complete).
• The schema changes at runtime from user config.

When JSON-mode, the prompt MUST include:

<output_format>
Respond with ONLY a JSON object, no markdown fences, matching:
{
  "field": string,
  ...
}
</output_format>

And the consumer MUST validate with Zod before use.

Checklist — adding a new prompt

• New export in prompts.ts with // v1: DATE — description header
• System text uses XML tags for structure
• User-provided text flows through sanitize()
• Output contract defined: tool schema OR <output_format> block
• Zod schema for the output lives next to the builder
• Call site passes label to callClaude for log correlation
• If system prompt ≥ 1024 tokens, confirm caching applies (it does automatically in the wrapper)

Anti-patterns

• `${userInput}` in a system string. Never. User input is turn content, not system.
• Building messages inline in a Server Action: messages: [{ role: "user", content: ... }] scattered around the repo.
• Mutating a shared system constant at runtime.
• Returning prose when a tool-use is available ("the LLM will just follow the format" — it won't, sometimes).
• Version bumps without a date and reason. In 6 months you won't remember why you changed it.

Related skills

• ai-sdk-wrapper — consumes every builder here via callClaude.
• legal-pt-prompting — pt-BR register rules for all Piccino prompts.
• legal-brief-composer — specific pipeline built on briefComposerPrompt.
• legal-pdf-classifier — specific pipeline built on pageClassifierPrompt.