Claude Config Self-Improvement

Analyze the current session for errors, mistakes, or inefficiencies and propose improvements to the .claude configuration to prevent similar issues in the future.

When to Use

•After a session with significant mistakes or rework
•When you notice patterns that could be prevented with better configuration
•When explicitly requested via /claude-improve-config
•Automatically triggered by the SessionEnd hook

Self-Reflection Process

1. Analyze the Session

Review the conversation for:

•Repeated mistakes: Same error made multiple times
•Misunderstandings: User had to correct Claude's interpretation
•Inefficient workflows: Better approaches discovered late in the session
•Tool misuse: Wrong tool for the job, excessive tool calls
•Missing context: Information that would have helped if in CLAUDE.md
•Ignored instructions: Existing CLAUDE.md rules that were violated

2. Categorize Issues

Rate severity:

•Critical: Caused significant rework or user frustration
•Moderate: Caused delays or minor corrections needed
•Minor: Slight inefficiency but didn't impact outcome

Only propose changes for critical or moderate issues.

3. Propose Configuration Changes

Changes can include:

CLAUDE.md Updates:

•New guardrails or constraints
•Clarified existing instructions
•Project-specific patterns to follow

New Hooks:

•PreToolUse hooks to prevent specific mistakes
•PostToolUse hooks to validate outputs
•Stop hooks to enforce checks before completion

New Skills:

•Reusable knowledge for recurring tasks
•Best practices for specific domains

4. Format the Proposal

Present proposals clearly:

markdown

## Session Reflection

### Issues Identified

1. **[Critical/Moderate]** Brief description of the issue
   - What happened: ...
   - Why it happened: ...
   - Impact: ...

### Proposed Changes

#### Change 1: [Type - CLAUDE.md/Hook/Skill]

**Rationale:** Why this change prevents the issue

**Implementation:**
[Show the exact changes to make]

#### Change 2: ...

Guidelines

•Only propose changes that are generalizable - don't add rules for one-off situations
•Keep CLAUDE.md concise - prefer hooks for enforcement over verbose instructions
•Test proposed hooks mentally - ensure they won't block legitimate workflows
•Prefer minimal changes - one well-designed rule is better than many narrow ones
•Consider false positives - hooks should not create friction for normal operations

Example Proposals

Example 1: Missing Test Verification

Issue: Claude claimed tests passed without running them.

Proposal: Add to CLAUDE.md:

markdown

**Test verification**: Never claim tests pass without showing actual test output. Always run `uv run pytest` with the specific test file before marking test-related tasks complete.

Example 2: Repeated Lint Failures

Issue: Code was submitted with lint errors multiple times.

Proposal: Add PostToolUse hook for Write/Edit:

json

{
  "matcher": "Write|Edit",
  "hooks": [
    {
      "type": "command",
      "command": "ruff check --select=E,F $TOOL_INPUT.file_path 2>/dev/null || true"
    }
  ]
}

Example 3: Wrong Branch for PR

Issue: PR was created against wrong base branch.

Proposal: Add to CLAUDE.md:

markdown

**Pull requests**: Always verify the target branch before creating a PR. For this project, PRs should target `main` unless explicitly specified otherwise.

Non-Examples (Do NOT Propose)

•One-off mistakes that won't recur
•User preference differences (not errors)
•Issues already covered by existing configuration
•Overly specific rules that won't generalize
•Changes that would slow down normal workflows significantly