Working with the Agent

Situation

You want Redis caching with a 5-minute TTL on a product endpoint, but you're new to production caching and unsure what else a robust implementation needs.

Recommended approach

Ask Claude to interview you first, surfacing invalidation strategy, caching layers, consistency guarantees, and failure modes before anything is built.

Why it works

You don't know what you don't know. Interviewing surfaces considerations you'd otherwise miss — cache invalidation, layering, consistency, failure modes — converting unknown-unknowns into explicit decisions before code is written.

Weaker approaches people try — and why they fall short

• Use plan mode to analyze the endpoint, then give requirements after Claude explains the code.Analyzing existing code doesn't teach you the caching considerations you're actually missing.
• Write a spec with TBD markers and let Claude propose solutions per TBD.You can only write TBDs for gaps you already recognize — the dangerous gaps are the ones you can't name.
• Make a minimal request now, add features via follow-ups as problems surface.Discovering requirements through production failures is the slowest, riskiest path for something you don't understand yet.

Situation

Add a date-validation check (event dates must be in the future) — a single conditional in one function in one file.

Recommended approach

Just make the change directly.

Why it works

The change is tiny, local, and unambiguous. Direct execution is the right amount of ceremony; planning modes and extended reasoning are for complex, multi-file, or uncertain work, and using them here just adds overhead.

Weaker approaches people try — and why they fall short

• Enter plan mode first for a detailed strategy.Overkill for a single-line conditional.
• Enable extended thinking to reason thoroughly.Wastes effort on genuinely trivial logic.
• Use plan mode to analyze impact on the wider reservation flow.There's no meaningful cross-flow impact to analyze for a self-contained check.

Situation

A migration script mishandles null values in optional fields, and needs a fix.

Recommended approach

Provide a concrete test case — an example null input plus the expected output — and ask Claude to fix it against that target.

Why it works

A concrete input/expected-output example defines success unambiguously and lets Claude make a targeted fix. It also becomes a regression check you can rerun to confirm the fix holds.

Weaker approaches people try — and why they fall short

• Add 'think harder about edge cases' and request a full rewrite.Vague feedback plus a rewrite discards working code and doesn't specify the correct null behavior.
• Fix the null handling yourself, then continue.Doesn't teach the model the pattern and loses the benefit of iterating together.
• Describe the null problem and ask for a full regeneration.Risky and wasteful when a small, well-specified fix would do.

Situation

Upgrading an auth library across a major version with breaking changes (callbacks becoming promises, a restructured type, removed methods), used across 45 files in multiple modules.

Recommended approach

Use plan mode: explore usage, map affected paths, and create a migration strategy before touching any code.

Why it works

This is a large, high-risk, interdependent change. Plan mode lets Claude map where and how the library is used and produce a reviewable strategy before implementation, so mistakes get caught on paper rather than in production.

Weaker approaches people try — and why they fall short

• Build a custom slash command and run it on each file without exploring first.A blind command can't handle usage patterns it never inspected.
• Paste the breaking changes and direct-execute across all 45 files.Direct-executing 45 interdependent files at once is error-prone with no plan to review.
• Bump the version, run tests, and fix each failure as it appears.Test-driven fixing only catches what tests cover; silent breakages in untested paths slip through.

Situation

A PDF report has three interacting problems: narrow columns truncate content, dates aren't formatted, and page breaks land wrong — and changing one affects the others.

Recommended approach

Fix column width first (with specific measurements), verify, then fix dates within the corrected columns, then adjust page breaks — testing after each step.

Why it works

Because the issues interact, changing everything at once makes it impossible to tell what fixed or broke what. Fixing one at a time and verifying after each isolates cause and effect, so each change lands on a known-good base. Column width first makes sense because both dates and page breaks depend on it.

Weaker approaches people try — and why they fall short

• Show a correct example and ask Claude to match it, without listing the issues.Matching an example doesn't supply the precise measurements the layout needs and hides which sub-issue is being solved.
• Start fresh with all requirements listed upfront.Discards working query logic and still bundles the interacting fixes together.
• Give all three issues at once with exact specs and fix them together.Fixing all three simultaneously tangles the interactions so results can't be attributed to any one change.

Situation

Adding real-time updates to a product — the choice is between WebSockets, server-sent events, or polling, each with different complexity, browser support, and infrastructure needs.

Recommended approach

Use plan mode to explore the architecture, weigh the trade-offs, and present the options for the team to approve.

Why it works

This is an architectural decision with real trade-offs and organizational impact. Plan mode lets Claude lay out the options so the team can approve a direction before code is committed — big directional choices should be decided by people, informed by analysis.

Weaker approaches people try — and why they fall short

• Direct-execute polling first, planning to upgrade later.Committing to polling prematurely may require a costly rewrite down the line.
• Direct-execute WebSockets and refactor if infrastructure issues arise.Committing to WebSockets before assessing infrastructure risks the same kind of rework.
• Direct-execute and let Claude silently pick the 'best' approach.Letting the model choose silently hides a decision that stakeholders should actually own.

Situation

Implementing a graph-traversal algorithm with performance requirements and edge cases: disconnected nodes, cycles, and weighted edges.

Recommended approach

Write a test suite first — covering behavior, edge cases, and performance — have Claude work to pass it, and iterate on whatever fails.

Why it works

The requirements here are precise and verifiable, which is exactly where writing tests first shines. It turns 'correct behavior' into an objective target; each edge case becomes a concrete pass/fail, and feedback is automatic and unambiguous.

Weaker approaches people try — and why they fall short

• Give a reference implementation, ask Claude to restyle it and add edge cases, then compare outputs.A reference implementation may not match your actual constraints, and comparing outputs is looser than a real test suite.
• Do extended-thinking research and produce one complete implementation from the plan.A one-shot implementation gives no iterative verification loop for the edge cases.
• Give a natural-language spec, review outputs manually, and describe changes each time.Manual review with prose feedback is slower and more subjective than tests, and doesn't verify performance.

Situation

After 25 minutes exploring a rendering subsystem, the agent starts citing 'typical rendering patterns' instead of the specific classes it actually found earlier. It's now asked to study how physics and rendering integrate.

Recommended approach

Summarize the key rendering findings, then spawn a subagent for the physics work, seeded with that summary as its starting context.

Why it works

Generalizing to 'typical patterns' instead of specific classes is the tell that context is degrading — useful detail is being crowded out. Summarizing preserves the valuable findings, and a fresh subagent regains a clean working context while still starting from what was already learned.

Weaker approaches people try — and why they fall short

• Clear the context entirely and start the physics work fresh from file paths in CLAUDE.md.Throws away the hard-won rendering findings still needed to relate physics to rendering.
• Continue in the same context with more targeted prompts naming the classes.Staying in the degraded context won't restore the lost detail; it will keep drifting.
• Spawn a subagent for physics independently, then manually synthesize with the rendering knowledge afterward.Exploring independently and hand-merging afterward risks losing the specific rendering linkages.

Situation

Caching logic spans 15 files and roughly 8,000 lines across decorators, middleware, and service classes. The goal is to understand it well enough to add an invalidation trigger, while keeping context usage under control.

Recommended approach

Analyze imports and class hierarchies to find the base cache class, read that to learn the shared interface, then trace the specific invalidation implementations from there.

Why it works

8,000 lines won't all fit usefully in context, so a structural map has to come first. Following imports and class hierarchies to the base class reveals the interface everything depends on, giving a targeted anchor to trace from — rather than brute-force reading.

Weaker approaches people try — and why they fall short

• Search for 'invalidate'/'expire' everywhere and read only those line ranges.Keyword-only slices miss the architecture and give a fragmented, potentially misleading picture.
• Sequentially read all 15 files for complete understanding.Blows the context budget and buries the signal in noise.
• Find files with 'cache' in the name and read the largest ones first.'Largest first' is an arbitrary heuristic unrelated to architectural importance.

Situation

Yesterday's two-hour deep-dive session into a legacy monolith's auth code needs to continue, but three other codebases have been worked on since, and the specific session needs to be found by name.

Recommended approach

Use --resume <name> with the session's name to load that specific session directly.

Why it works

The session's name is already known, and that specific session is what's wanted — resuming by name targets it directly, which is the natural fit.

Weaker approaches people try — and why they fall short

• Use a session-id flag with the UUID pulled from a transcript file.Works, but only if you go hunting for the exact ID — unnecessary when you already know the name.
• Use --continue to pick up the most recent conversation.--continue resumes the most recent session, which by now is one of the three other codebases — the wrong one.
• Start fresh and re-read the files.Discards two hours of accumulated context for no reason.

Situation

Intermittent 500 errors on one endpoint in a 200+ file codebase, with no idea yet which components are involved — could be routing, middleware, business logic, or the database.

Recommended approach

Dynamically generate investigation subtasks based on what's discovered at each step, adapting as the error path emerges.

Why it works

The bug's location isn't known yet, so the investigation has to be adaptive — each discovery narrows the next step. Generating subtasks as evidence emerges follows the real trail instead of committing to a plan built on ignorance.

Weaker approaches people try — and why they fall short

• First create a comprehensive plan mapping all code paths before any exploration.You can't comprehensively map paths you don't yet have the knowledge to plan around.
• Run parallel agents on all four layers simultaneously, then synthesize.Blind parallel investigation of every layer wastes effort and struggles to pinpoint an intermittent root cause.
• Follow a fixed step sequence regardless of findings.Ignoring intermediate findings is the opposite of what debugging an unknown actually needs.

Situation

Two requests: a mechanical rename of one function across the whole codebase, versus an open-ended request to improve error handling across a module (try/catch coverage, meaningful messages, no silent data corruption). Which one benefits from an analyze-then-propose-then-implement-with-review workflow?

Recommended approach

The error-handling request benefits from the multi-phase workflow; the rename does not.

Why it works

Improving error handling is open-ended and judgment-heavy — many valid designs exist, and the risk (silent data corruption) is real, so a review step before changes land is valuable. The rename is mechanical and unambiguous, so multi-phase ceremony adds little.

Weaker approaches people try — and why they fall short

• Assume both tasks benefit equally from the multi-phase workflow.They don't — one is deterministic, the other is design-laden.
• Apply the multi-phase workflow to the rename instead.A rename is exactly the kind of well-defined task that doesn't need phased review.
• Assume neither task benefits from it.The error-handling task clearly does benefit, so 'neither' undersells the judgment-heavy case.

Situation

Before removing a function, all its callers need to be found — but it's defined in a core library and re-exposed under a different, renamed wrapper name in another module.

Recommended approach

Read the library and its wrapper modules first to find every exposed alias, then search for each of those names.

Why it works

Because the function is re-exported under a different name, searching only for the original name misses every caller that goes through the alias. Reading the wrappers first to enumerate every name is the only way to catch calls made through renamed wrappers.

Weaker approaches people try — and why they fall short

• Search documentation for intended usage and navigate the documented integration points.Docs may be incomplete or stale — not a reliable way to find all callers.
• Search only for the original function name across the codebase.Misses every caller that goes through the renamed wrapper.
• Search for files importing the library or its wrappers, then read each one to check usage.Import-based scanning is noisy and still won't reliably tie usage back to the specific renamed function.

Situation

Resuming yesterday's auth analysis: the session is still valid, but 3 of the 12 previously-read files were changed overnight by a teammate's merge.

Recommended approach

Resume the session, and explicitly tell the agent which 3 files changed so it can re-analyze just those.

Why it works

Resuming keeps the valuable accumulated context — only what actually changed needs correcting. Naming the exact 3 changed files prompts a targeted re-read: accurate about the new reality, efficient because the other 9 files aren't redone.

Weaker approaches people try — and why they fall short

• Resume and immediately re-read all 12 files.Wastes effort re-reading 9 files that never changed.
• Start a fresh session to avoid stale assumptions.Throws away an hour of correct context over a 3-file delta.
• Resume without mentioning that anything changed.Leaves the agent reasoning from stale versions of those 3 files.

Situation

Adding comprehensive tests to a 200-file legacy codebase with minimal existing coverage, with no priorities specified up front.

Recommended approach

Map the codebase's structure, find the heavily-coupled (high-risk, high-value) modules, plan to test those first, and revise the plan as the dependency structure becomes clearer.

Why it works

With no priorities given, effort should follow impact. Mapping the structure and starting with high-coupling modules puts testing effort where risk and value are highest, and staying adaptive means the plan improves as more is learned.

Weaker approaches people try — and why they fall short

• Follow a fixed schedule by directory, with equal effort per directory regardless of complexity or importance.Ignores that some code is far riskier and more central than others.
• Start alphabetically at the first file and discover related files organically.Alphabetical order is arbitrary and unrelated to impact.
• Read all 200 files to inventory every function before writing any tests.A huge upfront cost that delays any actual value.

Situation

Yesterday's analysis surfaced two refactor approaches — extracting a microservice, versus refactoring in place. Today, concrete code changes are wanted for both, before deciding which to pursue.

Recommended approach

Fork the session from yesterday's analysis, exploring one approach in each branch.

Why it works

Both explorations should start from the same accumulated analysis but proceed independently. Forking branches the existing context into two, so each fork inherits yesterday's findings yet develops its own approach without the two ideas bleeding into each other.

Weaker approaches people try — and why they fall short

• Resume for approach one, and manually recreate the context in a brand-new session for approach two.Manually recreating context is error-prone and loses fidelity.
• Resume and explore both approaches sequentially in the same thread.Lets the two approaches bleed into each other and bloats the context unnecessarily.
• Start two fresh sessions and manually summarize yesterday's findings into each.Hand-written summaries lose detail and duplicate effort.

Situation

An agent has already analyzed a 23-file service, understanding its request flows and error patterns. Now two different testing strategies — end-to-end with mocks, versus snapshot tests — need to be developed independently for comparison.

Recommended approach

Resume with a session fork, giving each testing strategy its own branch.

Why it works

Both strategies should build on the same 23-file analysis but stay independent. Forking gives each strategy its own branch seeded with the full prior context, with no re-reading and no interference between them.

Weaker approaches people try — and why they fall short

• Export the key findings to a file, then create two new sessions that reference it.Exporting and re-seeding loses the rich in-context understanding and adds friction.
• Continue in the original session, doing one strategy fully before starting the other.Sequential work in one thread entangles the two strategies and grows context unnecessarily.
• Start two fresh sessions that each re-read all 23 source files.Re-reading 23 files twice is wasteful and starts from zero understanding both times.

Situation

Investigating untested paths across a 45-file payment module. After about 8 files, accuracy starts dropping — the agent forgets earlier patterns and hasn't yet found all the test files or traced the critical flows.

Recommended approach

Spawn subagents for specific narrow questions (find all the test files, trace the refund dependencies) while the main agent coordinates and keeps the high-level picture.

Why it works

Context is overflowing. Each subagent gets a fresh window to answer one narrow question and returns a concise result, so detailed exploration happens in disposable contexts while the coordinating agent preserves the overall understanding.

Weaker approaches people try — and why they fall short

• Summarize findings, clear the context, and use the summary report as the sole reference going forward.A single summary as the sole reference loses detail that's still needed and forces re-discovery.
• Clear the context, then selectively re-read critical files while writing findings to a scratchpad file.Helps, but is more manual and still reloads a lot of detail back into the main context.
• Switch to keyword search only, to reduce how much content gets loaded.Reduces tokens but sacrifices the deep understanding that tracing flows actually requires.

Situation

An exploration subagent spent 30 minutes across 47 files documenting data flows, then got interrupted. Meanwhile, a merged pull request renamed two utility functions. The exploration needs to continue.

Recommended approach

Resume the subagent from its transcript, and explicitly inform it about the two renamed functions.

Why it works

Resuming preserves the full 47 files of accumulated context. The only actual change is two renamed functions, so resuming and naming those two renames keeps everything else intact while correcting the one factual drift precisely.

Weaker approaches people try — and why they fall short

• Start a fresh subagent with only a summary of the prior findings.A summary loses most of the detailed data-flow context that was already built up.
• Start a fresh subagent with the prior transcript pasted into the initial prompt.Re-feeding the whole transcript into a fresh agent is redundant when resuming does the same thing more directly.
• Resume without mentioning the renames, since the overall architecture understanding still holds.Leaves the agent reasoning with outdated function names.

Situation

A customer returns 4 hours later to the same dispute. The old 32-turn session still has a stale 'pending' status recorded from a tool call; on resume, the agent keeps citing that outdated status even after fresh tool calls return updated information.

Recommended approach

Resume with the full history, plus a system instruction to always prefer the most recent tool result whenever the same tool has been called more than once.

Why it works

The goal is to keep conversation continuity while making sure current data wins. Resuming with full history plus an explicit instruction to trust the newest duplicate tool result resolves the staleness directly while preserving everything else — targeting the exact failure (old data vs. new) without discarding useful context.

Weaker approaches people try — and why they fall short

• Resume, but filter out all previous tool-result messages so the agent is forced to re-fetch everything.Loses useful context and forces re-fetching everything, not just the specific stale bits.
• Start a brand-new session and inject a structured summary of the issue, actions, and status before making fresh tool calls.Discards a rich 32-turn history unnecessarily when the fix could be much smaller.
• Resume and automatically re-call every previously-used tool at the start of the session.Wasteful, and may re-run tools that aren't even relevant to the current question.

Situation

Three separate issues have unfolded over 45 turns of a conversation — a refund, then a subscription question, then a payment update. At turn 48, with context nearly full, the customer asks 'what happened with my refund?'

Recommended approach

Extract and persist the key structured facts for each issue — order IDs, amounts, statuses — into a separate, durable context layer as the conversation goes.

Why it works

To keep all three issues answerable even as context fills up, the key structured facts per issue need to survive independently of the raw transcript. Those compact records let the agent answer 'what happened with my refund?' precisely, even after the original turns describing it have aged out of the window.

Weaker approaches people try — and why they fall short

• Rely on tools to re-fetch information on demand whenever an earlier issue gets referenced again.Only works if a tool can actually retrieve it and the right identifiers are still known — exactly what risks being lost.
• Use a sliding window that keeps only the most recent 30 turns.A 30-turn window would drop the refund issue (turns 1 through 15) entirely — the very thing being asked about.
• Summarize earlier turns into a narrative, keeping full history only for the currently active issue.A narrative summary is lossy and less reliable than structured fields for exact IDs, amounts, and statuses.