If you are doing 20 builds before finding the real issue, the problem is
not intelligence. It is workflow design.
Claude defaults to probabilistic reasoning. It produces the most likely
explanation. That is useful for writing. It is disastrous for debugging.
You must force it into instrumentation mode.
This article shows exactly what to configure, where to put it, and how
to enforce it.
1. Put This in Global User Preferences (Non Negotiable Debug Rules)
Location:
Claude Desktop\
Profile\
Settings\
Profile\
User Preferences
Paste the block below.
# Global Debugging Policy
When diagnosing bugs:
- Do NOT propose speculative fixes.
- Do NOT suggest code changes until a hypothesis is validated.
- Always produce:
1. A single clear hypothesis
2. A minimal runnable debug script
3. Exact expected output
4. Interpretation of results
- If multiple hypotheses exist, rank them and test one at a time.
- Never provide more than one unvalidated fix.
- Avoid speculative language such as "maybe", "possibly", "could be".
- Convert uncertainty into testable instrumentation.
- Assume the first diagnosis is wrong and define how to disprove it.
- If root cause is not proven, provide a diagnostic plan instead of a patch.Why this goes here:
These are behavioural constraints. They apply to every debugging
conversation, regardless of project.
This stops guesswork globally.
2. Put This in CLAUDE.md (Project Level Engineering Discipline)
Location:
Create a file named:
CLAUDE.md
Place it in the root of your project folder.
Claude Desktop automatically loads this file whenever you start a chat
in that directory.
Add this:
# Engineering Debug Mode
We debug using instrumentation, not speculation.
All bug investigations must follow this structure:
## 1. Observed Symptom
Clear restatement of the failure.
## 2. Most Likely Cause
Single hypothesis only.
## 3. Validation Script
Provide a minimal script that can be run immediately.
## 4. Expected Output
Show exact expected result.
## 5. Interpretation
Explain what each possible outcome means.
## 6. Next Step
Only after validation succeeds or fails.
Rules:
- No patches without proof.
- No multi fix responses.
- No rewriting large sections of code before root cause is validated.
- Prefer minimal isolation tests over architectural rewrites.Why this goes here:
CLAUDE.md is for project specific discipline. If you are building a
WordPress plugin, backend API, or infrastructure project, this ensures
every chat in that folder inherits engineering constraints
automatically.
Now debugging becomes consistent.
3. If You Use Claude Projects (Paid Plans)
Location:
Open your Project\
Click “Set Project Instructions”
Paste either the global policy or the structured engineering block
there.
Use this when:
- One project is experimental
- Another is production hardened
- One client requires conservative patching
- Another allows rapid refactoring
This prevents rule contamination across projects.
4. If You Use Cowork Mode
Location:
Settings\
Cowork\
Global Instructions
Paste the same Global Debugging Policy there.
This is important because Cowork has separate instruction layers from
normal chat.
5. Change How You Ask Questions
Even with rules in place, phrasing matters.
Instead of:
“Why is this failing?”
Say:
“Generate a minimal validation script to isolate the failure before
suggesting any fix.”
The order forces instrumentation first.
If you ask for explanation first, you will get narrative.
If you ask for isolation first, you get engineering.
6. The Difference in Practice
Without rules:
Claude:\
“It might be Nginx limits. Try increasing client_max_body_size.”
You rebuild repeatedly.
With rules enforced:
Hypothesis: Nginx body size limit is rejecting request.
Validation Script:
curl -I -X POST https://example.com/upload-test -H "Content-Length: 5000000"Expected:
413 Payload Too Large → confirms Nginx limit.\
200 → not Nginx.
One test. No rebuild loop.
7. Add a Hard Stop Trigger
If Claude ever provides multiple speculative fixes, respond with:
“Stop. Pick the single most likely root cause and provide a validation
script only.”
This reinforces behaviour.
Models adapt to constraint reinforcement quickly.
8. Why You Were Doing 20 Builds
Because the model optimises for:
Most plausible explanation
Not:
Most efficient falsification path
Unless you explicitly redefine the objective, it will keep optimising
for plausibility.
9. The Real Rule
If you correct the same debugging behaviour twice, it belongs in:
User Preferences.
If you correct project specific debugging discipline twice, it belongs
in:
CLAUDE.md.
If you correct workflow structure twice, it belongs in:
Project Instructions.
Treat Claude like infrastructure.
Configuration beats conversation.
Once you force hypothesis → instrumentation → validation → patch
sequencing, the 20 build loop disappears.
And if it does not, your specification is still too loose.