title: Explore Before Change slug: explore-before-change category: workflow-pattern status: battle-tested difficulty: beginner tags: [code-reading, understanding, safety, context-gathering] prerequisites: [basic-cli-usage] estimated_time: 5min to learn, immediate use cost_per_use: "$0.02-$0.10 for exploration phase"
Explore Before Change
Problem
Agents that jump straight into editing code without reading the surrounding context produce fragile, inconsistent changes. They duplicate existing utilities, violate local conventions, break implicit contracts between modules, and miss related code that also needs updating. The cheapest fix is prevention: make the agent read before it writes.
Solution
Always include an explicit exploration phase before any code modification. The agent must understand the existing code, conventions, and dependencies before making changes.
Step-by-Step
- Scope the exploration: Tell the agent which files, directories, or patterns to examine.
- Read, do not edit: The agent reads relevant files and summarizes what it finds.
- Confirm understanding: Review the agent's summary. Correct any misunderstandings.
- Proceed to changes: Only then allow the agent to modify code.
When to Use
- Editing code in an unfamiliar codebase
- Modifying a module you did not write
- Any change that touches shared utilities or interfaces
- First task in a new session (the agent has no memory of previous sessions)
- When the agent has made incorrect assumptions in the past
When NOT to Use
- Files you just created in this session (the agent already has full context)
- Appending to a file where surrounding context is irrelevant
- Trivial changes like updating a version number
Example: Claude Code
# Explicit two-phase prompt
claude -p "I need to add rate limiting to our API. Before making any changes:
Phase 1 — Explore:
1. Read src/middleware/ to understand existing middleware patterns.
2. Read src/routes/index.ts to see how middleware is applied.
3. Check package.json for any existing rate-limiting libraries.
4. Summarize what you found and propose an approach.
Do NOT edit any files until I confirm your approach."
# After reviewing the summary:
claude -p "Your approach looks good. Implement rate limiting following \
the patterns you found in the existing middleware."
# Add to CLAUDE.md as a standing rule
cat >> CLAUDE.md << 'EOF'
## Working with Code
- Before modifying any file, first read it completely and read its tests.
- Before adding a utility function, grep the codebase for existing ones.
- Before adding a dependency, check package.json for alternatives already installed.
EOF
# Interactive session with exploration
claude
# > I need to fix the authentication bug in the login flow.
# > First, read through src/auth/ and src/middleware/auth.ts.
# > Tell me how the current auth flow works before changing anything.
# (agent reads and explains)
# > Good. Now read the failing test in tests/auth.test.ts.
# (agent reads and explains the failure)
# > Now fix the bug using what you've learned.
Example: Codex CLI
# Exploration pass (read-only by default in codex)
codex -q "Read src/middleware/ and src/routes/index.ts. \
Explain how middleware is structured and applied in this project." \
> exploration-notes.txt
cat exploration-notes.txt
# Change pass
codex -q "Add rate limiting middleware following the patterns described here:
$(cat exploration-notes.txt)"
Cost Estimate
| Phase | Typical Cost |
|---|---|
| Exploration | ~$0.02-$0.10 |
| Modification | ~$0.05-$0.40 |
| Total | ~$0.07-$0.50 |
Exploration is cheap (mostly input tokens from reading files). It prevents expensive re-runs from bad assumptions.
Maturity Notes
Status: Battle-tested. This is foundational agent hygiene. The pattern is so reliable that many teams encode it directly into their CLAUDE.md as a standing instruction. The main failure mode is agents that skim rather than read — use specific instructions like "read the entire file" or "list all functions in this module" to force thorough exploration. Pairs naturally with Review Then Fix and Plan Then Execute.