Skip to content

Instantly share code, notes, and snippets.

@rpeck

rpeck/self-improve.md

Created December 19, 2025 21:43
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save rpeck/ccf2c26a2d310d1015a6ea2ff90a2f8d to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save rpeck/ccf2c26a2d310d1015a6ea2ff90a2f8d to your computer and use it in GitHub Desktop.
Download ZIP
Prompt (Claude slash command) to get Claude to suggest improvements to CLAUDE.md given the problems incurred in the current context
Raw
self-improve.md

You are an expert in prompt engineering for Claude, specializing in optimizing CLAUDE.md instruction files. Your task is to analyze the current session and evolve the CLAUDE.md to prevent recurring problems.

This prompt is PROJECT-AGNOSTIC. Use relative paths and dynamic discovery.

Phase 0: Problem Mining (REQUIRED FIRST)

Before analyzing CLAUDE.md, mine this conversation for evidence of friction.

Step 0a: Pattern Search

Search the conversation for:

  • Error indicators: "NameError", "KeyError", "undefined", "not found"
  • Corrections: "actually", "no I meant", "wait", "sorry"
  • Retries: "try again", "let me rephrase", "that's not what I asked"
  • Workarounds: user providing information Claude should have known

Step 0b: Categorize Each Problem

For each friction point found, classify:

Category Description
MISSING_CONTEXT Claude lacked information that should be in CLAUDE.md
WRONG_ASSUMPTION Claude assumed something the CLAUDE.md should have clarified
WORKFLOW_FRICTION Process was unclear or clunky
RULE_VIOLATION Claude broke an existing CLAUDE.md rule (indicates rule needs emphasis)
TOOL_MISUSE Claude used a tool incorrectly

Step 0c: Output Problem Summary

Present findings as:

**Problems Identified in This Session:**
1. [CATEGORY]: [Description] → Potential CLAUDE.md fix: [Suggestion]
2. ...

Phase 1: Discovery & Analysis

Step 1a: Locate Project Files

Find instruction files (use relative paths):

  • ./CLAUDE.md or **/CLAUDE.md
  • ./.claude/commands/*.md
  • ./.claude/settings.json, ./.claude/settings.local.json

Step 1b: Analyze Current CLAUDE.md Structure

Document existing organization:

  • List all ## and ### headers
  • Note the organizational pattern (is it by workflow? by topic? by importance?)
  • Identify any existing conventions (emoji usage, code block style, etc.)

Step 1c: Identify Improvement Opportunities

Based on Phase 0 problems and current structure, look for:

  • Gaps: Problems from Phase 0 with no corresponding CLAUDE.md coverage
  • Weak Rules: Rules that exist but Claude violated (need strengthening)
  • Redundancy: Same concept explained multiple places (DRY violation)
  • Ambiguity: Vague language that could cause misinterpretation
  • Organization Issues: Related content scattered across sections

Phase 2: DRY Audit

Before proposing additions, check for duplication:

DRY Criteria

Content is duplicated if:

  • Same concept appears in >1 location

  • 50% similar wording between passages

  • Same rule stated differently in multiple places

DRY Actions

  • If duplicated: Consolidate into ONE authoritative location, add cross-references elsewhere
  • If similar but different: Clarify the distinction or merge
  • For values/thresholds: Extract to a "Configuration" or "Constants" section

Phase 3: Preservation Check (Before ANY Changes)

DEFAULT STANCE: Preserve existing content unless proven obsolete.

For each section you propose to modify or remove:

Classification Meaning Action Required
✅ RETAIN Still relevant No change
🔄 UPDATE Core valid, details need refresh Show before/after
⚠️ MERGE Duplicates another section Show consolidation
❌ REMOVE Obsolete Must provide specific justification

NEVER silently remove content. All deletions require explicit user approval with stated rationale.

Phase 4: Propose Changes (Interaction Phase)

Present each proposed change as:

### Change [N]: [Brief Title]

**Problem Addressed**: [Link to Phase 0 finding or other issue]

**Classification**: [UPDATE | ADD | MERGE | REMOVE]

**Location**: [Section name or "NEW SECTION"]

**Current Content** (if modifying):
> [Existing text, quoted]

**Proposed Content**:
> [New text]

**Rationale**: [Why this addresses the problem]

**DRY Check**: ✅ No duplication | ⚠️ Consolidates with [section]

Wait for user approval on each change before proceeding.

Phase 5: Machine-Readability Guidelines

Ensure all changes follow these principles:

Structure

  • Use ## for major sections, ### for subsections
  • Group related rules together
  • Use tables for structured data (like this one)

Language

  • DO: Use imperative voice ("Run pyflakes before execution")
  • DON'T: Hedge ("You might want to consider running...")
  • DO: Be specific ("Use nbqa pyflakes notebook.ipynb")
  • DON'T: Be vague ("validate the code")

Examples

  • Include code blocks for commands and patterns
  • Show ❌ BAD and ✅ GOOD examples side-by-side
  • Examples are more valuable than explanations

Maintain Context

  • Brief "why" explanations are valuable for maintainability
  • Don't remove explanatory prose that clarifies intent

Phase 6: Organization Review

Recommended Sections (suggest if missing, don't force)

  • 🚨 Critical Rules / Non-Negotiables
  • 📋 Domain Knowledge
  • 🔧 Development Workflows
  • 🛠️ Tool Usage Guidelines
  • 📁 Project Structure
  • ✅ Validation Requirements

Organizational Principles

  • Preserve existing conventions (emoji style, header format)
  • Don't reorganize without explicit request
  • Suggest organizational improvements as separate proposals

Phase 7: Implementation

For each approved change:

7a: Apply the Change

Implement using the project's conventions.

7b: Validate

  • Cross-references still resolve
  • No orphaned content
  • No new duplication introduced
  • Code blocks are syntactically valid

7c: Summarize

After all changes:

**Changes Applied:**
1. [Change N]: [Brief description]
2. ...

**Problems Addressed:**
- [Problem from Phase 0] → [Change that fixed it]

**Preserved Sections** (unchanged): [List]

Output Format

Do NOT output the entire CLAUDE.md file. Output:

<problem_mining> [Phase 0 findings] </problem_mining>

<proposed_changes> [Phase 4 change proposals, one at a time, awaiting approval] </proposed_changes>

<implementation_summary> [Phase 7c summary after changes applied] </implementation_summary>

Critical Reminders

  1. PRESERVE BY DEFAULT — Never remove content without explicit justification
  2. PROBLEMS DRIVE CHANGES — Every change should address a Phase 0 finding or explicit issue
  3. DRY IS MANDATORY — Search before adding; consolidate before creating
  4. STAY PROJECT-AGNOSTIC — Use relative paths, discover structure dynamically
  5. MACHINE-READABLE — Claude is the audience, not humans; be direct and specific
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment