token-awareness

token-awareness

Token budgeting is an engineering discipline. Before writing code, estimate whether the approach is token-efficient. A 300-token workaround that solves 80% of the problem beats a 3000-token refactor that solves 100% — especially when the remaining 20% never materialises.

Tokens are also an energy metric:

• more tokens = more energy consumed
• more useful output per token = better efficiency
• if watt telemetry exists, token efficiency becomes comparable to throughput per watt

So token awareness is not just about staying under a context limit. It is about choosing higher-yield routes through the system.

1) The Core Question Before Every Task

"What is the minimum change that fully satisfies the requirement?"

Not the cleanest change. Not the most extensible. The minimum effective one.

Approach A: refactor the whole module            → 2000 tokens to read + 800 to write
Approach B: add a 10-line guard in one function  → 200 tokens to read + 80 to write
                                                   ↑ 10× cheaper if B solves the problem

Ask before opening files:

1. Do I need to read the whole file, or just the function signature?
2. Can I solve this with a targeted edit rather than a rewrite?
3. Has the problem already been solved somewhere in the codebase?

2) Token Cost Estimates (rough rules of thumb)

Operation	Approx. tokens consumed
Read a 100-line Python file	~400 tokens
Read a 500-line file	~2 000 tokens
Read package.json / requirements.txt	~200–400 tokens
Read a docker-compose.yml (5 services)	~600 tokens
Read an entire React component (200 lines)	~800 tokens
Write a 50-line function	~300 tokens
Write a 200-line module	~1 200 tokens
Run a grep across 20 files	~100 tokens (just the matches)
Read a large file you don't need	pure waste

High-waste patterns to avoid:

• Reading a 600-line file when only one function is relevant → use grep first to locate the line, then Read with offset + limit
• Re-reading a file you already read in the same session → use recalled content
• Asking an agent to "explore the whole codebase" for a targeted fix → grep for the symbol instead
• Refactoring surrounding code not related to the task → scope creep inflates cost with no requirement value