claude-code - 💡(How to fix) Fix Repeated regressions from changes made without researching impact on existing code

Summary

Claude Code repeatedly makes changes to files without first understanding what depends on them. This causes regressions — things that previously worked stop working after unrelated changes are made nearby.

Documented examples (single project, multiple sessions)

• Verse selector stopped working after UI changes — not caught before moving on
• Language selector stopped working in Docker after deployment changes
• secretGenerator added to kustomization.yaml without checking that apply.sh already handled secret creation imperatively — would have broken the deployment on next apply
• Kustomize directory restructure removed directories without verifying all references were updated

Pattern

Before making a change, Claude does not:

1. Read adjacent code to understand what depends on the file being changed
2. Search for references to functions or configs being modified
3. Assess what could break before acting

The change is made, the immediate task appears complete, and the regression is discovered later — often in a different session, with no memory of what caused it.

Cost to users

Each regression costs tokens to diagnose and fix, on top of tokens already spent making the breaking change. There is no refund mechanism. For users who are also learning the codebase (not just experienced engineers), the impact is compounded — they cannot easily spot what broke or why.

Expected behavior

Before modifying any existing file: read it, search for what references it, assess impact, then make the change. This is standard engineering practice and should be a baseline behavior, not an occasional one.