7 Claude Code Anti-Patterns: Distilled from a 520,000-Word Tutorial
This post distills stormzhang's ("Zhang Ge") AI Coding Guide — 92 articles and roughly 520,000 Chinese characters covering the full journey from installing Claude Code to using it expertly. The most valuable parts are the dedicated anti-patterns chapter and the decision trees for choosing features (Plan Mode, Subagents, /compact). GitHub: https://github.com/stormzhang/ai-coding-guide — Homepage: https://coding.stormzhang.ai
The 7 Anti-Patterns
1. Cramming many requests into one prompt
Example: "Switch login to OAuth, fix that error, adjust the homepage button style, and add tests." Claude works step by step (think → do → check); mixing four tasks means it guesses wrong direction, changes irrelevant code, and leaves the urgent task a hollow shell. Fix: one task at a time; for big changes, draft a plan in Plan Mode first, then implement.
2. Not writing CLAUDE.md — or stuffing everything into it
Two extremes: without CLAUDE.md you re-explain conventions every session; with 300 lines of API lists inside, it eats the context window and drowns the few rules that matter. The official self-check: for every line ask, *"Would deleting this cause Claude to make mistakes?"* If not, delete it.
| ✅ Include | ❌ Exclude | |---|---| | Bash commands Claude can't guess | Things readable from the code | | Code style deviating from defaults | Standard language conventions | | Test commands, preferred test runner | Detailed API docs (use links) | | Repo etiquette (branch naming, PR conventions) | Frequently changing info | | Project-specific architecture decisions | Platitudes like "write clean code" | | Environment quirks (required env vars) | File-by-file codebase descriptions |
Large knowledge (style guides, deployment checklists) → make a Skill loaded on demand.
3. Keeping one session open all day
Switching from OAuth work to "what's Python's GIL?" and back fills the context with noise; Claude gets worse at the real task. Fix: /clear when the task changes, /compact when sessions get long, don't bounce between chit-chat and coding.
4. Treating it as a search engine and believing everything
Claude will confidently fabricate answers — not maliciously, it just "thinks" that's how it should be. Without web access, it can't know an API is deprecated. Fix: give it web search tools; verify every output — run it, check official docs, confirm tests pass.
5. Not giving it a way to verify itself (the most emphasized point)
> "When work looks done, Claude stops. Without a check it can run, 'looks done' is the only signal available."
| Strategy | ❌ Before | ✅ After |
|---|---|---|
| Verification criteria | "Implement an email validator" | "Write validateEmail; tests: a@b.com true, invalid false; run tests after" |
| UI verification | "Make the dashboard look nicer" | "[attach mockup] Implement it, screenshot, diff against the mockup, fix differences" |
| Root cause | "The build fails" | "Here's the error: [paste]; fix it, verify the build succeeds, fix the root cause, don't suppress the error" |
This is the difference between sessions you babysit and sessions you can walk away from.
6. Running --dangerously-skip-permissions everywhere
Skipping all confirmations means prompt injection (via malicious code or web content) goes undefended. Fix: use acceptEdits or auto daily (auto-accept low-risk, confirm high-risk); run fully unrestricted only inside isolated containers/VMs — never on production machines.
7. Open-ended "investigate" tasks
"Investigate how this whole project is organized" → it reads 80+ files, blows the context window. Fix: narrow the scope ("look at routing under src/auth"), delegate exploration to a Subagent to keep the main window clean, or check README/CLAUDE.md first.
The vicious cycle
The seven mistakes feed each other: one mega-prompt (#1) + unbounded investigation (#7) → bloated context → Claude makes mistakes (#3) → you distrust it → you skip verification (#5) and go full auto (#6) → results get worse → "Claude Code isn't that good." Break the cycle at #1 (split requirements) and #5 (give verification).
Decision trees (quick reference)
- Mode: small task → say it directly; big task → Plan Mode first; don't know where to start → have Claude read key files or explore via Subagents.
- Session: task done →
/clear; 20+ turns →/compact; unrelated topic →/clearfirst. - Verification: has tests → make it run them; UI change → screenshot diff; bug fix → verify root cause resolved, not symptom suppressed.
- Permissions: production/work machine → never skip permissions; personal project →
autowith vigilance; isolated container → full auto acceptable. - Where knowledge lives: deleting it would cause errors + used every session → CLAUDE.md; scenario-specific → Skill; one-off → just say it in chat.
- stormzhang. "AI Coding Guide." GitHub: https://github.com/stormzhang/ai-coding-guide
- Homepage: https://coding.stormzhang.ai
- Anti-patterns article: https://coding.stormzhang.ai/claude-code/50-anti-patterns
- Related breakdown: https://zhichai.net/t/178208038
Quick-reference card
| Scenario | Don't | Do |
|---|---|---|
| Requests | Four tasks in one sentence | One thread at a time; Plan Mode for big changes |
| CLAUDE.md | Nothing, or 300 lines | One page; "would deleting this cause errors?" |
| Sessions | One session all day | /clear on task switch, /compact when long |
| Trust | Believe everything | Give web tools; verify all output |
| Verification | "Looks right" | Tests/builds/screenshot diffs — demand evidence |
| Permissions | Full bypass always | acceptEdits/auto; bypass only in containers |
| Exploration | "Investigate the whole project" | Narrow scope or use a Subagent |
Takeaway
When Claude Code frustrates you, the tool is usually fine — your usage has slipped into an anti-pattern. All seven mistakes "sound reasonable" (say everything at once, write detailed docs, keep one session open), but they invert under Claude Code's mechanics of context windows, verification, and injection risk. Knowing what not to do matters more than learning new features.
References: