Keeping Claude Code Refactors Consistent Across Long Sessions

During a long Node.js refactor, Claude Code added my async/await convention to the project instructions and then used .then() chains in the remaining files. The review needed to connect the written rule to every affected change.

I was migrating a Node.js codebase from callbacks to async/await. Early in the session, I established the pattern: use async/await consistently and wrap legacy callback APIs with util.promisify. My constraint for that project was to keep the original function signatures while changing the implementation.

The work spanned dozens of files and a long conversation. Eventually, Claude Code compacted older context into a summary. The callback conversions were correct, but the final batch of files used .then() chains. Those chains were valid JavaScript; they violated the convention we had established hours earlier.

September 2026 update: This revision adds current Claude Code instruction guidance and a locally tested Node.js example.

The rule was recorded and then missed

  1. I established the async/await convention in conversation.
  2. Claude acknowledged it.
  3. We continued refactoring dozens of files.
  4. Context compacted.
  5. I asked to add the convention to CLAUDE.md.
  6. Claude added it correctly.
  7. Claude continued refactoring the remaining files using .then() chains.

The irony was hard to miss: Claude was documenting the very convention it was violating.

Compaction came before the request to update CLAUDE.md. A summary produced at step 4 could not have recorded the later file update. Context loss was my explanation, but the sequence alone does not distinguish an omitted detail, an instruction that did not load, and an instruction that was present but not followed.

CLAUDE.md is a Markdown file for project instructions. Saving a rule there creates a durable record. Checking that the relevant instructions reached the session, and checking that the code follows them, are separate parts of the review.

What compaction preserves

The context window holds the material available for a response, including instructions, conversation and file contents. As it fills, Claude Code can clear older tool output and summarize conversation history. A summary can omit a detail needed for the next change. Anthropic's explanation of Claude Code describes this process.

MaterialWhat the documentation says happens
Project-root CLAUDE.md and rules without a path filterRead from disk again and supplied to the session
Nested CLAUDE.md and rules scoped to matching pathsLoaded again when Claude reads files that trigger them
System prompt and output styleRemain applicable

These mechanisms are documented in what survives compaction. A missed rule does not, by itself, show that the rule disappeared. The documented loading mechanism and the resulting code both need inspection.

Consider an illustrative rule: “Use async/await in promise consumers, except that these legacy public APIs must retain callbacks.” A summary that retains only “use modern async patterns” loses the exception and the application scope.

An early instruction mentioned once may be absent from a later summary. Restating the requirement in the next request makes that task's constraint explicit; check the resulting code to see whether it was followed.

Keep the convention attached to the work

  1. Write the rule and its exceptions before the refactor spreads. Keep recurring guidance in the appropriate CLAUDE.md or a clearly referenced project document. Name the scope: promise consumers use async/await; designated callback APIs keep their existing caller contract. An arbitrary documentation file needs to be supplied or read explicitly. Its presence in the repository does not give it CLAUDE.md's loading behavior.

  2. Restate the constraint when a new phase begins. When work resumes after compaction or moves into another subtree, bring the relevant convention into the current request. Check /context under Memory files for the instruction paths actually loaded. For files enabled by the instruction settings and not excluded, root and ancestor guidance loads at startup; nested guidance loads when the relevant files are read. If an expected path is missing, check the instruction settings and exclusions.

  3. Make consistency an explicit task over a named file set. Ask for the pattern to be checked in every modified file, including changes made before the rule was added. Include exceptions and the tests that establish the caller's expected behavior. “Continue the refactor” leaves more implicit than a task that names the remaining files and their acceptance checks.

  4. Inspect the changes before committing. A literal search for .then( can locate chains to review. Read each hit in context, inspect the complete changed-file set and check intentional callback boundaries. Then run tests for the behavior being changed. A search cannot establish when an operation completes or how it reports failure.

  5. Use a new instruction as a checklist for work already in progress. When adding a convention to CLAUDE.md, compare it with the current diff immediately. If an existing change violates it, correct that change and run the relevant checks before treating the task as complete.

For the worked example below, a phase-boundary request could read:

Read CLAUDE.md and both files in changed-files.json. Identify the callback boundary that must remain. Use async/await in the promise consumer, retain the callback method's receiver, and check the convention across both files. Run the behavior tests and report their results.

Writing the convention earlier would have preserved its wording. Restating it would have made it explicit again; a consistency task would have named its application scope. A search could have located the specified chains.

Check the refactor's behavior

Keeping the argument list is only part of preserving a function's interface. A callback API and a promise-returning function deliver their results differently. An error-first callback receives an error as its first argument on failure, or null followed by the result on success. Node's util.promisify creates a promise-returning wrapper around the usual form with that callback as the final argument. A method that uses this also needs its receiver preserved.

The downloadable refactor example is constructed for this article. It uses an in-memory job store and runs locally; it is not the original project's code or a Claude Code compaction experiment.

The store retains save(id, callback). With a callback supplied, it returns undefined immediately, then invokes that callback once on a later turn. The new consumer has a separate promise interface:

import { promisify } from 'node:util';

export async function saveJob(store, id, notify = () => {}) {
  if (typeof notify !== 'function') {
    throw new TypeError('notify must be a function');
  }
  const saveAsync = promisify(store.save.bind(store));
  await saveAsync(id);
  const receipt = { id, status: 'saved' };
  notify({ ...receipt });
  return receipt;
}

bind(store) keeps the method attached to the object whose prefix and records it uses. await saveAsync(id) waits for the in-memory write before calling the synchronous observer notify. For job-7, the stored row is {id: 'job-7', label: 'queue:job-7'} and the returned receipt is {id: 'job-7', status: 'saved'}. The observer must see that row when it is called.

If the store rejects the ID blocked, the consumer must reject with code E_WRITE and message Cannot save blocked, without notifying the observer. If the observer itself throws, the consumer rejects after the write has completed. The example does not roll that write back.

After extracting the folder, run the four commands from inside it:

node demo.mjs
node search-demo.mjs
node --test --test-reporter=tap refactor.test.mjs
node verify-controls.mjs control-results

The first command prints the receipt, row and notification state. The second searches the declared changed files and a separate demonstration file. The third runs the behavior tests. The fourth keeps a passing baseline and three deliberately faulty copies, then runs the unchanged tests against each copy:

Deliberate changeBehavior the unchanged test rejects
Remove the await before the writeThe observer is called before the row is present
Swallow the callback errorThe consumer reports success instead of rejecting
Remove the method's receiver bindingThe receiver-dependent call fails when it reads the prefix

The 13 named tests passed on Node.js v26.8.2 from both the source folder and a clean extraction of the ZIP. Each faulty copy failed its designated behavior test. The control command returns success only when the baseline passes and those failures occur; it retains the altered files and complete test output in a new directory. Other Node versions were not executed for this package.

The search demonstration produces three matches: a comment, a string and an actual chain. It misses the equivalent computed access promise['then'](...). All three faulty consumer copies contain no .then( text. The omitted await and swallowed error still break the contract. These are checks of specified faults, not a measurement of how many bugs a search or a test suite catches.

The archive's CLAUDE.md records the convention, its callback exception and the required checks. No native Claude Code session was used to establish whether that file loaded or influenced a response. The demonstrated result is the local behavior of the JavaScript and its tests.

Review the whole changed-file set

Long refactors, extended debugging and multi-part features need checkpoints as the task moves between files and phases. A short exchange can also miss an instruction even when the conversation fits in the context window. Keep durable requirements available, then inspect their application to the work being accepted.

  • Is the convention consistent across all affected changes? Review the named file set and its intentional exceptions, including earlier batches.
  • Did behavior drift from an early instruction? Compare the earlier and later changes. Check which guidance was available before treating compaction as the explanation.
  • Was the rule explicitly connected to the task? Name the files and the outcomes to verify. In the example, that means checking that the observer sees a completed write, errors reach the caller and the callback API remains usable.

CLAUDE.md files, project documentation and explicit task lists are context infrastructure for reliable work across sessions, compaction events and the natural gaps in a long conversation.

Trust the capability. Design for the architecture.


This article is part of the synthesis coding series. For the loading mechanisms in more detail, see How Claude Code Uses CLAUDE.md and Memory.