Let's grow CLAUDE.md with Anthropic's official claude-md-management plugin

When was the last time you reviewed your CLAUDE.md? Project build commands changed, the way tests are run changed, or the directory structure was reorganized. Are you keeping up with those changes every time? To be honest, I tend to neglect it. And by the time I realize it, a classic "common occurrence" happens: Claude Code starts doing the wrong thing because it's relying on outdated information.

The official claude-md-management plugin from Anthropic is a direct answer to this problem. Developed and maintained by Anthropic themselves (the creators of Claude Code), this plugin comes as a set: a skill that scores the quality of your CLAUDE.md and a command to incorporate learnings from a session into CLAUDE.md. You could call it a "housekeeper" for your CLAUDE.md.

In this article, I will introduce the contents of this plugin, how to install it, its actual usage, and best practices for how you should grow your CLAUDE.md.

Why the Freshness of CLAUDE.md Matters

CLAUDE.md is the "project manual" that Claude Code reads at the start of every session. By writing information that is hard to understand just by reading the code—such as build commands, architecture, and common pitfalls—Claude can start working with an understanding of the project's "vibe" from the very beginning.

However, this has a side effect. Since the contents of CLAUDE.md are sent as part of the prompt every time, outdated or redundant information can mislead Claude or waste tokens. It's a common story: while the code itself is constantly refined through refactoring, CLAUDE.md is left behind in its state from months ago.

The claude-md-management plugin is a tool designed to solve this "write-and-forget" problem through a systematic approach.

Two Tools: Inventory and Note-taking

This plugin contains two tools with different roles. Since they can be easily confused, let's clarify them first.

claude-md-improver is a skill that looks over the entire codebase and performs an "inventory" to see if the CLAUDE.md accurately reflects the current code. Think of it as a periodic health checkup.

On the other hand, /revise-claude-md is more for daily use—a command to take notes on "commands discovered or pitfalls encountered in today's session" and write them into CLAUDE.md on the spot. It might be easier to think of it as a "note-taker."

Both will ask for user approval before finally applying any edits, so there is no need to worry about CLAUDE.md being rewritten without your knowledge.

Installation

The claude-plugins-official marketplace is automatically enabled when you start Claude Code, so no additional preparation is required. You can install it simply by running the following inside Claude Code:

/plugin install claude-md-management@claude-plugins-official

If you want to browse and choose plugins, you can type /plugin, open the Discover tab, and search the catalog to install.

After installation, don't forget to run /reload-plugins. This will reflect the skills and commands in your current session.

Usage 1: Auditing with claude-md-improver

Since claude-md-improver is a skill, you don't need to memorize a specific slash command. You can trigger it just by asking Claude in natural language.

Audit my CLAUDE.md
check if my CLAUDE.md is up to date

A sentence like this is enough. Once the skill starts, the following workflow runs:

1. Search for all CLAUDE.md and CLAUDE.local.md files in the repository.
2. Score each based on six criteria and assign a grade from A to F.
3. Present a report and list specific improvement suggestions.
4. Ask for approval before actually applying the diffs.

By the way, when I type /claude-md, claude-md-improver appears as a candidate. Pressing the Tab key completes it to the command /claude-md-management:claude-md-improver, which I then execute.

Six Scoring Criteria

The scoring is based on a proper rubric. The total is out of 100 points.

What's interesting is that Conciseness is properly weighted. "Just write everything for now" will actually result in a point deduction. Since CLAUDE.md is read every time as part of the prompt, increasing the volume isn't necessarily better.

Scoring results are displayed in five levels from A (90–100) to F (0–29). When I run this skill, I often see B's and C's, which makes me realize how poorly I've been maintaining my CLAUDE.md and makes me appreciate the value of this plugin.

Usage 2: Incorporating Learnings with /revise-claude-md

After finishing a coding session, have you ever felt, "I didn't know this command today" or "This directory structure is confusing at first glance"? The command to pass that feeling on to the Claude of the next session is /revise-claude-md.

/claude-md-management:revise-claude-md

All plugin skills are called with a namespace. If you type up to /claude-md-management:, Tab completion works, so it's surprisingly easy.

When you run this command, Claude looks back at the current session and searches for "things that should be added" based on the following perspectives:

• Bash commands used or discovered
• Code style patterns followed
• Successful testing methods
• Environment or configuration quirks
• Pitfalls or warnings encountered

Furthermore, it even judges which CLAUDE.md it should be written to. For example, CLAUDE.md for team sharing, or CLAUDE.local.md for personal use.

Proposals are displayed in diff format, and the actual file won't be changed until you approve it. If you think something is a bit redundant, you can just reject it, so there's no worry about over-importing information.

CLAUDE.md Has Four Locations

While using this plugin, you'll realize that even though we say CLAUDE.md, there are several types. Let's organize them.

Claude Code automatically picks up and aggregates CLAUDE.md files from parent directories, so it works fine even if you place a CLAUDE.md in each package of a monorepo (a structure that combines multiple packages in one repository). This plugin also audits each CLAUDE.md individually.

Best Practices: How to Grow It

Since we're at it, I'll introduce the essence of "How to write a good CLAUDE.md" as gleaned from the plugin's update-guidelines.md.

What to Write

• Discovered commands: Commands you looked up on the spot, like npm run build:prod, should be kept for next time.
• Non-obvious patterns: Constraints that can't be understood just by reading the code, such as "Tests must be run serially with --runInBand."
• Relationships between packages: Dependencies like "The auth module must be imported after crypto initialization."
• Successful testing methods: Established patterns like "Use supertest for API tests."
• Configuration quirks: Environment-specific details like "Need to add ?family=0 to the Redis connection."

What Not to Write

• Things obvious from reading the code: Self-evident descriptions from class names, like "UserService handles user operations."
• Generalities: "Write tests properly" is not project-specific information and is unnecessary.
• One-time fixes: "Bug fixed in commit abc123" won't recur, so it's a waste to write it.
• Redundant explanations: Instead of explaining what a JWT is from an RFC, settle for a single line like "Auth: JWT HS256, Authorization: Bearer <token>."

It's important to be conscious that "CLAUDE.md is part of the prompt." Since the context window is precious, you should maintain an attitude of demanding "value for inclusion" for every single line.

When to Use Which Tool

Finally, let's summarize the use cases for the two tools once more.

• After a major refactoring or directory reorganization → Audit the whole thing with claude-md-improver.
• Immediately after introducing new tools or settings → Look for missing reflections with claude-md-improver.
• When you feel "Oh, I didn't know this" during a session → Incorporate it on the spot with /revise-claude-md.

I recommend running both: periodic health checkups (improver) and small daily note-taking (revise).

Summary

claude-md-management is a plugin that embodies the idea that "CLAUDE.md is not something you write once and finish, but something you grow." Since it's officially released by Anthropic, it has great compatibility with Claude Code itself, and the cost of introduction was almost zero.

Using it myself, I'm often surprised to find how outdated my CLAUDE.md had become. If you use Claude Code daily, I highly recommend installing it. Just having your CLAUDE.md audited will slightly change how you see your own project.

Reference Links

• CLAUDE.md Management (Claude Plugins Catalog)
• claude-plugins-official Repository
• Discover and install plugins (Official Documentation)