Why Context Quality Beats Effort Level in Claude Code: The 80% Heuristic

Apr 19, 2026

Context quality matters more than effort

The Problem: Reaching for Max When Medium Fails

I was working on what should have been a simple task: adding a new API endpoint to my Flask backend. The task felt straightforward - create a route, add validation, return a standard response format.

But when I ran Claude Code at Medium effort, it failed. The route was created but validation was missing. The response format didn’t match my project’s pattern.

So I increased to High effort. Same problems. Then I went to Max effort, expecting Claude to “think harder” and finally get it right.

Max effort produced slightly better results, but still missed key patterns. I was confused - why would such a simple task require Max effort?

Then I found a Reddit thread that changed my understanding: “A model on Low with great context often outperforms the same model on Max with poor context.”

The insight hit hard: I was spending the extra thinking budget on “reconstructing state the session should already have.”

The Core Insight: Effort Level is a Context-Quality Proxy

The Reddit discussion (by ng37779a) revealed something fundamental about Claude Code:

Medium effort + poor CLAUDE.md = Claude "spends" budget reconstructing:
  - Build commands (should be in CLAUDE.md)
  - Architecture patterns (should be in CLAUDE.md)
  - Response formats (should be in CLAUDE.md)
  - File relationships (should be in CLAUDE.md)

Max effort + poor CLAUDE.md = Claude STILL spends budget reconstructing
  The extra thinking budget goes toward figuring out what the session
  SHOULD already know, not toward solving your actual task.

Low effort + great CLAUDE.md = Claude "spends" budget on your task
  No reconstruction needed. Context is already present.
  Thinking budget goes directly to implementation quality.

This explained everything. My CLAUDE.md was minimal - just “Flask backend, use clean code.” Claude was wasting tokens figuring out my patterns instead of implementing my task.

The 80% Heuristic

The Reddit thread established a practical rule:

If you find yourself reaching for Max on a task that feels like
it shouldn't need it, ~80% of the time the fix is upstream:
  - Better CLAUDE.md
  - Clearer plans
  - Atomic tasks with zero ambiguity

NOT: Increase effort level
BUT: Improve what the session knows

This heuristic changed my workflow. Before increasing effort, I audit context.

What Context Quality Actually Means

The official Claude Code documentation defines six dimensions of CLAUDE.md quality:

Dimension             Weight   What It Measures
─────────────────────────────────────────────────────
Commands/workflows    20 pts   Build/test/deploy commands present
Architecture clarity  20 pts   Codebase structure understood
Non-obvious patterns  15 pts   Gotchas and quirks captured
Conciseness           15 pts   Dense, valuable content
Currency              15 pts   Reflects current codebase
Actionability         15 pts   Instructions executable

Target: 90+ points for optimal context quality

Each dimension represents “state the session should already have.” When missing, Claude reconstructs it - burning thinking budget.

My CLAUDE.md Before vs After

Here’s what I had (the poor context that forced reconstruction):

# Project Setup

This is a Flask backend project.

Run tests with pytest.

Use clean code practices.

Problems:

No specific test command (pytest? pytest tests/? pytest -v?)
No architecture overview
No API response format pattern
No validation pattern
“Clean code” is subjective, not actionable

Here’s what I added (the good context that enabled efficient thinking):

# Backend API

## Quick Start
pip install -r requirements.txt
python app.py              # Start server on port 5000

## Test Commands
pytest tests/              # Unit tests
pytest tests/ -v           # Verbose output
pytest --cov=app           # With coverage (target: 80%)

## Architecture
app/
  routes/        # Flask blueprints, each file is one resource
  services/      # Business logic, no direct database access
  repositories/  # Database access, SQLAlchemy queries only here
  models/        # SQLAlchemy models, one file per table
  utils/         # Pure functions, no side effects

## Key Files
- app/routes/__init__.py — Registers all blueprints
- app/repositories/base.py — Base repository pattern
- app/utils/validation.py — Input validation schemas

## API Response Format
{
  "success": boolean,
  "data": object | null,
  "error": string | null
}

## Gotchas
- All routes must go through services (never direct repo calls)
- Validation uses marshmallow schemas, not manual checks
- Error responses use the standard format, never plain strings

Benefits:

Commands copy-paste ready
Architecture mapped with relationships
Key files identified
Response format documented
Gotchas captured
Dense, actionable, no filler

The Diagnostic Pattern: When Effort Level Reveals Context Gaps

After improving my CLAUDE.md, I discovered a diagnostic pattern:

Signal: Project works on High but fails on Medium
Meaning: Context gaps, not model weakness
Action: Audit CLAUDE.md, add missing info

Signal: Need Max for a "simple" task
Meaning: Claude is reconstructing state that should exist
Action: Check upstream context quality first

Signal: Results inconsistent across sessions
Meaning: CLAUDE.md missing key patterns
Action: Document what Claude should know but doesn't

The key insight: Effort level behavior reveals context quality. When effort changes break workflows, the signal is “fix context,” not “use more effort.”

The Fix Workflow: Audit Before Increasing Effort

I now follow this workflow when Claude Code struggles:

1. Task fails at Medium effort
2. Before reaching for High/Max:
   └─────────────────────────────────────
   | Check CLAUDE.md quality score       |
   | Identify missing context:           |
   |   - Commands? Add exact syntax      |
   |   - Architecture? Add directory map |
   |   - Patterns? Document with examples|
   |   - Gotchas? Add them               |
   └─────────────────────────────────────
3. Re-run at Medium
4. If still fails, THEN consider higher effort

The CLAUDE.md Quality Checklist

I use this checklist before increasing effort level:

## Commands (20 pts)
[ ] Build command documented with exact syntax?
[ ] Test command(s) documented?
[ ] Dev workflow clear (start, stop, debug)?

## Architecture (20 pts)
[ ] Directory structure explained?
[ ] Module relationships clear?
[ ] Entry points identified?

## Patterns (15 pts)
[ ] Key patterns documented with examples?
[ ] Gotchas captured?
[ ] "Why we do this" explained?

## Conciseness (15 pts)
[ ] No filler or generic advice?
[ ] Each line adds value?
[ ] No redundancy with code comments?

## Currency (15 pts)
[ ] Commands work as documented?
[ ] File references accurate?
[ ] Tech stack current?

## Actionability (15 pts)
[ ] Commands copy-paste ready?
[ ] Paths are real?
[ ] Steps concrete, not vague?

Score: __/100    Target: 90+

When my score drops below 90, I add context before increasing effort.

Why This Matters: Token Efficiency

Every context gap forces Claude to “spend” thinking budget on reconstruction:

Scenario A: Max effort + Poor CLAUDE.md (score: 40)
───────────────────────────────────────────────────
Total thinking budget: Large
Budget spent on reconstruction: 70%
Budget spent on actual task: 30%
Result: Mediocre output despite Max effort

Scenario B: Medium effort + Good CLAUDE.md (score: 95)
───────────────────────────────────────────────────
Total thinking budget: Medium
Budget spent on reconstruction: 5%
Budget spent on actual task: 95%
Result: Better output with lower effort

The math is clear: Better context = less reconstruction = more efficient thinking.

Common Mistakes I Made

Mistake	Why It Fails	How I Fixed It
Max as first resort	Diagnosis wrong	Audit context before increasing effort
Generic CLAUDE.md	Claude wastes tokens	Write project-specific rules
Stale context	Wrong signals	Update CLAUDE.md when architecture changes
Missing “why”	Claude doesn’t understand reasoning	Explain reasoning behind patterns
Verbose over dense	Claude reads filler	Remove generic advice, keep actionable info

The biggest mistake was treating effort level as the solution when context quality was the actual problem.

Summary

The 80% heuristic has transformed my Claude Code workflow:

When effort level increases become necessary for “simple” tasks, 80% of the time the upstream problem is missing project state, not insufficient model thinking.

Fix context quality first. Audit CLAUDE.md. Add commands, architecture, patterns, gotchas. Then re-run at the original effort level.

A Low-effort session with comprehensive CLAUDE.md often produces better results than Max-effort with sparse context. The model’s thinking goes toward your actual task, not figuring out project basics.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Reddit: Effort level is partly a context-quality proxy
👨‍💻 Anthropic Claude Code Documentation

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!