Git worktrees are wonderful. They let you have several branches checked out at once in separate folders, so you can hack on a feature in one and hotfix in another without the constant stash-juggling. We use them. We like them.

We like them slightly less since the day we realized a worktree had been quietly operating on a stale copy of the rulebook for who-knows-how-long.

The setup

We keep project instructions in CLAUDE.md at the repo root — conventions, gotchas, the hard-won “never do this again” list. Living document. We update it often.

Worktrees, created at points in time, contain their own copy of the files as they were when relevant — including copies that live under .claude/worktrees/*/CLAUDE.md. And here’s the thing nobody internalizes until it bites: updating the root CLAUDE.md does not reach into existing worktrees and update theirs. Why would it? They’re separate working directories. Git doesn’t run around syncing untracked-context files for you.

So you add a shiny new rule to the root — “billing tokens stay lowercase end-to-end,” say — feel great about it, and meanwhile a long-lived worktree three folders over is still reading the version from two months ago, blissfully unaware, confidently doing the old wrong thing while citing the rulebook.

Why it's sneaky

This isn’t a crash. There’s no error. There’s just a slow, silent divergence of context. The worktree behaves correctly according to the rules it can see — they’re just not the current rules. It’s like leaving a sticky note on the fridge and being surprised the person who moved out last year didn’t follow it.

The damage is proportional to how long the worktree lives and how much the rulebook drifts. A throwaway worktree you delete in an hour? Fine. A worktree you’ve been nursing a big feature in for three weeks? It’s running on increasingly ancient law.

The fix

There’s no magic here, and that’s the point — it’s a discipline, not a feature:

  • For long-lived worktrees, manually copy the root CLAUDE.md in when you update the root. One command, periodically:
    cp ./CLAUDE.md .claude/worktrees/my-feature/CLAUDE.md
  • Treat worktree context files as caches, not sources. When in doubt about what the rules say, check the root, not the worktree’s copy.
  • Prefer short-lived worktrees. The shorter they live, the less the rulebook can drift out from under them.

The moral

  • Copies don’t subscribe to updates. Any file you duplicate into a worktree (or a fork, or a vendored dependency, or a snapshot) is frozen at copy time and will silently rot relative to its source.
  • The most dangerous staleness is the kind with no error message — where everything “works,” just against an outdated definition of “right.”
  • When you have one source of truth and N copies of it, you have N opportunities for divergence. Either automate the sync or build the habit of refreshing by hand.

Your worktree isn’t disobeying the rules. It just never got the memo — because nobody sent it one.

Amit Jethva is the CTO and co-founder of Nuvika Technologies Pvt Ltd, makers of Fintropy, a multi-cloud FinOps platform. Learn more at nuvikatech.com.