How to Update CLAUDE.md Without Letting It Grow Forever

To update CLAUDE.md, identify which lasting project instruction changed, edit the existing rule, and verify the new wording against the repository and a fresh Claude Code session. Do not append every correction to the end. Tools like fenbs keep the lesson and the human decision behind a rule outside the instruction file, so you can shorten the file without losing its history.

A useful update makes the next session clearer. It might replace a broken command, narrow a rule to the work it actually concerns, or remove an instruction made obsolete by a code change. The goal is a reliable starting point, rather than an archive of everything an assistant once got wrong.

What is the safest way to make an update?

1. Read the current file and any project instructions it refers to. Identify the exact sentence that needs changing before proposing another one.
2. Find the evidence: a renamed script, a reviewed code change, a repeated failure, or a decision someone actually made. Separate an observed mistake from a proposed policy.
3. Rewrite or remove the existing instruction. Give the replacement a clear action and scope, then check for another sentence that now contradicts it.
4. Inspect the diff and verify the affected command or workflow. Use a safe environment; documenting a deployment command does not authorize running it.
5. Start a fresh session and try a small representative task. Record what loaded, what the assistant did, and which checks remain outstanding.

Keep unrelated instruction changes separate when possible. If a patch changes both the test command and the approval policy, a reviewer has two different questions to resolve. A focused update is easier to approve, explain, and reverse if its assumptions prove wrong.

For the file’s basic purpose, see the CLAUDE.md guide. This workflow is about maintaining an established file, rather than choosing every instruction it should contain.

Why does the file keep growing?

Adding a warning is easy after an unpleasant failure. Removing an older warning is harder when nobody remembers why it exists. Over time, the file can mix current conventions, temporary workarounds, finished tasks, and several versions of the same advice. Each addition appears reasonable on its own.

Imagine that an assistant edits a generated file. Someone adds “never edit generated files.” Later, another person lists five generated directories. A third adds a build recipe that repeats the restriction. The lasting instruction can become one sentence naming the generated boundary and the source files to edit instead. The incident belongs in the work record.

Anthropic’s instruction guidance↗ (opens in a new tab) recommends specific, consistent instructions and reviewing files for contradictions. Treat that as a reason to review the combined instructions, rather than judging the newest paragraph in isolation.

Which lines should stay, change, or leave?

Do not delete a safety boundary simply because it has not been needed recently. Check what it protects and whether the protection still matters. A restriction on live data may remain essential even after a particular database bug is fixed. If its owner or purpose is unclear, flag that uncertainty for review.

Keep the explanation for a removal in fenbs Lessons learned, alongside what happened and what should change next time. That makes the next maintenance pass less dependent on someone remembering an old conversation.

How do you turn a correction into a better rule?

Describe the action at the point where someone must choose. “Be careful with generated content” gives little help. “Edit the source records in content/data; regenerate the output with the documented script” names both the boundary and the correct alternative. Verify those paths before using that example in a real repository.

# Generated content
Edit source records in content/data.
Do not hand-edit content/generated.
Run the generation script named in package.json after source changes.
Report the exact validation command and result.

Avoid converting a single task preference into a permanent rule. A request to preserve one customer’s wording does not establish a writing policy for every project. Ask whether a future teammate would need the instruction without knowing this task. If the answer is no, keep it with the task instead.

Use CLAUDE.md examples to compare wording, but copy only conventions your repository actually uses. An attractive example is still a guess until you check the paths, commands, and authority behind it.

How can you tell whether the update worked?

Check both truth and behavior. A command can exist but fail from the directory the file names. A perfectly accurate paragraph can still be too vague to guide the next action. Test the command where appropriate, then give a fresh session a small task that reaches the changed instruction.

Anthropic’s Claude Code best practices↗ (opens in a new tab) emphasize giving Claude a way to verify its work. Apply the same principle here: define an observable result. For a generated-file rule, inspect whether the assistant chose the source file. For a test rule, inspect the reported command and actual result.

One successful attempt is evidence, not a guarantee. If the result is inconsistent, check for conflicting instructions before adding stronger language. The CLAUDE.md troubleshooting guide covers loading and instruction failures beyond the maintenance task.

How to do this with fenbs

1. Create a free account and add the project whose instructions you maintain.
2. Add a task for the instruction change. Describe the observed problem, the evidence, and the proposed verification in its plan.
3. Save the incident as a lesson. Ask a person to decide whether the proposed correction should become a lasting rule, then record their decision.
4. Connect a supported assistant through Integrations. Ask it to read the project context before proposing the file edit.
5. Save the actual validation result and Where we left off, including any unresolved approval. Keep the repository diff available for review.

fenbs does not enforce the contents of CLAUDE.md or automatically prove an edit correct. If you only need to correct one command in a small private repository, a reviewed file change may be enough. A shared work record becomes useful when several people or assistants need the reason, approval, and follow-up.

Make the next review easy: a short current rule in the repository, a clear explanation of why it changed, and an honest record of what was checked. More guidance on reusable instructions is collected in the AI prompts hub.