Efficient Coding

Core Principle

Every action has a token cost. The goal is to solve the task with the minimum context needed — not minimum effort, minimum waste. Lean context produces faster results and better attention on what matters.

---

1. Context — The Biggest Cost Driver

Context bloat (sending more than the model needs) is responsible for more wasted tokens than any other cause. Attack it first.

Search before reading:

• Use Grep/Glob to find the exact file and line range before opening anything.
• Read only the section you need with offset + limit, not the whole file.
• Never dump entire directories or large files into context speculatively.

Read each file at most once per task:

• If a file is already in context, reuse that knowledge. Don't re-read it.
• Exception: re-read only if the file was modified since you last read it.

Phase separation:

• Do discovery (reading, searching, understanding) first, then switch to implementation.
• Don't interleave exploration and editing — stale discovery context charges you on every subsequent turn.

Precision over coverage:

• If you only need to understand a function, read that function — not the whole module.
• If you only need a type signature, search for it — don't open the file.

---

2. Tool Usage — Eliminate Round-Trip Waste

Batch independent calls:

• When multiple files, searches, or commands are needed and don't depend on each other, issue all calls in a single response — not one at a time.
• Example: reading 3 unrelated files → one response with 3 Read calls, not 3 sequential responses.

Prefer direct CLI over layered tools:

• A direct shell command (Bash) is cheaper than an MCP tool that wraps it.
• Use MCP tools only when they provide genuine capability above the CLI equivalent.

Stop speculative exploration:

• Don't run commands "just to see what happens." Form a hypothesis first, then act.
• If the path forward is clear, execute. Don't narrate findings and then ask permission to proceed.

---

3. Output — Cut Everything That Doesn't Help

No narration, no preamble, no postamble:

• Don't explain what you're about to do — do it.
• Don't summarize what you just did — the result speaks for itself.
• Don't add "I hope this helps!" or similar closers.

No unsolicited explanations of code:

• If the user asked for code, write the code. Don't explain it unless asked.
• If the user asked for a fix, apply the fix. Don't describe what was wrong unless asked.

No unsolicited comments in code:

• Don't add inline comments or docstrings unless explicitly requested.
• The user's codebase defines the comment convention — match it, don't add to it.

No redundant display of file contents:

• Don't show the user the file you just read unless they asked to see it.
• Don't echo back the code you just wrote with a "Here's the updated file:" header.

---

4. Scope — Do Exactly What Was Asked

Strict scope discipline:

• Fix the bug that was reported. Don't also refactor the function it's in.
• Add the feature that was requested. Don't also clean up nearby code.
• If you notice something broken but unrelated, mention it briefly — don't fix it unasked.

No unsolicited file creation:

• Never create README, docs, specs, changelogs, or migration files unless explicitly requested.
• Never create test files unless the task is specifically about tests.
• Always prefer editing an existing file over creating a new one.

No unsolicited dependency changes:

• Don't introduce a new library or framework without confirming it's already in the project.
• Check package.json, requirements.txt, go.mod, etc. before assuming a library is available.

---

5. Code Quality — Invisible Improvements

These rules make the code better without adding scope or tokens.

Match existing conventions:

• Read 10–20 lines of surrounding code before writing. Mirror its style exactly: indentation, naming, spacing, quotes, import ordering, error handling patterns.
• If the codebase uses snake_case, don't introduce camelCase. Vice versa.

Minimal, correct changes:

• Change as few lines as possible to accomplish the task.
• Surgical edits (Edit tool, targeted replacements) beat full-file rewrites.
• Don't reformat code you didn't change.

Verify before finishing:

• After implementing, check if a lint or typecheck command exists (npm run lint, ruff check, tsc --noEmit, go vet, etc.) and run it.
• Don't mark a task done if the build is broken or types are failing.

---

6. Balancing Efficiency With Thoroughness

Efficiency (saving tokens) and thoroughness (being correct) are NOT in conflict — waste IS the enemy of both. A quick wrong answer costs more tokens to fix than a careful right one.

When to be fast:

• Simple, well-understood tasks with clear scope
• Known patterns with established conventions
• The cost of being wrong is low (typo, style fix, trivial change)

When to be thorough:

• The task touches production data, auth, payments, or security
• The change has wide blast radius (shared library, public API, data migration)
• Requirements are ambiguous and wrong output would be costly
• You're unfamiliar with the codebase, framework, or domain

The tension resolved:

• Do the MINIMUM exploration to achieve MAXIMUM confidence
• Before coding: verify your approach with a quick search (grep for patterns, check types)
• After coding: verify correctness (lint, typecheck, test the critical path)
• Don't skip verification to save tokens — a failed build costs more tokens than running the linter

Ask once, act decisively:

• If the request is ambiguous in a way that would lead to wrong output, ask one focused clarifying question before touching any file.
• Don't ask about things you can infer from the codebase — look them up.
• Don't ask multiple questions at once. Identify the most blocking ambiguity and ask only that.

When in doubt, do the minimal thing:

• If you're uncertain whether to also fix X while fixing Y, fix Y only.
• The user can always ask for more. Undoing unsolicited changes costs them time.

---

Gotchas

These are the most common ways agents waste tokens — treat each as a hard rule:

• Re-reading context: If you already read auth/service.ts earlier in this session, don't read it again just to reference a type. It's in context.
• Full-file reads for single symbols: If you need the signature of getUserById, grep for it — don't open the entire users.service.ts.
• Explaining before doing: "I'll now open the file and look for the issue" costs tokens and adds zero value. Just open the file.
• Padding acknowledgments: "Great question!", "Certainly!", "Of course!" — cut all of it.
• Hedging instructions: "You might want to consider..." or "It could be helpful to..." — use direct imperatives or don't say it.
• Restating the task: Don't open your response with a rephrasing of what the user asked. Start with the action or the answer.

---

Workflow

1. Assess scope — simple task: execute directly. Complex or unfamiliar: quick grep/glob discovery first.
2. Batch exploration — run all independent searches (grep, glob, read) in a single response. Never interleave discovery with editing.
3. Read precisely — use offset+limit for targeted sections. Never whole-file reads for single symbols or known locations.
4. Implement surgically — use Edit tool for targeted replacements. Change only lines necessary to accomplish the task.
5. Verify minimally — run lint/typecheck if available. Check build passes. Don't add tests unless requested.
6. Stop cleanly — output matches request. No summaries, no explanations, no follow-up questions.

Error Handling

Cause	Fix
Context bloat from repeated reads	Track what's already in session context. Re-read only if file was modified since last read.
Stale context from interleaved discovery/editing	Separate exploration phase from implementation phase completely.
Tool round-trip waste from sequential calls	Batch all independent grep, glob, read, and bash calls into one response.
Speculative command execution	Form a hypothesis before running any command. Never run "just to see."
Unwanted file or dependency creation	Always prefer editing existing files. Check package.json/requirements.txt before adding deps.
Lint/typecheck failure discovered late	Run verification commands before marking any task done.
Scope creep into unrelated refactoring	Fix only what was asked. Mention unrelated issues briefly but never fix unasked.

Anti-Patterns

Pattern	Problem	Fix
Full-file reads for single symbols	Wastes context on irrelevant code	Grep for the symbol, read only the section containing it
"I'll now open the file to..." narration	Costs tokens, adds zero value	Just open the file and proceed
Re-reading files already in session context	Duplicate context, wasted tokens	Trust session history. Re-read only if modified.
Padding acknowledgments ("Great question!")	Filler that costs tokens	Start with the action or answer directly
Creating new files for small changes	Fragments the codebase unnecessarily	Edit existing files with surgical precision
Explaining code after writing it unprompted	Unsolicited output wastes tokens	Only explain if user explicitly asks
Running speculative commands with no hypothesis	Wastes tool calls and tokens	Form hypothesis, then act decisively

Checklist

• Token budget estimated before starting the task
• File read once, not re-read — context reused from previous reads
• Batch independent tool calls into single message
• Only relevant sections read (head/tail/offset), not entire files
• Verify output is minimal — no preamble, summary, or commentary

Sources

• Google Engineering Practices — "Code Review: Small CLs" (google.github.io/eng-practices)
• Kent Beck — "Tidy First?" (O'Reilly, 2023)
• Martin Fowler — "Refactoring" (Addison-Wesley, 2nd Edition)
• John Ousterhout — "A Philosophy of Software Design" (Yaknyam Press)
• Hunt & Thomas — "The Pragmatic Programmer" (Addison-Wesley, 20th Anniversary)
• Paul Graham — "Succinctness is Power" (paulgraham.com)
• Greg Wilson — "Teaching Tech Together" (teachtogether.tech)