The Day After a Big Refactor, Your CLAUDE.md Becomes a Liability

Drift is usually gradual — a path here, a renamed module there, accumulating over weeks. A large refactor skips the gradual part. It invalidates your CLAUDE.md all at once, overnight, because the entire point of a refactor is to change structure, names, and patterns — which is precisely what the file documents. The PR merges, everyone moves on to the next thing, and your grounding document is now a detailed, confident description of a codebase that no longer exists.

The overlap is the whole problem

What makes a refactor uniquely destructive to CLAUDE.md is that the two describe the same things. This is not bad luck; it is structural:

A refactor changes exactly what CLAUDE.md describes

  CLAUDE.md typically documents:        A refactor typically changes:
    -> module layout & file paths          -> module layout & file paths
    -> naming conventions                  -> names everywhere
    -> the patterns to follow              -> the patterns themselves
    -> where things live                   -> where things live

  The overlap is near total. The refactor is, definitionally,
  an edit to the thing the file is about.

A bug fix might touch a line the file never mentioned. A refactor touches the file's entire subject matter. The bigger and more valuable the refactor — the one that finally untangles the architecture — the more completely it invalidates the document describing the old architecture.

What Monday looks like

The gap does not announce itself. It surfaces the first time someone leans on the agent after the merge:

The day after the merge

  Friday   refactor merges: services/ flattened into modules/,
           UserRepo -> UserStore, REST controllers -> RPC handlers
  Friday   CLAUDE.md still says services/, UserRepo, "REST controllers"
  Monday   teammate asks Claude to "add a method to the user repo"
           -> Claude reads CLAUDE.md, looks for UserRepo in services/
           -> recreates the old pattern the refactor just removed
           -> a clean PR that re-introduces what you deleted

This is the cruelest version of remembering wrong: the agent does not just fail to find the new code, it confidently rebuilds the old pattern you spent a sprint removing. The refactor's value leaks back out one well-intentioned PR at a time, each one grounded in a file that froze the day before the change.

The update never makes the PR

In theory you update CLAUDE.md as part of the refactor. In practice the refactor PR is already enormous, the file is not part of the build, and updating prose about the change feels like a chore next to shipping the change. So it slips. And because nothing breaks when the file is wrong, there is no failing check to catch the omission. The one moment you most needed the document to keep pace is the moment it is least likely to.

Grounding has to re-derive, not be re-typed

The only grounding that survives a refactor is one that comes from the code itself and regenerates when the code changes — so the refactor that rewrites the codebase also rewrites the context:

Snapshot vs. re-derived grounding

  CLAUDE.md:
    -> a snapshot taken before the refactor
    -> only a human edit makes it match the new code
    -> until then, it actively describes the deleted version

  Semantic index:
    -> re-derived from the post-refactor source on merge
    -> the new layout, names, and patterns ARE the grounding
    -> nothing to remember; the refactor updated the context

When the grounding is re-derived from the post-merge source, the new layout, the new names, and the new patterns are the context the moment the refactor lands. There is no window where the agent is working from the deleted version, because there is no separate document to fall out of sync.

Where Kognita fits

Kognita re-indexes your repositories as changes merge, so a refactor updates the agent's grounding as a side effect of merging — no separate documentation PR, no chore that slips. The day after the merge, the index already reflects modules/ instead of services/, UserStore instead of UserRepo, the RPC handlers instead of the REST controllers. The agent extends the refactor instead of quietly undoing it.

Final take

A refactor and a CLAUDE.md are about the same thing — structure, names, patterns — so the better the refactor, the more thoroughly it invalidates the file. And the update that would fix it is the one most likely to be skipped under the weight of the PR that caused the problem.

If your grounding has to be re-typed after every refactor, it will be wrong after every refactor. Context that re-derives from the code updates the moment the code does.