Claude Code Field Guide: Environment and Efficiency

Part of the Claude Code Field Guide series.

---

Long conversations get expensive (on pay-per-token plans) and slow (context processing). A few patterns help.

Token Efficiency

Logs to Files

Instead of watching Claude process thousands of lines of console output:

# Don't do this - floods context
npm run build

# Do this - Claude can grep what it needs
npm run build > /tmp/build.log 2>&1
grep -i error /tmp/build.log

The full log exists for deep investigation. Claude only loads what's relevant.

Targeted Investigation

When debugging:

# Bad: dump entire log
cat application.log

# Good: extract relevant window
grep -A5 -B5 "ERROR" application.log > /tmp/errors.log
# Then read /tmp/errors.log

Claude can always go deeper if the summary isn't enough, but starting narrow saves significant context.

Why This Matters

On flat pricing (Max plan), token efficiency is about speed, not cost. Smaller context = faster responses.

On pay-per-token, these patterns save real money. A 100KB log dumped into context vs. a 1KB grep result is a 100x difference.

direnv: Multi-Project Sanity

I work across multiple projects, multiple cloud accounts, multiple access levels. direnv makes this manageable.

The Problem

Without direnv:

1. Open terminal
2. gcloud config set project client-a-prod
3. Do work for client A
4. Switch to client B project
5. Forget to switch gcloud config
6. Accidentally deploy to wrong project

With direnv:

1. cd ~/Code/client-a → automatically loads client A credentials
2. cd ~/Code/client-b → automatically loads client B credentials
3. Impossible to accidentally cross-contaminate

The Setup

Each project has .envrc:

# ~/Code/client-a/.envrc
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/client-a-sa.json"
export CLOUDSDK_CORE_PROJECT="client-a-production"
export ENVIRONMENT="production"

# ~/Code/client-b/.envrc
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/client-b-sa.json"
export CLOUDSDK_CORE_PROJECT="client-b-staging"
export ENVIRONMENT="staging"

Claude Code (via my global CLAUDE.md instruction) sources .envrc before running cloud commands. The right credentials are always active for the current directory.

This enables true parallel work across projects. Different terminals, different projects, different accounts, no confusion.

CLAUDE.md Integration

In my global ~/.claude/CLAUDE.md:

## Environment Setup

Before running any shell commands that interact with cloud services
(gcloud, bq, terraform, etc.), source .envrc if it exists:

source .envrc 2>/dev/null || true

This ensures Claude always uses the correct project credentials.

Everything in the Repo

With Claude Code, it's more important than ever to keep everything in version-controlled repositories:

• Configuration as code: Infrastructure, CI/CD, linting rules—all versioned
• Documentation alongside code: docs/ in the repo, not a separate wiki
• Machine-readable formats: YAML, JSON, markdown—formats Claude can parse and modify
• No tribal knowledge: If it's not written down and committed, it doesn't exist

Why this matters now:

• Claude can read and modify anything in the repo
• Version history provides rollback for Claude's changes
• PRs give you review checkpoints for AI-generated code
• Everything is discoverable—Claude can find what it needs

Structure repositories for machine readability. Use consistent naming, clear directory hierarchies, and predictable patterns. The easier it is for Claude to understand your project structure, the better it works.

Engineering Principles with AI

Explicitly ask Claude to follow good engineering practices. LLMs tend toward verbose, one-off solutions unless directed otherwise.

In my CLAUDE.md:

## Code Quality

Always apply:
- **DRY** - Don't repeat yourself. Extract common patterns.
- **KISS** - Keep it simple. Avoid over-engineering.
- **Modular** - Small, focused functions. Single responsibility.
- **Reusable** - Write code that can be used elsewhere.

Before writing new code, check if similar functionality exists.
Prefer extending existing patterns over creating new ones.

This isn't optional politeness—it's necessary guidance. Without it, Claude will happily write 50 lines that duplicate existing utility functions.

---

Back to Claude Code Field Guide