CLAUDE.md Doctor: Auditing Your Project Instructions

A CLAUDE.md file starts small and grows. Over time, it accumulates instructions, task history, debugging notes, temporary rules from last month's sprint, and half-remembered context that nobody has verified recently. When that happens, Claude Code reads everything equally, which means the standing rule about how authentication works competes for attention with a note about a one-off exception from three weeks ago. Tools like fenbs keep the changing work records outside the instruction file, so CLAUDE.md stays focused on what is always true.

Auditing a CLAUDE.md is not a one-time cleanup. It is a habit: review it when a session produces surprising results, when a new person joins the project, or whenever you notice Claude Code working against rules you thought you had established.

What belongs in CLAUDE.md

CLAUDE.md is for stable, project-wide instructions that Claude Code should read and apply in every session. That includes the architecture overview, the coding conventions, the testing approach, and the commands that set up and verify the project.

It is not a task list, a change log, a decision history, or a place to store progress notes. Those belong in the tool that tracks the work. When they live in CLAUDE.md, they make the file longer, harder to scan and less reliable as a source of instructions.

The CLAUDE.md examples guide shows what well-structured project instructions look like. The CLAUDE.md hierarchy guide explains how Claude Code loads multiple CLAUDE.md files in a project and which takes precedence.

How to use available diagnostics

Claude Code includes a diagnostic mode that can tell you how it is reading your CLAUDE.md. Ask it to summarize the instructions it loaded at the start of a session. Compare that summary to what you intended. If something is missing from the summary, it may not be getting read. If something in the summary surprises you, investigate where it came from.

You can also ask Claude Code to list all the CLAUDE.md files it found in the project. A large project may have several, and they can conflict. Ask Claude Code which instruction takes precedence when two files say different things about the same topic.

For problems with CLAUDE.md not having the effect you expect, the CLAUDE.md not working guide covers the most common failure modes and how to diagnose them.

A systematic audit of an overloaded CLAUDE.md

Read through the current file line by line and ask one question about each entry: does this instruction apply in every session with this project, regardless of the specific task?

• If yes, and it is accurate today, keep it.
• If yes, but it is out of date, update it or delete it.
• If no, because it is task-specific progress or a temporary rule, move it to the work record.
• If uncertain, ask someone who knows the project whether the instruction still applies.

After the audit, read the result as a new contributor would. Can they understand the project architecture from this file? Do the instructions tell them what to do without making them guess? Is anything so long that the important rules get buried?

What to move out and where to put it

Task progress notes belong in the task record. Move them to the active task in your work tracking tool, with the current state and the next step.

Decisions that a person made belong in a record a person maintains. Move them to Decisions and rules in fenbs, with the person who decided, the reason and the date. The next Claude Code session reads them from fenbs as part of the project context, so removing them from CLAUDE.md does not mean the assistant stops seeing them.

Lessons from debugging sessions belong in Lessons learned in fenbs. A lesson like "always check the migration log before assuming a schema change applied" is more useful as a lesson than as a buried paragraph in CLAUDE.md.

How to prevent CLAUDE.md from growing back

At the end of each Claude Code session, resist the temptation to add session-specific notes directly to CLAUDE.md. Put task progress in the task, put decisions in Decisions and rules, put lessons in Lessons learned. Reserve CLAUDE.md for additions that genuinely belong there: a new library, a changed architecture rule, a command that was added to the project.

A short review at the start of a new month is easier than a full audit after a year of growth. The goal is a CLAUDE.md that a new contributor can read in ten minutes and understand the project well enough to start working.

How to do this with fenbs

1. Create a free account and add the project. As you audit CLAUDE.md, move each decision into Decisions and rules in fenbs and each lesson into Lessons learned.
2. Connect Claude Code over MCP from Integrations. At the start of the next session, ask it to read the project context from fenbs. It reads the decisions and lessons you moved there, even though they are no longer in CLAUDE.md.
3. Keep CLAUDE.md focused on stable instructions: architecture, conventions, commands. Let fenbs carry the changing records.
4. When a session produces surprising results, check both CLAUDE.md and the fenbs project context. The surprising instruction may be in either place.
5. Add a note in CLAUDE.md that says "Decisions and rules, lessons and task progress are in fenbs at [link]." That tells any Claude Code session where to look for the full context.