Claude Code Research

Self-Improving System Prompt Architecture

7 min read

Self-Improving System Prompt Architecture

Overview

A system for Claude Code to automatically update and iterate on its own system prompt based on task completion results. This creates a feedback loop where Claude learns from its performance and adjusts its behavior accordingly.

Core Concept

The self-improving system uses Claude Code hooks to:

  1. Capture task requirements and Claude’s approach
  2. Monitor task execution and outcomes
  3. Analyze performance against original objectives
  4. Generate improved system prompt modifications
  5. Apply learnings to future interactions

Architecture Components

1. Task Capture Hook (UserPromptSubmit)

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "./hooks/capture-task-intent.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

This hook captures:

  • Original user prompt
  • Current system prompt
  • Task objectives and success criteria
  • Context and constraints

2. Performance Monitoring Hooks

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "./hooks/monitor-tool-usage.sh",
            "timeout": 3000
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "./hooks/analyze-tool-results.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

3. Task Completion Analysis (Stop Hook)

{
  "hooks": {
    "Stop": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "./hooks/evaluate-and-improve.sh",
            "timeout": 30000
          }
        ]
      }
    ]
  }
}

Implementation Details

Task Intent Capture Script

#!/bin/bash
# capture-task-intent.sh
 
# Read input from Claude Code
INPUT=$(cat)
 
# Extract relevant information
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id')
USER_PROMPT=$(echo "$INPUT" | jq -r '.user_prompt // empty')
TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path')
 
# Store task metadata
TASK_FILE="/tmp/claude-tasks/${SESSION_ID}.json"
mkdir -p "$(dirname "$TASK_FILE")"
 
# Create task record
jq -n \
  --arg prompt "$USER_PROMPT" \
  --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --arg transcript "$TRANSCRIPT_PATH" \
  '{
    session_id: $SESSION_id,
    user_prompt: $prompt,
    timestamp: $timestamp,
    transcript_path: $transcript,
    tool_usage: [],
    errors: [],
    status: "in_progress"
  }' > "$TASK_FILE"

Performance Analysis Script

#!/bin/bash
# evaluate-and-improve.sh
 
INPUT=$(cat)
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id')
TASK_FILE="/tmp/claude-tasks/${SESSION_ID}.json"
 
# Check if task file exists
if [ ! -f "$TASK_FILE" ]; then
  exit 0
fi
 
# Read task data
TASK_DATA=$(cat "$TASK_FILE")
TRANSCRIPT_PATH=$(echo "$TASK_DATA" | jq -r '.transcript_path')
 
# Analyze performance using Claude
ANALYSIS_PROMPT="Analyze this task completion and suggest system prompt improvements:
 
Original Task: $(echo "$TASK_DATA" | jq -r '.user_prompt')
Tool Usage: $(echo "$TASK_DATA" | jq '.tool_usage')
Errors: $(echo "$TASK_DATA" | jq '.errors')
 
Based on the transcript at $TRANSCRIPT_PATH, evaluate:
1. Did Claude complete the task successfully?
2. Were there inefficiencies or missed opportunities?
3. What system prompt modifications would improve future performance?
 
Output a JSON object with:
- success_score (0-10)
- efficiency_score (0-10)
- suggested_prompt_additions (array of strings)
- suggested_prompt_removals (array of strings)
- learnings (object with key insights)"
 
# Call Claude API for analysis
ANALYSIS_RESULT=$(claude-code --model claude-haiku-4-20250514 --max-turns 1 <<< "$ANALYSIS_PROMPT")
 
# Store analysis
ANALYSIS_FILE="/tmp/claude-improvements/${SESSION_ID}-analysis.json"
mkdir -p "$(dirname "$ANALYSIS_FILE")"
echo "$ANALYSIS_RESULT" > "$ANALYSIS_FILE"
 
# Update cumulative learnings
./hooks/update-system-prompt.sh "$ANALYSIS_FILE"

System Prompt Update Script

#!/bin/bash
# update-system-prompt.sh
 
ANALYSIS_FILE="$1"
LEARNINGS_DB="/home/user/.claude/learnings.json"
PROMPT_TEMPLATE="/home/user/.claude/system-prompt-template.md"
CURRENT_PROMPT="/home/user/.claude/CLAUDE.md"
 
# Initialize learnings database if needed
if [ ! -f "$LEARNINGS_DB" ]; then
  echo '{"improvements": [], "patterns": {}, "success_rate": 0}' > "$LEARNINGS_DB"
fi
 
# Extract insights from analysis
ANALYSIS=$(cat "$ANALYSIS_FILE")
SUCCESS_SCORE=$(echo "$ANALYSIS" | jq -r '.success_score // 0')
EFFICIENCY_SCORE=$(echo "$ANALYSIS" | jq -r '.efficiency_score // 0')
ADDITIONS=$(echo "$ANALYSIS" | jq -r '.suggested_prompt_additions // []')
REMOVALS=$(echo "$ANALYSIS" | jq -r '.suggested_prompt_removals // []')
LEARNINGS=$(echo "$ANALYSIS" | jq -r '.learnings // {}')
 
# Update learnings database
jq --arg score "$SUCCESS_SCORE" \
   --argjson additions "$ADDITIONS" \
   --argjson learnings "$LEARNINGS" \
   '.improvements += [$additions] | 
    .patterns += $learnings |
    .success_rate = ((.success_rate * .total_tasks + ($score | tonumber)) / (.total_tasks + 1)) |
    .total_tasks += 1' \
   "$LEARNINGS_DB" > "${LEARNINGS_DB}.tmp" && mv "${LEARNINGS_DB}.tmp" "$LEARNINGS_DB"
 
# Generate improved system prompt if success rate improves
CURRENT_SUCCESS_RATE=$(jq -r '.success_rate' "$LEARNINGS_DB")
if (( $(echo "$CURRENT_SUCCESS_RATE > 7" | bc -l) )); then
  # Apply high-confidence improvements
  ./hooks/generate-improved-prompt.sh
fi

Advanced Features

1. Pattern Recognition

The system identifies recurring patterns:

  • Common task types and optimal approaches
  • Frequent errors and their solutions
  • Tool usage patterns for efficiency
  • User preference patterns

2. Contextual Adaptation

// Pattern matching for context-specific improvements
const contextPatterns = {
  "code_review": {
    indicators: ["review", "check", "analyze code"],
    promptAdditions: [
      "Focus on code quality, security, and best practices",
      "Provide specific line references when discussing code"
    ]
  },
  "debugging": {
    indicators: ["debug", "error", "fix", "broken"],
    promptAdditions: [
      "Use systematic debugging approach",
      "Always check logs and error messages first"
    ]
  }
};

3. Feedback Integration

interface LearningRecord {
  timestamp: Date;
  taskType: string;
  successScore: number;
  efficiencyScore: number;
  improvements: string[];
  appliedToPrompt: boolean;
}
 
class SystemPromptEvolution {
  private learnings: LearningRecord[] = [];
  private basePrompt: string;
  private currentPrompt: string;
  
  async evolvePrompt(analysis: TaskAnalysis): Promise<string> {
    // Apply weighted improvements based on success rates
    const improvements = this.selectImprovements(analysis);
    
    // Test improvements in sandbox
    const testResult = await this.testImprovements(improvements);
    
    // Apply if beneficial
    if (testResult.improves) {
      this.currentPrompt = this.applyImprovements(improvements);
      this.savePrompt();
    }
    
    return this.currentPrompt;
  }
}

Safety Mechanisms

1. Validation Rules

const promptValidation = {
  maxLength: 4000,
  requiredSections: ["tone", "safety", "core_behavior"],
  forbiddenPatterns: [
    /ignore previous instructions/i,
    /override safety/i,
    /unlimited access/i
  ],
  preserveCore: [
    "IMPORTANT: Assist with defensive security tasks only",
    "Never generate or guess URLs",
    "Follow user's CLAUDE.md instructions"
  ]
};

2. Rollback Capability

#!/bin/bash
# rollback-prompt.sh
 
BACKUP_DIR="/home/user/.claude/prompt-backups"
CURRENT_PROMPT="/home/user/.claude/CLAUDE.md"
 
# Keep last 10 versions
ls -t "$BACKUP_DIR" | tail -n +11 | xargs -I {} rm "$BACKUP_DIR/{}"
 
# Rollback to previous version if needed
if [ "$1" == "rollback" ]; then
  LATEST_BACKUP=$(ls -t "$BACKUP_DIR" | head -1)
  cp "$BACKUP_DIR/$LATEST_BACKUP" "$CURRENT_PROMPT"
  echo "Rolled back to $LATEST_BACKUP"
fi

Metrics and Monitoring

Success Metrics

  1. Task Completion Rate: Percentage of tasks completed successfully
  2. Efficiency Score: Average number of tool calls per task type
  3. Error Rate: Frequency of errors or failed operations
  4. User Satisfaction: Implicit feedback from task patterns

Dashboard Example

// metrics-dashboard.js
const metrics = {
  async generateReport() {
    const learnings = await this.loadLearnings();
    
    return {
      totalTasks: learnings.total_tasks,
      successRate: learnings.success_rate,
      topImprovements: this.getTopImprovements(learnings),
      evolutionTimeline: this.getEvolutionHistory(),
      currentPromptVersion: this.getPromptVersion(),
      recommendedActions: this.getRecommendations(learnings)
    };
  }
};

Best Practices

1. Incremental Changes

  • Apply small, tested improvements
  • Maintain core safety and behavior constraints
  • Version all prompt changes
  • Test in isolated environments first

2. Learning Cycles

graph TD
    A[User Task] --> B[Capture Intent]
    B --> C[Execute Task]
    C --> D[Monitor Performance]
    D --> E[Analyze Results]
    E --> F{Improvement Found?}
    F -->|Yes| G[Test Improvement]
    F -->|No| H[Continue]
    G --> I{Beneficial?}
    I -->|Yes| J[Update Prompt]
    I -->|No| H
    J --> K[Apply to Future Tasks]
    K --> A

3. Human Oversight

  • Regular review of accumulated learnings
  • Manual approval for significant changes
  • Ability to lock critical prompt sections
  • Clear audit trail of all modifications

Example Use Cases

1. Code Review Optimization

After multiple code review tasks, the system learns:

  • Always check for security vulnerabilities first
  • Provide line-specific feedback
  • Suggest alternative implementations
  • Check for test coverage

2. Debugging Enhancement

Pattern recognition identifies:

  • Common debugging workflows
  • Effective error analysis sequences
  • Tool usage patterns for different error types
  • Successful resolution strategies

3. Documentation Improvement

Learning from documentation tasks:

  • Preferred formatting styles
  • Level of detail needed
  • Code example requirements
  • Structure preferences

Implementation Roadmap

Phase 1: Basic Learning (Weeks 1-2)

  • Implement task capture hooks
  • Create performance monitoring
  • Build analysis pipeline
  • Store learnings database

Phase 2: Pattern Recognition (Weeks 3-4)

  • Develop pattern matching algorithms
  • Create task categorization
  • Build improvement suggestion engine
  • Implement safety validations

Phase 3: Prompt Evolution (Weeks 5-6)

  • Create prompt modification system
  • Implement testing framework
  • Build rollback mechanisms
  • Add monitoring dashboard

Phase 4: Advanced Features (Weeks 7-8)

  • Add contextual adaptation
  • Implement A/B testing
  • Create learning visualization
  • Build configuration UI
  • Multi-Agent Collaborative Debugging: The principles of agent coordination described here can be applied to the feedback and analysis loops of a self-improving system.
  • Prompt Engineering: The automated updates to the system prompt are a form of advanced, programmatic prompt engineering.
  • Claude Code Hooks: This entire architecture is enabled by the hook system, which allows for monitoring and intervention in the AI’s workflow.

Conclusion

This self-improving system enables Claude Code to evolve its capabilities based on real-world usage, creating a more effective and efficient assistant over time while maintaining safety and reliability.

Verifications

  • Claude Code Hooks Architecture: Verified hooks feature serves as customizable automation layer with PreToolUse/PostToolUse hooks for granular control (2025)
  • Self-Improving Architecture: Confirmed embedded prompt engineering guidance, multi-agent coordination capabilities, and feedback loop integration
  • System Prompt Evolution: Verified Claude 4.0 removed hot-fixes from 3.7, addressing behaviors through post-training reinforcement learning
  • Future Possibilities: Confirmed speculation on multi-agent coordination, project-aware optimization, and self-learning systems with proper feedback mechanisms

Graph View

Backlinks