Skip to content

prompt-engineering.md

Latest commit

 

History

History
93 lines (79 loc) · 4.6 KB

prompt-engineering.md

File metadata and controls

93 lines (79 loc) · 4.6 KB

Prompt Engineering

Overview

Claude Code's system prompt is not a static string -- it's dynamically assembled from multiple sources with feature-gated sections, context injection, and runtime customization.

System Prompt Assembly

The system prompt is built in layers:

┌─────────────────────────────┐
│     Base Instructions       │  Core behavior, tool usage rules,
│     (systemPromptSections)  │  tone/style, safety guidelines
├─────────────────────────────┤
│     Tool Descriptions       │  Auto-generated from tool schemas
│                             │  (deferred tools show name only)
├─────────────────────────────┤
│     Context Sections        │  Git status, environment info,
│     (context.ts)            │  working directory, platform
├─────────────────────────────┤
│     Memory Prompt           │  Persistent memory from memdir/
│     (memdir.ts)             │  MEMORY.md index loaded
├─────────────────────────────┤
│     CLAUDE.md Content       │  Project-specific instructions
│     (claudemd.ts)           │  from .claude/ directories
├─────────────────────────────┤
│     Plugin/Skill Prompts    │  Skill descriptions, MCP server
│                             │  instructions, plugin commands
├─────────────────────────────┤
│     Feature-Gated Sections  │  Proactive mode, coordinator mode,
│     (bun:bundle flags)      │  voice mode, etc.
├─────────────────────────────┤
│     Output Style Config     │  Custom output formatting rules
│     (outputStyles)          │
└─────────────────────────────┘

Key Prompt Sections

System Prompt Sections Framework

  • Uses systemPromptSection() for cacheable sections (stable across turns)
  • Uses DANGEROUS_uncachedSystemPromptSection() for dynamic content (changes each turn)
  • resolveSystemPromptSections() assembles final prompt with cache-aware ordering
  • Cache-friendly sections placed first for API prompt caching benefits

Context Injection

  • Git context: Current branch, recent commits, dirty files, default branch
  • Environment: OS, shell, platform, model name, date
  • Working directories: Primary + additional directories
  • Non-interactive mode: Reduced context for headless/SDK usage

Memory System

  • Persistent memory stored in ~/.claude/projects/{project}/memory/
  • MEMORY.md index file loaded into every conversation
  • Individual memory files loaded on demand
  • Types: user, feedback, project, reference
  • Auto-extraction: System can suggest memories from conversation

CLAUDE.md Instructions

  • Project-specific instructions from .claude/CLAUDE.md files
  • Hierarchical: repo root -> subdirectory -> user-level
  • External includes supported (with user approval dialog)
  • Content cached and injected into system prompt

Feature-Gated Prompt Sections

Feature Flag Prompt Section
PROACTIVE Proactive mode instructions (initiative-taking behavior)
KAIROS Brief tool usage, push notification guidelines
COORDINATOR_MODE Multi-agent coordination instructions
CACHED_MICROCOMPACT Compact-aware caching config
EXPERIMENTAL_SKILL_SEARCH Skill discovery instructions

Cyber Risk Instruction

A dedicated section (cyberRiskInstruction.ts) provides safety guidelines:

  • Authorized security testing contexts only
  • Refuse destructive techniques, DoS, supply chain attacks
  • Dual-use tool guidance (C2 frameworks, credential testing)
  • Clear authorization context requirements

Undercover Mode

When working in sensitive repositories (internal Anthropic repos):

  • Prevents leaking internal model codenames in commits/PRs
  • Restricts certain information from appearing in tool outputs
  • Gated by repository detection in commitAttribution

Design Principles

  1. Cache-friendly ordering: Stable sections first for prompt caching
  2. Progressive disclosure: Deferred tool descriptions save tokens
  3. Context-aware: Git status, environment info keep model grounded
  4. Safety-first: Cyber risk instructions always included
  5. Extensible: Plugins, skills, and CLAUDE.md can all inject prompt content