Persist findings with their file evidence

Learning objective

Persist verified file-specific findings and dependencies in scratchpads for later phases.

Core idea

For an architect exploring a large codebase, a durable finding is more useful than a remembered conversation. Persist the exact symbol, file, dependency, and evidence you established, then read that record before using the finding in another phase. This counters context degradation: answers become inconsistent with earlier findings and refer to “typical patterns” instead of the specific classes already discovered. Anthropic documents that performance degrades as the context fills; accumulated conversation, file reads, and command output can make earlier details less reliable to recall.

Anthropic describes structured note-taking as writing notes outside the context window and pulling them back into context later. A scratchpad implements that pattern with ordinary files. The filename and structure are yours to choose; a file called findings.md does not gain special loading behavior from its name.

See 5.4.1 for isolating verbose searches, 5.4.3 for reclaiming conversation space, and 5.4.5 for interrupted-run recovery. This lesson owns the evidence record those later operations depend on: what you know about a particular file and how another reader can verify it.

How it works

Record a finding when you establish it

Use Read to inspect source files, Write to create the scratchpad, and Edit to update an existing record. Claude Code documents these as file-reading, file-writing, and targeted-editing tools. Tell the agent which scratchpad path to maintain and when to update it; persistence should be part of the investigation assignment.

Save findings while the supporting code is available, before a long search moves attention elsewhere. A statement such as “refunds use the ledger service” loses the detail that makes it actionable. A stronger record names RefundLedgerService.post_reversal() in billing/rl_svc.py and identifies the caller or import that establishes the relationship.

The record should distinguish observed behavior from an interpretation. Finding an import establishes a source dependency; it does not by itself establish that a particular request executes the imported method. When you trace a call edge, record the call site as well as the callee. Keep the untraced edge open rather than smoothing it into a complete flow.

Preserve file-specific evidence and dependencies

Choose a compact format that lets a later phase recover the evidence. The following fields are an example scratchpad design, not an Anthropic schema:

Keep dependency direction explicit. “The admin route calls the ledger service” and “the ledger service calls the stock allocator” are different edges. A later question about restocking needs the second edge verified; knowing the first one does not complete the answer.

Line references help navigation, but the symbol and surrounding behavior matter when lines move. If a later edit changes the file, reopen the relevant passage with Read and update or invalidate the record. A scratchpad preserves an observation; it does not make that observation true for every revision.

Keep separate worker discoveries attributable when they disagree. If one report says a refund invokes allocation and another says restocking is separate, retain both evidence locations and reopen the relevant files. Replacing the first statement with the second without checking the edges leaves a tidy record with an unresolved factual conflict.

Make rereading part of the workflow

Put a concise standing instruction in the project-root CLAUDE.md when maintaining and consulting the scratchpad is a project-wide workflow. For example, require the coordinator to read the findings file before answering dependency questions and to update it after verified discoveries. See 3.1.1 for instruction scope and 5.4.3 for what survives compaction.

Keep the findings themselves in the scratchpad rather than expanding CLAUDE.md into a running dump of discovered code. Anthropic recommends keeping that instruction file focused on broadly applicable guidance. Your standing rule can point to the record and explain when to consult it.

Reading the file brings its content back into the model’s context. Persisting a thousand lines does not require loading all thousand on every turn. Organize the record by subsystem or question, then ask for the part relevant to the next decision. The durable file can hold more detail than the concise summary the coordinator uses for planning.

Explore cannot use Write or Edit, so the coordinator must persist its report; choose a writing-capable custom agent when maintaining the assigned scratchpad is part of the worker’s task (see 3.4.3).

Key distinctions and trade-offs

Scratchpad versus conversation: The scratchpad survives a context reset because it is a file. The conversation supplies immediate reasoning but is subject to summarization and accumulated noise.

Evidence versus conclusion: An exact caller and callee establish a particular dependency. A conclusion about all refund paths requires coverage of those paths, not only one representative method.

Persistence versus automatic retrieval: Writing the file saves it; Read or another deliberate loading step supplies it to a later phase. A file on disk that no agent consults cannot repair an answer.

More detail improves recoverability but increases rereading cost. Prefer precise, compact records with pointers to source passages. Preserve enough evidence to check a claim, while leaving repetitive searches and rejected leads in the discovery transcript.

Architecture / decision scenario

A developer productivity agent maps a legacy refund system in the morning. It verifies that admin/refunds.py calls RefundLedgerService.post_reversal() in billing/rl_svc.py. It also inspects jobs/restock.py and finds a separate stock-restoration path, but it has not yet checked every background-job caller of the ledger method.

The coordinator uses Write to create investigation/findings.md. It records both verified paths, their dependency edges, the inspected scope, and the unanswered background-job question. After further discoveries, it uses Edit to extend the record.

Later, after compaction, the engineer asks whether every refund immediately restores stock. The coordinator first uses Read on the relevant scratchpad section. It answers from the inspected paths, explains the unverified scope, and assigns the remaining caller search. If the working tree has changed, it reopens the affected code before repeating the morning’s conclusion.

The result is a precise answer with an explicit gap. A generic reminder to “always name classes” would not restore the file evidence needed to produce that answer.

Common exam traps

• Leaving exact class names and file paths only in early conversation turns.
• Writing broad conclusions without dependency direction or evidence locations.
• Treating a saved findings file as automatically loaded context.
• Assuming a record stays valid after the referenced code changes.
• Making Explore responsible for Write or Edit operations.
• Turning CLAUDE.md into a large transcript instead of a concise workflow rule.

What to remember

Persist verified symbols, locations, dependencies, coverage, and open questions in an ordinary scratchpad. Make writing and rereading explicit steps. Later phases should recover the code-specific evidence and verify its freshness before building on the conclusion.

Knowledge check

References

• Anthropic, Effective context engineering for AI agents
• Anthropic, Tools reference
• Anthropic, Best practices for Claude Code
• Anthropic, Create custom subagents
• Anthropic, Claude Certified Architect – Foundations Exam Guide