Lesson 2.3 — Glob Patterns: Loading Entire Directories for Bulk Changes

Lesson 2.3 — Glob Patterns: Loading Entire Directories for Bulk Changes

THE NAIVE APPROACH TRAP

A developer coming from Claude.ai chat hits a task like this: add return type annotations to every function across 12 route handlers. Their instinct is to open each file, paste it into chat, get the suggestion, apply manually. Realising that's 30 minutes of copy-paste, they upgrade to Claude Code and type /add src/routes/auth.py, get the diff, /remove it, then /add src/routes/users.py. They've replaced copy-paste with a slower, more deliberate version of the same sequential loop.

The fix is a single line: /add src/routes/**/*.py. One glob, 12 files, all in context simultaneously. Claude can now see cross-file patterns — duplicate error-handling logic, inconsistent return shapes — and produce diffs that are globally coherent instead of locally correct. The problem is that without understanding how Claude Code resolves globs, this single line can silently consume your entire context budget before you've typed a single instruction.

THE FAILURE MODE

Context window overflow from over-broad globs. /add src/**/* on a real Python web project matches .pyc bytecode, SQLite dev databases, __pycache__ directories, and fixture JSON blobs. Claude Code CLI resolves the glob client-side before sending content to the API. The resulting token count can exceed usable context (approximately 150K tokens for claude-sonnet-4-20250514 after leaving headroom for system prompt and response). The CLI does not hard-fail — it truncates or degrades coherence on files that overflow. /status after loading reveals the damage, but you've already spent the tokens.

Binary file contamination. Shell glob patterns like **/* match .pyc compiled bytecode, .sqlite dev databases, and binary assets. Claude Code encodes these as UTF-8 text, producing garbage byte sequences that consume tokens without contributing signal. A single 200KB SQLite file costs ~50K tokens — one third of your usable budget — and returns noise.

Gitignore semantics are not automatic. Claude Code glob expansion does not read .gitignore. A **/*.py pattern descends into node_modules/, .venv/, and dist/ unless you explicitly exclude them. On a project with a Python virtual environment, this can triple the matched file count.

ANSI escape codes breaking headless pipelines. When chaining glob-loaded sessions with claude --print in bash, stdout includes ANSI color codes if the terminal is a TTY. Piping to grep or jq without stripping these breaks parsing. Fix: pass --no-color to the CLI invocation.

Non-zero exit codes swallowed silently. Bare && chains in shell scripts swallow non-zero exits from claude --print. Use set -euo pipefail and capture exit codes explicitly — covered in depth in Lesson 3.1.

THE CLAUDEFORGE ARCHITECTURE

Lesson 2.3 is the scaling bridge between individual file operations (2.1: /add, /remove, /status) and bulk automated workflows (2.4: multi-file simultaneous refactor). Glob patterns express directory-level intent instead of file-level intent.

What this lesson introduces:

Forward connections:

• Lesson 2.4 uses the glob-loaded context directly — the same route-handler context loaded here is the input to a codebase-wide rename pass.

• Lesson 3.3 (batch type-hint adder) uses glob patterns inside a Bash loop to process a codebase that exceeds a single context window, splitting work across multiple claude --print invocations with per-file state tracking.

Files introduced:

IMPLEMENTATION DEEP DIVE