Pitfalls & Boundaries

Beginner-Friendly Teaching Edition · Where AI coding has its limits

What you will learn
The earlier chapters covered what Claude Code can do. This one is about what it does poorly, where you will stumble, and how to avoid it: forgetting, confident wrongness, cost, "AI flavour", going off the rails, over-dependence, and a list of things it genuinely cannot do well. Everything here is from real experience, not theory.

ForgettingConfident wrongnessToken costAI flavourGoing off the railsDependenceNo silver bullet

The Big Idea

Claude Code is powerful, but it has real edges. Knowing exactly where its capabilities end is what lets you truly use the capabilities it has. The chapter's recommended mindset: treat it like an incredibly hardworking but occasionally careless junior engineer.

Easy way to remember:
Exceptional execution, limited big-picture vision. It types fast and never complains — but it makes basic mistakes that need checking, and it will not warn you that a direction is wrong. That judgment is yours.

Why This Topic Matters

Most beginner frustration comes from expecting the tool to do things it structurally cannot.
Some failures (outdated data, silent forgetting) are invisible unless you know to check.
Some failures (Agent Teams cost, MCP context bloat) cost real money.
The biggest risk is subtle: quietly losing your own judgment.

Pitfall 1 — "Forgetting": it really will forget what you said

What happened: during a long article, the author repeatedly told Claude "no em-dashes, no filler phrases." Claude complied for the first few rounds, then after about 40 minutes started using em-dashes freely again. The instructions had been swallowed by context compression.

This is not a fluke. The context window is 1M tokens, but long conversations trigger automatic compaction, and compaction is lossy. What you said early may survive only as a vague shadow by the end.

Lesson: important rules always go in CLAUDE.md — never rely on saying them in conversation. Conversation gets compressed; CLAUDE.md is re-read fresh every session. This is why the author turned all his writing rules into Skills rather than restating them.

Pitfall 2 — "Confident wrongness": it won't say it doesn't know

What happened: the author asked Claude Code for the latest pricing of an AI product. It gave numbers with complete confidence. He put them straight into an article. A reader then pointed out the pricing was three months out of date.

Claude does not say "I'm not sure." It gives a plausible-sounding answer from its training data even when that answer is already outdated. For AI tools specifically, three months is an entire product lifecycle.

Lesson: any content involving specific data, dates, pricing, or product features must be verified with WebSearch. Do not use something just because Claude said it confidently. The author now has this as rule number one under "Absolute Rules" in CLAUDE.md.

Pitfall 3 — "Token anxiety": it can get very expensive

Agent Teams is one of the most powerful features — and the most expensive. Each Teammate keeps its own context window, so token consumption is roughly 7× a normal session. Writing 6 chapters in parallel one afternoon cost around $50.

An overlooked cost: MCP servers. Every MCP server's tool definitions consume context. With 8 MCP servers running at once, the author found tool descriptions alone were eating 15% of his context — every conversation had 15% less usable space.

Lesson	Why
Use `/cost` and `/context` regularly	See consumption before it surprises you
Shut down MCP servers you are not using	Their tool definitions silently eat context
Break large tasks into smaller sessions	Cheaper and more stable than one massive session
Use Agent Teams only when you genuinely need parallelism	Not just to show off — it is ~7× the cost

Pitfall 4 — "AI flavour": the writing looks fake at a glance

The problem the author spent the most time solving. Claude's Chinese writing has recognisable tells (the same categories apply broadly to AI writing):

Em-dashes used constantly — normal writers rarely do this
Triplet parallelism: "It can XXX, it can YYY, it can ZZZ"
Hypothetical openings: "Imagine that…" or "If you've ever…"
Filler phrase clusters: "Simply put," "In other words," "To put it plainly"
Mandatory uplifting endings: "Let's embrace this future full of possibility together"

The first time the author published a Claude-written article directly, reader feedback was two words: AI vibes. It took several months to build a three-pass proofreading workflow that brings the AI-detection rate from above 60% down to below 30%. That workflow is now a Skill (/proofreading) every article must pass through.

Lesson: AI writing a first draft is fine — publishing it directly is not. Run it through at least one round of AI-flavour reduction. For human-reader content (not code), this step matters more than the draft itself.

Pitfall 5 — "Going off the rails": it wanders if you're not watching

Give Claude Code a vague request and it will "improvise." What happened:

"Clean up the styling on this page" (meaning a few spacing/font tweaks) → it refactored the entire CSS file, overwrote a carefully tuned layout, and added a pile of "improvements." Half an hour to roll back.
"Fix a small bug" → it fixed the bug and also "took the opportunity" to refactor the surrounding code, introducing two new bugs.

Lesson	In practice
Be specific	"Change the heading font size from 16px to 18px" beats "clean up the heading" by a hundred times
Give clear stopping conditions	"Stop when tests pass," "only touch this one file"
Use Plan mode for complex changes	Discuss the approach first, then execute once confirmed
Git is your safety net	Always have a clean commit to roll back to before any major change

Pitfall 6 — "Dependency": you may lose your own judgment

More subtle than the others. After six months, the author noticed he was accepting Claude's proposals without thinking — it says approach A, he uses approach A — because most of the time the suggestions were right, so he got lazy about asking "why A and not B?"

Then Claude recommended a tech stack he knew nothing about. He built it out and found the performance was terrible — after two days of work. Ten minutes of thinking through the technical choices at the start would have avoided the whole detour.

Lesson: Claude Code is an engineer, not a product manager. On execution, trust it fully. But directional decisions — what to build, which technology, who it is for — must come from you. Anthropic's trend reports: engineers use AI for 60% of their work, but only 0–20% of tasks can be fully delegated. That 80% requiring human judgment is where the most value lies.

Pitfall 7 — "No silver bullet": things it genuinely can't do well

Area	What happens	Workaround
Fine-grained UI tweaks	Pixel-level visual adjustments are hard to convey in words	Show a screenshot, or use Computer Use so it can see the screen directly
Long-term consistency	Style and conventions drift across multiple sessions	Write everything in `CLAUDE.md`; lock rules into Skills
Taste and aesthetics	It can execute a design, but cannot judge whether it is a good one	You set the direction; it does the execution
Current information	Training data has a cutoff; anything 3+ months old may be outdated	Verify all time-sensitive information with WebSearch
Collaboration scenarios	It does not understand team dynamics, relationships, or org politics	Delegate technical decisions; keep human decisions for yourself
Extreme performance optimization	Routine optimization is fine; peak tuning needs deep understanding	Let it do the first pass; review critical paths yourself

Visual Mental Model: Trust Boundary

            EXECUTION  (trust it fully)          DIRECTION  (your call)
   ┌──────────────────────────────────┐   ┌──────────────────────────────┐
   │ write code, wire APIs, fix bugs  │   │ what problem to solve        │
   │ refactor to a named pattern      │   │ which tech stack             │
   │ first-pass optimization          │   │ who the users are            │
   │ run tests, deploy, CI/CD         │   │ which features to cut        │
   └──────────────────────────────────┘   │ is the design any good       │
                                          └──────────────────────────────┘
   Rule: AI proposes, you decide.  ~60% of work assisted, only 0-20% fully delegated.

Important Comparisons

	Said in conversation	Written in CLAUDE.md / a Skill
Survives context compaction?	No — may fade to a "vague shadow"	Yes — re-read fresh every session
Good for	One-off, task-specific asks	Rules you have given more than twice

	Normal session	Agent Teams	Many MCP servers
Context / token impact	Baseline	~7× tokens	Tool definitions can eat ~15% of context
When to use	Default	Only when you genuinely need parallelism	Only the ones you are actively using

Common Beginner Mistakes

Repeating rules in chat instead of putting them in CLAUDE.md / a Skill.
Trusting confident answers about pricing, dates, or features without WebSearch.
Never checking /cost or /context until the bill or the degradation surprises you.
Leaving unused MCP servers running.
Publishing an AI first draft directly without an AI-flavour-reduction pass.
Vague requests with no stopping condition — inviting Claude to "improvise."
No clean commit before a major change.
Adopting Claude's architecture/tech choices without your own ten minutes of thought.
Expecting taste, pixel-perfect UI, or org-politics awareness from the model.

Best Practices

Rules live in CLAUDE.md or Skills, not in conversation.
Verify all time-sensitive facts with WebSearch; make it an "Absolute Rule".
Check /cost and /context regularly; shut down idle MCP servers; prefer several small sessions.
Use Agent Teams only for genuine parallelism.
Always run an AI-flavour-reduction pass on human-facing writing.
Be specific and give stopping conditions; use Plan mode for complex changes.
Keep a clean commit to roll back to before any major change.
AI proposes, you decide — especially architecture and technology.
For UI/aesthetics, show screenshots or use Computer Use; you judge whether it is good.
Treat it like a hardworking but careless junior engineer — check its basic mistakes, give it direction.

Interview / Revision Questions

Why does Claude "forget" instructions in a long session, and what is the fix?
What is "confident wrongness," and what rule does the author now keep as number one?
Roughly how much more expensive is Agent Teams than a normal session?
How can idle MCP servers hurt you even when you are not calling them?
List three "AI flavour" tells in writing.
What is the /proofreading Skill for, and what detection-rate range does it target?
Give two real examples of Claude "going off the rails" and the four lessons drawn from them.
Why is over-dependence the most subtle pitfall?
According to Anthropic's trend reports, what share of tasks can be fully delegated?
Name four things Claude Code genuinely cannot do well, with a workaround for each.
What is the recommended overall mindset toward Claude Code?
Where is the line between "trust it fully" and "your call"?

Practice Exercises

Exercise 1: Take a rule you have told Claude more than twice and move it into CLAUDE.md under an "Absolute Rules" heading.

Exercise 2: Ask Claude for a current price or spec, then verify it with WebSearch and note the gap.

Exercise 3: Run /context with all your MCP servers on, then again with the idle ones off, and record the difference.

Exercise 4: Take an AI-written paragraph and rewrite it to remove three "AI flavour" tells.

Exercise 5: Before a change, make a clean commit, then give Claude a request with an explicit stopping condition ("only touch this one file").

Exercise 6: For your current project, write one sentence each for: what to build, which tech, who it is for — the decisions you will not delegate.

Quick Memory Map

Pitfalls & Boundaries
│
├── 1 Forgetting        -> compaction is lossy -> rules in CLAUDE.md / Skills
├── 2 Confident wrongness -> verify data/dates/prices with WebSearch
├── 3 Token cost        -> Agent Teams ~7x ; idle MCP eats ~15% context
│                          -> /cost, /context, small sessions
├── 4 AI flavour        -> never publish first draft raw -> /proofreading
├── 5 Going off rails   -> be specific + stopping conditions + Plan mode + git
├── 6 Dependency        -> AI = engineer, not PM ; direction is yours
└── 7 No silver bullet  -> pixel UI, taste, current info, org politics,
                           long-term consistency, peak perf tuning
Mindset: hardworking but careless junior engineer.

Complete Chapter Revision

Forgetting: long conversations compact lossily; put important rules in CLAUDE.md or Skills.
Confident wrongness: Claude never says "I don't know"; verify all time-sensitive facts with WebSearch.
Cost: Agent Teams ~7× tokens; unused MCP servers eat context; use /cost, /context, and smaller sessions.
AI flavour: first drafts are fine, raw publication is not — run an AI-flavour-reduction pass (/proofreading).
Going off the rails: vague requests invite improvisation — be specific, set stopping conditions, use Plan mode, keep a clean commit.
Dependency: the subtle one — AI proposes, you decide; only 0–20% of tasks are fully delegable.
No silver bullet: pixel-level UI, taste, current information, team dynamics, long-term consistency, and peak performance tuning all need you.
Mindset: a hardworking but occasionally careless junior engineer — exceptional execution, limited vision.

Final Takeaway

The chapter's central lesson:

Using Claude Code well means knowing where its capabilities end. Trust its execution completely; keep direction, technology choice, taste, and fact-checking firmly with yourself. The door is open — but you decide where to walk.

This teaching edition is based on the supplied April 2026, 2nd edition of Claude Code: The Complete Guide (§09b, "Pitfalls Guide: Where AI Coding Has Its Limits"). Context-window size, cost multipliers, command names and delegation statistics reflect that edition and may change over time.