claude-md-manager

CLAUDE.md Manager

Create and maintain effective CLAUDE.md files that configure Claude Code's project behavior.

Core Workflow

1. Determine the Mode

Creating new CLAUDE.md:

• Analyze project structure, tech stack, and conventions
• Generate focused documentation using WHAT/WHY/HOW framework
• Target under 100 lines (max 300)

Refreshing existing CLAUDE.md:

• Audit current content for bloat, staleness, and anti-patterns
• Identify instructions that should be externalized
• Optimize for conciseness and relevance

2. Project Analysis (for new files)

Examine:

• package.json, Cargo.toml, pyproject.toml, etc. for stack
• Directory structure for architecture patterns
• Existing README.md for project context
• .github/, Makefile, scripts for workflows
• Test directories for testing conventions

3. Apply the WHAT/WHY/HOW Framework

WHAT - Technical reality:

• Tech stack and key dependencies
• Directory structure and architecture
• Key files and entry points

WHY - Context and purpose:

• What the project does
• Why certain patterns exist
• Functional purpose of directories

HOW - Practical workflows:

• Build commands (package manager specifics)
• Test execution
• Development workflow
• Deployment process

4. Validation Review Pass

After creating or refreshing CLAUDE.md, validate claims against the actual codebase using OSGrep. This catches stale commands, incorrect paths, and drifted conventions.

Validation Steps

1. Validate Commands

# For each command documented, verify it exists
osgrep "dev server startup configuration" -p $REPO -m 3
osgrep "test runner setup" -p $REPO -m 3
osgrep "build script configuration" -p $REPO -m 3

2. Validate Directory Structure

# Verify directories contain what's documented
osgrep "component definitions" -p $REPO/src/components -m 3
osgrep "API route handlers" -p $REPO/src/routes -m 3

3. Validate @import References

# Check each @path/to/file reference exists
test -f $REPO/docs/architecture.md && echo "EXISTS" || echo "MISSING"