DEV Community: assaf baruch

Most Claude Code Complaints Are Context Problems, Not Model Problems

assaf baruch — Tue, 18 Aug 2026 20:22:15 +0000

I've been spending time in the Claude Code community lately, reading through the complaint threads. Model got nerfed. Token usage exploded. It ignores my CLAUDE.md. It's vague and won't explain itself.

Some of these are real. But after reading enough of them, a pattern shows up: the same underlying issue keeps wearing different costumes. It's almost always about context. What's in the window, what the model is being asked to infer, and what nobody told it explicitly.

Here are the four versions I keep running into, and what actually fixes them.

"Token usage suddenly exploded"

The complaint: usage doubled without the workload changing.

What's usually happening: long sessions. Every turn resends the entire conversation history. A session that ran for two hours isn't paying for what you asked in the last message. It's paying for everything you asked since the beginning, again, on every single turn.

The fix is unglamorous: end sessions and start fresh ones. Keep durable state in files (a PROJECT.md, a scratch notes file) rather than letting it accumulate in the conversation. Then every new session starts compact and reads only what it needs.

A useful signal: if you can't remember what you asked at the start of the session, it's too long.

"It ignores my CLAUDE.md"

The complaint: rules are written down, the model doesn't follow them.

What's usually happening: the file is too long, and the rules are bare assertions.

Two things consistently help. First, shorter. A file with twelve rules that get followed beats forty that get diluted. Second, attach reasons. Compare:

Never use raw SQL string concatenation.

Never use raw SQL string concatenation, injection risk.

The first is a rule the model applies literally, to the exact pattern named. The second is a principle, and the model generalizes it to the whole category: parameterized queries, ORM misuse, anywhere the same risk shows up. Models extrapolate from reasons far better than they comply with lists.

"It's vague and won't explain itself"

The complaint: it says there are "some issues to address" and you burn three rounds extracting what it means.

What's usually happening: you asked for clarity, which is an adjective, not a constraint.

Asking a model to "be clear" or "think like a senior engineer" gives it a persona, not a specification. It has no way to know what clear means for you, so it defaults to hedged, safe phrasing.

Replace the adjective with a structure. Instead of "explain the issues clearly", try:

For each issue, state:
- file and line
- what breaks
- the exact fix you propose

If you can't fill all three, say so instead of guessing.

Two things happen. Vagueness has nowhere to hide, because every slot has to be filled. And when the model genuinely doesn't know something, you see it immediately instead of receiving a confident paragraph that says nothing.

This is the same lesson as skill descriptions, which I wrote about in a previous post: adjectives are wishes, constraints are instructions.

"The output quality feels inconsistent"

The complaint: same kind of task, wildly different quality day to day.

What's usually happening: the inputs are more different than they feel. Different session length, different amount of prior context, different phrasing, different starting state of the codebase.

If you want to know whether something actually changed, you need a fixed reference. Keep two or three prompts from your real work as a benchmark. Same prompt, same starting state, run them every few weeks. Compare outputs.

Without that, you're comparing today's frustrating session to a remembered good one, and memory is a terrible instrument for this.

The thing they have in common

All four are the same mistake in different clothes: assuming the model has context it doesn't have, and hasn't been given.

It doesn't know your session got long. It doesn't know which of your forty rules matter most. It doesn't know what "clear" means in your codebase. It doesn't know what last week's output looked like.

None of this means the models are perfect or that complaints are always user error. Genuine regressions happen, and vendors should be held to them. But before concluding a model got worse, it's worth checking whether the thing that changed was the context around it.

Cheaper to check, and fixable today.

I write about building Claude Code skills and workflows for a real dev team. The full field guide, covering 5 skill patterns, anatomy, and the 7 mistakes I made, is here, and a complete debugging skill is free here.

Here's a Complete Claude Code Skill. It's Free.

assaf baruch — Fri, 14 Aug 2026 12:19:16 +0000

Two weeks ago I wrote about why most Claude Code skills never fire — the description problem. The most common response I got, in DMs and at work: "OK, but show me a full skill."

Fair. Here's one — complete, production-tested, free to copy.

It's my team's debugging protocol: the skill I built after watching Claude (and honestly, half my developers) do the same thing when hit with a bug — guess a fix, patch it, and hope. This skill forces the boring discipline that actually finds root causes.

The full skill

Save this as debugging-protocol/SKILL.md in your skills directory:

---
name: debugging-protocol
description: Systematic debugging for Python/FastAPI and general code.
  Trigger when the user reports a bug, error, exception, crash, or
  unexpected behavior, pastes a stack trace or error message, or asks
  "why doesn't this work", "what's wrong", "this is broken", "fix this
  bug". Also on short requests like "debug this" or "it fails".
  NOT for code review of working code — that's the reviewer skill.
---

# Role
You are a senior engineer who debugs systematically. You do not
propose fixes before understanding the root cause. Guessing is
the failure mode you exist to prevent.

# Process — in this order, no skipping

1. REPRODUCE FIRST
   Restate the bug precisely: what was expected, what happened
   instead, and under which exact conditions. If you cannot state
   all three from the information given — ask, don't assume.

2. ISOLATE
   Narrow the search space before proposing anything:
   - What is the smallest input/scenario that still fails?
   - When did it last work? What changed since (code, deps, data,
     config, environment)?
   - Does it fail consistently or intermittently?

3. HYPOTHESIZE — OUT LOUD
   State 2-3 candidate root causes, ranked by likelihood.
   For each: what evidence would confirm or kill it, and what is
   the cheapest way to get that evidence (a log line, a breakpoint,
   a one-line test)?

4. VERIFY BEFORE FIXING
   Test the top hypothesis with evidence, not intuition. Show the
   verification step. Only a confirmed root cause earns a fix.

5. FIX THE CAUSE, NOT THE SYMPTOM
   Propose the minimal fix for the confirmed root cause. If the
   symptom could be silenced without fixing the cause (a try/except,
   a null check) — say so explicitly and explain why that's wrong here.

6. PREVENT RECURRENCE
   One short suggestion: the test, assertion, or log line that would
   have caught this class of bug earlier.

# Output format
## Bug
[one-line restatement]
## Root cause
[confirmed cause + the evidence]
## Fix
[minimal code change]
## Prevention
[one test/assertion/log suggestion]

# Hard rules
- Never propose a fix in step 1-3. Ever.
- If information is missing, ask for the specific missing piece —
  don't fill gaps with assumptions.
- If the first hypothesis dies, say so and move to the next.
  Dead hypotheses are progress, not failure.

Prefer a ready file? Grab the skill as a downloadable SKILL.md here (free): https://asfbar.gumroad.com/l/toofjt

Why each block is built this way

The description names the lazy phrasings. "Debug this", "it fails", "what's wrong" — that's how people actually type at 11pm. This was the whole lesson of the first article: a description without your real phrasing is a skill that never loads. Note also the last line — the boundary ("NOT for code review") — which stops this skill from shadowing my reviewer skill.

Step 1-3 exist to slow the model down. Claude's default instinct (like most developers') is to jump to a plausible fix. Plausible is the enemy: it feels like progress and buries the actual cause. Forcing reproduce → isolate → hypothesize before any fix is allowed changes the entire quality of the output.

"Out loud" hypotheses are the killer feature. When Claude ranks 2-3 candidate causes and states what evidence would kill each one, two things happen: you can veto a wrong direction in seconds, and the eventual fix comes with a reasoning trail you can trust — or audit when it's wrong.

The output format makes results diffable. Every debugging session ends in the same four sections. After a month, your team can scan any past session in ten seconds. Consistency is the compound interest of skills.

The hard rules carry the "why". Models generalize from reasons, not rule lists. "Dead hypotheses are progress" isn't decoration — it stops the model from stubbornly defending hypothesis #1 after the evidence kills it.

Adapt it in 5 minutes

Swap "Python/FastAPI" for your stack in the description. If your team uses a specific logger or test framework, name it in step 6 — prevention suggestions get dramatically better when the skill knows your tools.

This is skill #1 from my production set. The full field guide — 5 skill patterns, anatomy, and the 7 mistakes I made building them for my team — is here: Stop Prompting. Start Building Claude Code Skills. I'm packaging the complete ready-to-install skill pack next — this article is what it will feel like. Questions about adapting the skill to your stack? Comments are open.

Your Claude Code Skill Never Fires — and It's Not the Skill's Fault

assaf baruch — Sat, 08 Aug 2026 20:39:09 +0000

I manage a dev team, and we've been running Claude Code daily for months. I built a set of custom skills for us — code review, a debugging protocol, our team conventions — and the biggest lesson I learned surprised me:

The body of your skill barely matters if the description is wrong.

The failure mode nobody warns you about

Here's what happens to most developers who discover skills. They get excited, write a detailed 200-line SKILL.md encoding everything they know about code review... and then it never triggers. Not once. They conclude skills "don't really work" and go back to re-typing the same prompt every session.

The skill was probably fine. The description killed it.

The description is a routing rule, not documentation

A skill's description is the only part Claude sees upfront. The full instructions load only after the description matches your request. So the description isn't marketing copy — it's a routing rule, and it needs to be written like one.

Compare:

# WEAK — reads nicely, never triggers
description: Helps with code quality and best practices.

# STRONG — names the situations AND the phrasings
description: Security-first code review for Python/FastAPI.
  Trigger when the user asks to "review", "check", or
  "look at" code, pastes a function or endpoint, mentions
  a bug, or asks "what's wrong with this". Also trigger
  on short requests like "review this".

The difference: the strong version contains the actual words you type. Including the lazy ones. Nobody writes "please perform a comprehensive quality assessment" at 11pm — they write "review this". If your description doesn't cover the two-word tired version, your skill sleeps through most of your real requests.

Three rules that fixed my skills

1. List your real trigger phrases. Open your chat history and look at how you actually phrase requests. Those exact phrases go in the description — "fix it", "what's wrong here", "check this". Your real vocabulary, not your professional vocabulary.

2. Name the artifacts, not just the verbs. "When the user pastes Python code", "when a stack trace appears", "when a diff is shared". Half my requests don't contain a verb at all — I just paste code. The description has to catch that.

3. Draw the boundary. Say what the skill is not for: "not for writing new features — that's handled by the builder skill". Without boundaries, overlapping skills shadow each other and you get the wrong specialist answering.

Test it like code

My rule now: after writing a skill, open a fresh session and make five requests the way I'd naturally type them — tired, abbreviated, mid-task. If the skill fires on four out of five, it ships. If not, the description needs more of my real phrasing, not more adjectives.

Treat every miss as a bug. The fix is almost always adding one more real-world phrasing to the description.

I packaged everything I learned building skills for my team — the anatomy, five battle-tested patterns, a complete production-ready security-review skill, and the seven mistakes I made — into a short field guide: Stop Prompting. Start Building Claude Code Skills. Happy to answer skill-building questions in the comments either way.