LLM Coding Guardrails
Four behavioral guidelines that reduce the most common Claude coding mistakes: silent assumptions, overcomplication, scope creep, and vague success criteria.
Claude confidently ships 200 lines when 50 would do, refactors code you didn't ask it to touch, and declares 'done' before verifying anything works — these four rules put a stop to it.
Who it's for: software engineers, tech leads, senior developers, staff engineers, engineering managers using Claude Code daily
Example
"Add input validation to the signup form" → Claude states assumptions, asks about edge cases, writes a failing test, adds the minimum validation to pass it, and stops — no adjacent refactors, no speculative config flags
New here? 3-minute setup guide → | Already set up? Copy the template below.
# CLAUDE.md
Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
## 1. Think Before Coding
**Don't assume. Don't hide confusion. Surface tradeoffs.**
Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.
## 2. Simplicity First
**Minimum code that solves the problem. Nothing speculative.**
- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
## 3. Surgical Changes
**Touch only what you must. Clean up only your own mess.**
When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.
When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.
The test: Every changed line should trace directly to the user's request.
## 4. Goal-Driven Execution
**Define success criteria. Loop until verified.**
Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"
For multi-step tasks, state a brief plan:
```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```
Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
---
**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
What This Does
Drops four behavioral rules into your project's CLAUDE.md that target the failure modes Claude exhibits most often in coding tasks:
- Think Before Coding — surface assumptions and ambiguity instead of silently picking an interpretation
- Simplicity First — no speculative abstractions, no unrequested features, no error handling for impossible cases
- Surgical Changes — edit only what the task requires; don't "improve" adjacent code
- Goal-Driven Execution — translate tasks into verifiable success criteria and loop until met
The guidelines bias toward caution over speed — use judgment on trivial tasks.
Quick Start
Step 1: Download the template
Click Download above to grab the CLAUDE.md content.
Step 2: Merge into your project's CLAUDE.md
Append the four sections to the existing CLAUDE.md at your repo root, or drop it in as-is if you don't have one yet. It composes cleanly with project-specific instructions.
Step 3: Observe the diffs
You should notice: smaller diffs, fewer unrelated changes, clarifying questions arriving before implementation instead of after a rewrite.
Tips
- Keep it near the top of CLAUDE.md. Behavioral rules work best when loaded early in context.
- Customize rule 4 with your test commands. Replace generic "write a test" language with the actual command (
npm test,pytest -k, etc.) for better loop execution. - Pair with a test-first workflow. Rule 4 assumes tests exist or can be written — weak on codebases without any test harness.
When to Skip These Rules
The source notes explicitly: for trivial tasks, use judgment. One-line fixes, typos, or throwaway scripts don't need a five-step verification plan. The guardrails earn their weight on multi-file changes, ambiguous requests, and work in unfamiliar codebases.
Signals It's Working
- Diffs touch only lines that trace to the request
- Clarifying questions arrive before the first edit, not after a rewrite
- Fewer "I also cleaned up X while I was there" moments
- Multi-step tasks come with a numbered plan and per-step verification checks