Keeping CLAUDE.md current as your research changes

The short answer: regenerate on events rather than on a schedule — when new sources change a conclusion, when a decision is reversed, or when a section stops matching the code — and delete as much as you add, keeping a source citation on every non-obvious claim. Staleness in a context file is worse than absence, because an agent treats it as authority.

Most teams write a project context file once, in the enthusiasm of week one, and then never touch it. Three months later it describes a target user who was refined away, a stack decision that was reversed, and a feature list that includes two things now explicitly out of scope. The coding agent reads all of it as current fact and builds accordingly.

A context file has authority the codebase does not

Ordinary documentation goes stale and readers compensate: a human who finds a README describing a deleted module shrugs and reads the code. An agent does the opposite. It weights an explicit statement of intent above the ambiguity of implementation, because that is precisely what the file exists to resolve.

The practical consequence is that a wrong line in a context file is more expensive than a missing one. Missing context produces a question or a conservative inference; wrong context produces a confident branch of work aimed at a decision you already abandoned, and the mistake spreads to every file touched in that session. That asymmetry is the entire argument for maintenance, and it builds on the structure covered in how to write a CLAUDE.md.

Durable context in, transient status out

The single most useful editorial rule is a time horizon test: would this line still be true in three months if the project went well. Mission, target user, product direction, non-goals, risk rules and hard constraints pass it. Current sprint, open bugs, this week’s blockers and half-finished migrations do not.

Transient content is what makes a file feel wrong within weeks, and it is also what makes people stop trusting the durable parts. Once a reader has found two obviously stale lines, they discount everything else in the file, including the sections that are still exactly right.

The three events that should trigger a rewrite

New evidence changes a conclusion. A research pass that adds five sources and confirms everything needs no rewrite. One that contradicts a stated direction needs the direction line changed the same day, before anything is built against it.

A decision is reversed. Reversals are where files rot fastest, because the reversal happens in a conversation and the file is never told. Any decision recorded in the file should be treated as owned by the file: changing it in practice means changing it there.

The code stops matching. When the agent starts producing work that contradicts the file, the correct first suspicion is that the file is wrong, not the agent. That is usually the cheapest bug report a team gets about its own documentation.

Cite the source of every non-obvious claim

A claim like “buyers in this segment will not adopt a tool that requires an admin to install it” is enormously consequential and completely unverifiable a month later unless it carries its source. With a citation, a future reader can watch two minutes of video and either confirm it or retire it. Without one, the team re-argues the point from memory and whoever is most confident wins.

A workable minimum is source title, link and the moment the claim came from. That habit is the same one that makes research shareable at all — the argument in sharing research with your team — and it is what separates a research artefact from a set of opinions, as covered in summarisers that keep timestamps and citations.

# Product Direction
Lead with the reconciliation step, not the import step.
Practitioners describe import as annoying but reconciliation as
the part they stay late for.
  - src: "Month-end close, start to finish" (23:10) — 3 of 14 sources
  - contradicted by: "Fast import workflow" (07:40) — 1 of 14
  - decided 2026-09-04, revisit if 2+ new sources contradict

The counter-evidence line matters as much as the supporting one. A direction recorded with its dissent is one a future reader can evaluate; a direction recorded as consensus invites nobody to check whether the consensus was three voices or thirty.

Deletion is the maintenance most files never get

Context files grow monotonically because adding is easy and removing feels like losing information. The result is a file long enough that the agent must prioritise inside it, and the parts it prioritises are not necessarily the parts you would.

Two removal rules keep it in check. First, a resolved open question is replaced by its decision rather than kept alongside it — the question is now noise. Second, a section that has not informed a decision in two months is a candidate for deletion; if it turns out to matter, the research that produced it still exists and it can be regenerated in minutes.

Make the refresh part of the research loop

The maintenance problem largely disappears when the file is an output of the research process rather than a document maintained beside it. If a recurring pass adds sources to the same project each month, the synthesis it produces is already the current state of what you know, and the context file is that synthesis in the shape an agent reads.

That is the practical case for keeping research in one place long enough to be re-run — the monitoring pattern in monitoring a niche with recurring research — and the reason the same corpus should also feed the specification work described in turning research notes into a coding-agent spec.

A five-minute monthly review

The whole discipline fits into a short recurring review, and doing it badly on time beats doing it well eventually. Read the file top to bottom and mark each line with one of three verdicts: still true, now false, or no longer load-bearing. Fix the false ones immediately, delete the non-load-bearing ones, and note which conclusions are resting on a single source.

Single-source conclusions are the ones to schedule work against. Either find corroboration in the next pass or plan a conversation to settle it, using the interview approach in turning video research into an interview script. A conclusion that survives a year on one source has usually become an assumption without anyone deciding to promote it.

What the refresh costs

A monthly refresh is normally five to ten new sources and one synthesis rather than a fresh corpus. As of September 2026 that sits inside the Hobby plan at $19 a month, which covers 25 videos, 2 projects and 3 syntheses a month; Pro at $59 covers 80 videos, 8 projects and 6 syntheses; Studio at $199 covers 250 videos, 20 projects, 25 syntheses and 3 seats. Every plan starts with a 7-day free trial — details on the pricing page.

Closing thought

The test of a context file is not whether it reads well. It is whether someone who disagreed with a line in it could find the evidence, watch it, and change your mind in ten minutes.