Overview
Claude Code fails in predictable ways. The failures are not random; they are patterns you can guard against by writing better briefs and configuring the right guardrails. Most problems trace back to under-specified scope, missing non-goals, or skipped verification. Read this page alongside claude-code and prompt-design; the patterns overlap.
Unscoped find-and-replace breaks unrelated files
The failure: Claude receives “rename Foo to Bar” and runs a regex over the entire repo, renaming identifiers in files the brief never mentioned.
The fix: always scope rename instructions to a file, directory, or explicit list.
# Bad
Rename the variable `apiUrl` to `endpointUrl`.
# Good
In src/config.ts only, rename the variable `apiUrl` to `endpointUrl`.
Do not modify any other file.
Add the scope constraint as a non-goal when the rename is in a shared utility: “Do not rename occurrences in test files.” Explicit scope eliminates the most common cause of unintended diffs.
Over-editing turns a one-line fix into a large diff
The failure: Claude opens a file to fix a bug on line 47 and also reformats the file, renames two other variables, and reorders the imports.
The fix: pin the change to the relevant lines and add explicit non-goals.
Fix the null check on line 47 of src/auth.ts.
Do not reformat the file.
Do not rename any variables.
Do not modify any line outside the affected function.
The diff before committing habit is the review step: before approving a commit, run git diff --staged and read every changed line. A diff that touches more than the brief described means the non-goals were under-specified. Reject the commit, tighten the brief, and re-run.
Helpful refactors land unreviewed changes
The failure: Claude notices an unrelated pattern that “could be improved” and refactors it while completing the stated task.
Helpful refactors are the hardest failure to catch because the refactor is often correct. The problem is that it is unreviewed, untested in isolation, and outside the scope of the brief.
The fix: name the off-limits areas explicitly.
## Non-goals
- Do not refactor the authentication module.
- Do not change any file not mentioned in this brief.
- Do not add or remove dependencies.
A non-goals section in every brief is not defensive writing; it is scope management. Claude respects explicit non-goals more reliably than implicit assumptions about what “small task” means.
Skipped verification produces a false green
The failure: Claude reports a phase complete without running the verification command. The build is broken, but the session ends with a success message.
The fix: require the verification output in the brief.
## Phase 2: update the schema
[steps...]
Verify: run `npm run build` and paste the last 10 lines of output.
Do not advance to Phase 3 until the build exits 0.
Asking for the output forces Claude to run the command and read the result. A brief that says “verify the build” without asking for the output invites the model to skip the step.
Inventing dependencies creates broken installs
The failure: Claude adds import { parse } from 'some-library' for a package not in package.json, or pins a version that conflicts with the current lockfile.
The fix: require a pre-flight dependency check before adding any new import.
Before adding any import, run `npm ls <package-name>`.
If the package is not installed, ask before proceeding.
Do not add packages that are not already in package.json.
For projects where the dependency manifest is strict, add “do not add or remove dependencies” to CLAUDE.md as a standing rule. See claude-code-claude-md for CLAUDE.md structure.
Drifting voice requires explicit re-pinning
The failure: a writing session starts in neutral playbook voice and drifts to marketing voice by the third section. Claude slides into slop constructions like “harness the power of” or “discover the magic of” language midway through a page.
The fix: voice rules belong in CLAUDE.md and in the brief, not just in one or the other.
## Voice (apply to all written content)
- Lead with the rule, then the rationale.
- No em-dashes.
- No slop preambles.
- No slop preamble constructions.Re-state the most critical rules at the end of the brief. Long prompts have recency bias; a rule on line 3 gets less weight than a rule on the last line. See prompt-design for the repetition rule.