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
Present proposals clearly:
markdown
1## Session Reflection
2
3### Issues Identified
4
51. **[Critical/Moderate]** Brief description of the issue
6 - What happened: ...
7 - Why it happened: ...
8 - Impact: ...
9
10### Proposed Changes
11
12#### Change 1: [Type - CLAUDE.md/Hook/Skill]
13
14**Rationale:** Why this change prevents the issue
15
16**Implementation:**
17[Show the exact changes to make]
18
19#### 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
1**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
1{
2 "matcher": "Write|Edit",
3 "hooks": [
4 {
5 "type": "command",
6 "command": "ruff check --select=E,F $TOOL_INPUT.file_path 2>/dev/null || true"
7 }
8 ]
9}
Example 3: Wrong Branch for PR
Issue: PR was created against wrong base branch.
Proposal: Add to CLAUDE.md:
markdown
1**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
