A coding assistant can appear productive while reading the wrong files, editing unrelated modules, or forgetting the constraint that made a change necessary. Working safely in a large repository is partly a tool-selection problem and partly a context-management problem. Claude Code offers operations for discovering files, reading source, making precise edits, and running controlled commands. A reliable workflow decides which tools to use, how to bound the search, what durable notes to keep, and when an interrupted session can resume without repeating harmful work.

A large-repository change tests two distinct Architect Foundations skills: finding the right code and preserving reliable task state as the working context changes. The assistant must distinguish a search result from evidence that the correct file was edited. Record the accepted revision, inspected paths and validation results outside a transient conversation; otherwise a later session can confidently continue from an outdated premise.

Start with an acceptance criterion, not a broad search

Suppose a service occasionally stores an invalid country code when importing customer records. A weak instruction asks the assistant to scan the entire monorepo and fix whatever looks related. A stronger assignment identifies the observed failure, affected input contract, authorized directories, expected valid values, tests, and a constraint not to change unrelated behavior. The assistant can then search for the specific validation function and its callers rather than reading every file that contains the word customer.

Write down what would prove the repair is correct: an invalid code is rejected consistently, existing valid imports still work, and no migration or configuration change occurs outside scope. Without such criteria, the assistant can produce a plausible code diff and still leave the original bug unresolved.

Choose discovery tools by the question

Glob is useful when file paths follow recognizable patterns, such as validation tests or configuration files. Grep narrows the search to code that references an exact function or error message. Read inspects selected content. Edit and Write change files, but they should enter the workflow after the relevant tests and existing conventions are understood. Bash can run approved build or test commands when configured and authorized; broad shell access should not be treated as the default response to every repository question.

Using a dedicated file-search tool makes the search intent visible in an audit. If the agent needs to understand a call chain, first locate a symbol, then inspect its definition and representative callers. If a command could delete files, install dependencies, contact external services, or print secrets, review its side effects and privileges before running it. Tool availability and permission are distinct from task necessity.

A practical exploration pass

For the country-code defect, begin by locating import-related paths. Read the validation helper and the nearest tests, then search for all places that construct the related data object. If multiple services use the same helper, trace whether the requirement should be applied centrally or only at one entry point. Record the relevant paths, expected invariant, and test command in a small task note.

Do not ask the model to hold entire files in conversation when a small excerpt and a stable file path are sufficient. Preserve exact test names and error output when a failure needs debugging, but discard noisy console logs after extracting the relevant line and a reproducible command. Context management is selective retention, not indiscriminate deletion of evidence.

Direct execution versus a planning phase

A one-line text correction with an obvious test may not need a lengthy plan. A change spanning validation, database schema, API responses and a consumer service should begin with a plan identifying dependencies and rollback points. A plan is useful when it reduces uncertainty about execution order or protects a high-impact boundary. It is not an excuse to generate pages of generic steps before touching a simple file.

During planning, distinguish facts already verified from hypotheses. The assistant may discover two similarly named validators. It should read both and explain which one handles the failing path before choosing a patch. A good plan names actual repository modules and tests; “review code, implement fix, test solution” without specifics adds little value.

Make changes small and verifiable

Prefer the smallest coherent edit that satisfies the observed requirement. After editing, run the relevant unit tests, then any affected integration checks. Review the diff for unintended changes, unneeded formatting churn, accidental secrets, or removal of behavior relied on by callers. A passing unit test is not proof of deployment readiness when the change also affects serialization or authorization.

The assistant should report what it changed, which checks passed, which were not run and what remains uncertain. If a test runner cannot execute because dependencies are unavailable, record that as NOT TESTED rather than reporting success from inspecting code alone. For a security-sensitive path, ask for the required reviewer or approval before treating the work as complete.

Context windows are not durable task state

Long code investigations can exceed the useful conversation context. A summary generated during compaction may omit why a design was chosen or which commands already changed files. Protect important facts in a durable checkpoint: the current task, verified root cause, relevant paths, accepted decisions, applied edits, tested behavior, unresolved questions and next safe action. Give each item a stable reference that can be checked against the repository or execution logs.

Distinguish an observation such as “test_import_invalid_country failed before the patch” from the conclusion “the validator is the root cause.” The latter remains a hypothesis until supported by traceable code paths and tests. A future session must not inherit model guesses as immutable facts merely because they appear in a compact note.

Resume and fork deliberately

Claude Code and the Agent SDK offer session mechanisms that can support resumption or branching. A resumed conversation should start from the latest verified source code state, not simply replay every model action. Read the current diff and relevant test results before executing another write. If a branch of investigation evaluates a different architecture, record which decisions and changes are shared and which are specific to that branch.

Forking is useful when comparing alternatives, but it creates a risk that one branch’s tests are mistaken for another’s. Assign distinct branch or session identifiers, checkpoint the starting revision, and document the artifacts created in each. A successful result from one branch does not authorize applying its changes to the other without comparison and review.

Preserve state outside the model when reliability demands it

For a longer refactoring project, a task manifest can contain source revision, objective, permitted directories, modified files, tool actions with IDs, test results, rollback instructions and reviewer state. Store it in a location the next authorized worker can read. That record should not automatically expose confidential files to every subagent. Use restricted access and references to protected artifacts where appropriate.

A model-generated narrative is useful for understanding progress, but a code review needs authoritative evidence. Record test commands and their actual output status; use a repository diff to identify changed files; keep tool identifiers to prevent accidental duplicate operations. When one external operation returned an ambiguous result, check the authoritative state before trying it again.

Delegation and context boundaries

An Explore-style subagent can investigate a narrow subsystem and report relevant files, tests and observations. It should receive a bounded task rather than “understand everything.” The parent agent can then decide whether the findings justify a change. Keep source references and paths in the handoff, especially if several specialists examine different parts of the repository. A summary that omits which file supports a conclusion is difficult to trust.

Subagents do not automatically share all context. Their isolation can improve focus, but a coordinator needs explicit packets containing required facts, permissions and expected output. If a tool is only required for searching, there is no reason to give that subagent a production deployment credential or permission to modify unrelated files.

Worked recovery: a failed integration test after compaction

Suppose the assistant updates the country-code helper and unit tests pass, but an integration test times out when the environment refreshes. A session compaction occurs. The checkpoint preserves the starting revision, touched files, exact unit-test results, integration command, timeout status and the fact that the integration outcome is unknown. The assistant must not resume by announcing the entire task is complete or by immediately rewriting another module.

A safe recovery begins by checking the working tree and rerunning or inspecting the timed-out test within the approved budget. If a previous migration or external write may have occurred, reconcile the corresponding service state before repeating it. The final report distinguishes verified passed checks, verified failed checks, and checks that could not complete. The original requirement remains the acceptance criterion throughout the recovery.

The important choice in this failure is not whether Claude Code can remember a summary; it is which observations must be refreshed before another edit is safe. Give the resumed agent a checkpoint whose last tested revision differs from the current working tree, and require it to identify the mismatch before modifying code. It should preserve verified unit-test evidence but label the interrupted integration run unknown until checked again. In an independent CCA-F preparation scenario, compare a blind rerun with checking the changed repository revision and reconciling the interrupted integration test. The defensible answer uses repository state, prior test evidence and edit authorization; a longer prompt cannot certify a stale checkout. A summary can support continuity, but it cannot certify present filesystem or test-runner state.

Common failure patterns worth testing

Test a search that returns too many unrelated files, an edit attempted outside an allowed directory, a missing configuration file, a unit test that passes but integration behavior that remains unknown, and a resumed session that sees a different source revision. Verify that the assistant narrows the search, respects authorization, identifies missing evidence, and stops rather than guessing the next write.

Another useful test is deliberate contradictory context: a durable requirement says country codes must be uppercase, while a recently retrieved file comment suggests lowercase. The assistant should locate the authoritative input contract and call out the conflict before changing behavior. Retrieved comments are not a substitute for approved system requirements.

The architectural decision

Before accepting a Claude Code change, collect the repository revision, files actually read, allowed directories, the source diff and the checks that exercised modified behavior. A resumed session must recheck its working tree instead of treating old conversational context as proof that files remain unchanged. Check how Claude Code project memory and subagents load and isolate context when implementing this workflow; configuration and delegation behavior can change between versions. The final report must distinguish executed tests from suggested tests and unknown outcomes.