# evolve-claude-md

> Analyze recent errors, PR feedback, and debugging sessions to suggest improvements to the project's CLAUDE.md. Claude is surprisingly good at writing rules for itself.

- Author: Matheus Kindrazki
- Repository: MatheusKindrazki/clauderc
- Version: 20260203134403
- Stars: 10
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/MatheusKindrazki/clauderc
- Web: https://mule.run/skillshub/@@MatheusKindrazki/clauderc~evolve-claude-md:20260203134403

---

# Evolve CLAUDE.md

Analyze recent errors, PR feedback, and debugging sessions to suggest improvements to the project's CLAUDE.md. Claude is surprisingly good at writing rules for itself.

## When to Use

- After fixing a bug that could have been prevented by better instructions
- After a PR review reveals missing conventions
- After a debugging session uncovers undocumented patterns
- Periodically (weekly/sprint) to refine project rules
- After onboarding a new team member who hit friction

## Workflow

### 1. Gather Context

Collect recent signals about what went wrong or could be improved:

```bash
# Recent commits (look for fix/refactor patterns)
git log --oneline -20 --grep="fix\|refactor\|revert"

# Recent PR comments (if using GitHub)
gh pr list --state merged --limit 5 --json number,title | head -20
```

### 2. Analyze Current CLAUDE.md

Read the existing CLAUDE.md and identify:
- Missing commands or outdated commands
- Missing conventions that caused recent bugs
- Missing architecture notes that led to wrong approaches
- Missing workflow guidance

### 3. Identify Improvement Categories

| Category | Signal | Example Rule to Add |
|----------|--------|---------------------|
| **Missing Convention** | Repeated style fixes in PRs | "Always use named exports" |
| **Undocumented Pattern** | Bug from wrong usage | "Use `trx` for DB transactions" |
| **Outdated Command** | Command fails or changed | Update test/build commands |
| **Missing Guard Rail** | Repeated mistake | "Never modify migration files" |
| **Architecture Gap** | Wrong file placement | "API routes go in `src/routes/`" |
| **Missing Context** | Wrong assumptions | "This is a multi-tenant app" |

### 4. Generate Suggestions

For each improvement, provide:

```markdown
## Suggested Addition: [Category]

**Signal:** [What happened that revealed this gap]

**Current CLAUDE.md:** [What it says now, or "missing"]

**Proposed Change:**
[Exact text to add/modify in CLAUDE.md]

**Rationale:** [Why this prevents future issues]
```

### 5. Apply Changes

After approval, update CLAUDE.md with the accepted suggestions.
Keep CLAUDE.md under 100 lines - use @imports for detailed docs.

## Rules

- NEVER remove existing rules without explicit approval
- ALWAYS explain WHY a rule is being added (cite the incident)
- PREFER specific rules over vague guidelines
- KEEP rules actionable - "do X" not "consider X"
- GROUP related rules under existing sections when possible
- USE @imports if CLAUDE.md exceeds 100 lines

## Examples

### Example 1: After a bug fix

**Signal:** Fixed a bug where API response wasn't validated

**Proposed Addition to CLAUDE.md:**
```markdown
## API Conventions
- Always validate API responses with zod schemas before using data
- Never trust external API response shapes - they can change
```

### Example 2: After PR feedback

**Signal:** PR reviewer noted inconsistent error handling

**Proposed Addition to CLAUDE.md:**
```markdown
## Error Handling
- Use `AppError` class for all application errors
- Always include error code, message, and context
- Log errors with structured logging (`logger.error({ err, context })`)
```

### Example 3: After debugging session

**Signal:** Spent 30 minutes debugging because test DB wasn't reset

**Proposed Addition to CLAUDE.md:**
```markdown
## Testing
- Run `npm run db:reset:test` before test suites
- Tests use isolated DB transactions (auto-rolled back)
```

## Checklist

- [ ] Reviewed recent git history for fix/refactor commits
- [ ] Checked recent PR comments for recurring feedback
- [ ] Identified gaps in current CLAUDE.md
- [ ] Generated specific, actionable suggestions
- [ ] Each suggestion cites the originating signal
- [ ] CLAUDE.md stays under 100 lines (use @imports if needed)
- [ ] No existing rules were removed without approval