Skip to content

Latest commit

 

History

History
 
 

claude-md-enhancer

README.md

claude-md-enhancer

Analyze, generate, and enhance CLAUDE.md files for any project type with intelligent templates and best practices.

A comprehensive Claude Code skill that helps teams create and maintain high-quality CLAUDE.md files. Supports analysis, validation, generation, and enhancement with tech stack customization, team size adaptation, and modular architecture.

Features

🆕 Interactive Initialization - Explore repository, detect project context, and create CLAUDE.md through conversational workflow ✨ 100% Native Format Compliance - All generated files follow official Claude Code format with project structure diagrams, setup instructions, architecture sections, and file structure explanations ✅ Intelligent Analysis - Scan and evaluate existing CLAUDE.md files for quality and completeness 🎯 Best Practice Validation - Check against Anthropic guidelines and community standards 🚀 Smart Generation - Create customized CLAUDE.md files from scratch 🔧 Enhancement - Add missing sections and improve existing files 📦 Modular Architecture - Support context-specific files (backend/, frontend/, database/) 🛠️ Tech Stack Customization - Tailor guidelines to your technologies 👥 Team Size Adaptation - Adjust complexity for solo, small, medium, or large teams 📊 Quality Scoring - Get 0-100 quality scores with actionable recommendations

Quick Start

Installation

Option 1: Claude Code (Project-Level)

# Copy skill folder to your project
cp -r claude-md-enhancer /path/to/your/project/.claude/skills/

# Restart Claude Code or reload skills

Option 2: Claude Code (User-Level)

# Copy skill folder to user skills directory
cp -r claude-md-enhancer ~/.claude/skills/

# Available across all your projects

Option 3: Claude Apps

1. Open Claude in browser
2. Go to Skills settings
3. Upload claude-md-enhancer.zip
4. Enable the skill

Basic Usage

New Project (Interactive Initialization)

Hey Claude—I just added the "claude-md-enhancer" skill. I don't have a CLAUDE.md file yet. Can you help me create one for this project?

Claude will:

  1. Explore your repository
  2. Detect project type, tech stack, team size
  3. Show discoveries and ask for confirmation
  4. Create customized CLAUDE.md file(s)

Existing Project

Hey Claude—I just added the "claude-md-enhancer" skill. Can you analyze my CLAUDE.md and suggest improvements?

See HOW_TO_USE.md for comprehensive examples.

Architecture

Module Overview

claude-md-enhancer/
├── SKILL.md                    # Skill definition with YAML frontmatter
├── analyzer.py                 # Analyzes existing CLAUDE.md files
├── validator.py                # Validates against best practices
├── generator.py                # Generates new content
├── template_selector.py        # Selects appropriate templates
├── sample_input.json           # Example inputs
├── expected_output.json        # Expected outputs
├── HOW_TO_USE.md               # Usage examples
└── README.md                   # This file

Python Modules

workflow.py - Initialization Workflow (New!)

Class: InitializationWorkflow

Key Methods:

  • check_claude_md_exists() - Detect if CLAUDE.md exists
  • generate_exploration_prompt() - Guide Claude to explore repository
  • analyze_discoveries(results) - Analyze exploration results to detect project context
  • generate_confirmation_prompt(context) - Create user confirmation prompt
  • get_workflow_steps() - Get complete 7-step workflow

Workflow Steps:

  1. Check for existing CLAUDE.md
  2. Explore repository (built-in Claude Code command)
  3. Analyze discoveries (project type, tech stack, team size)
  4. Request user confirmation
  5. Create CLAUDE.md file(s)
  6. Enhance with best practices
  7. Provide summary

Detection Capabilities:

  • Project Types: web_app, api, fullstack, cli, library, mobile, desktop
  • Tech Stacks: TypeScript, Python, Go, React, Vue, FastAPI, Django, PostgreSQL, Docker, Kubernetes, etc.
  • Team Sizes: solo, small (<10), medium (10-50), large (50+)
  • Development Phases: prototype, mvp, production, enterprise
  • Workflows: TDD, CI/CD, documentation-first, agile

analyzer.py - File Analysis

Class: CLAUDEMDAnalyzer

Key Methods:

  • analyze_file() - Comprehensive file analysis
  • detect_sections() - Identify all sections and subsections
  • calculate_quality_score() - Score 0-100 based on multiple factors
  • generate_recommendations() - Actionable improvement suggestions

Quality Score Breakdown (0-100):

  • Length appropriateness: 25 points
  • Section completeness: 25 points
  • Formatting quality: 20 points
  • Content specificity: 15 points
  • Modular organization: 15 points

validator.py - Best Practices Validation

Class: BestPracticesValidator

Key Methods:

  • validate_length() - Check file length (20-300 lines recommended)
  • validate_structure() - Verify required sections and hierarchy
  • validate_formatting() - Check markdown formatting quality
  • validate_completeness() - Ensure critical content included
  • validate_all() - Run all validation checks

Validation Categories:

  • File length (MUST be 20-300 lines)
  • Structure (required sections: Core Principles, Workflow)
  • Formatting (balanced code blocks, heading hierarchy)
  • Completeness (code examples, links, lists)
  • Anti-patterns (hardcoded secrets, placeholders, broken links)

generator.py - Content Generation

Class: ContentGenerator

Key Methods:

  • generate_root_file() - Create main CLAUDE.md (navigation hub)
  • generate_context_file(context) - Create context-specific files
  • generate_section(name) - Generate individual sections
  • merge_with_existing(content, sections) - Enhance existing files

Supported Contexts:

  • backend - API design, database, error handling
  • frontend - Components, state, styling, performance
  • database - Schema, migrations, query optimization
  • docs - Documentation standards
  • .github - CI/CD workflows

template_selector.py - Template Selection

Class: TemplateSelector

Key Methods:

  • select_template() - Choose template based on project context
  • customize_template(template) - Generate customized content
  • recommend_modular_structure() - Determine if modular architecture needed

Template Matrix:

Project Type Team Size Target Lines Complexity
Web App Solo 75 Minimal
API Small (<10) 125 Core
Full-Stack Medium (10-50) 200 Detailed
Library Large (50+) 275 Comprehensive

Supported Project Types:

  • web_app - Frontend-focused (React, Vue, Angular)
  • api - Backend services (REST, GraphQL)
  • fullstack - Integrated frontend + backend
  • cli - Command-line tools
  • library - Reusable packages
  • mobile - React Native, Flutter
  • desktop - Electron, Tauri

Supported Tech Stacks:

  • TypeScript/JavaScript (React, Vue, Angular, Node)
  • Python (Django, FastAPI, Flask)
  • Go (Gin, Echo)
  • Java/Kotlin (Spring Boot)
  • Ruby (Rails)
  • And more...

Use Cases

1. Analyze Existing CLAUDE.md

Scenario: You have a CLAUDE.md file and want quality feedback.

Input: Existing file content + project context

Output:

  • Quality score (0-100)
  • Missing sections identified
  • Issues and warnings
  • Prioritized recommendations

Example:

Quality Score: 75/100

Missing Sections:
- Testing Requirements
- Error Handling Patterns

Recommendations:
1. Add testing requirements section
2. Reduce file length from 320 to <300 lines
3. Consider modular architecture

2. Generate New CLAUDE.md from Scratch

Scenario: Starting new project, need CLAUDE.md file.

Input: Project context (type, tech stack, team size, phase)

Output: Complete CLAUDE.md tailored to your specifications

Generated Sections:

  • Quick Navigation (if modular)
  • Core Principles
  • Tech Stack
  • Workflow Instructions
  • Testing Requirements
  • Error Handling
  • Documentation Standards
  • Performance Guidelines

3. Enhance Existing File

Scenario: Your CLAUDE.md is missing important sections.

Input: Current content + sections to add

Output: Enhanced file with new sections, preserving existing content

Preservation:

  • Keeps all existing content intact
  • Adds new sections seamlessly
  • Maintains consistent formatting
  • Respects your style choices

4. Generate Modular Architecture

Scenario: Large project needs separate CLAUDE.md files.

Input: Project context + modular flag + subdirectories

Output:

  • Root CLAUDE.md (navigation hub, <150 lines)
  • backend/CLAUDE.md (API, database, testing)
  • frontend/CLAUDE.md (components, state, styling)
  • database/CLAUDE.md (schema, migrations, queries)
  • .github/CLAUDE.md (CI/CD workflows)

When Recommended:

  • Full-stack projects
  • Large teams (10+ developers)
  • Production/enterprise phase
  • 3+ major tech components

5. Validate Before Commit

Scenario: Quick quality check before committing.

Input: Current CLAUDE.md content

Output:

  • Pass/fail status
  • Validation results (5 checks)
  • Errors and warnings
  • Pass/fail counts

Validation Checks:

  1. File length (20-300 lines)
  2. Structure (required sections present)
  3. Formatting (markdown quality)
  4. Completeness (essential content)
  5. Anti-patterns (security, placeholders)

Sample Data

Sample Input

See sample_input.json for 6 realistic scenarios:

  1. analyze_existing - Analyze basic CLAUDE.md file
  2. create_new_fullstack - Generate modular full-stack setup
  3. enhance_with_missing_sections - Add specific sections
  4. create_modular_architecture - Large team, enterprise setup
  5. validate_existing - Validate production-ready file
  6. generate_context_specific - Backend-only file

Expected Output

See expected_output.json for:

  • Analysis reports with quality scores
  • Generated CLAUDE.md content
  • Validation results
  • Enhanced file examples

Best Practices

Critical Validation Rule ⚠️

"Always validate your output against official native examples before declaring complete."

Before finalizing any CLAUDE.md generation:

  1. Compare output against /update-claude-md slash command format
  2. Check official Claude Code documentation for required sections
  3. Verify all native format sections are present (Overview, Project Structure, File Structure, Setup & Installation, Architecture, etc.)
  4. Cross-check against reference examples in examples/ folder

For New Projects

  1. Start Minimal - Generate 50-100 line file, expand as needed
  2. Add Tech Stack Early - Include technologies immediately
  3. Update with Team Growth - Regenerate when team size changes
  4. Consider Modular - Use separate files if >3 major components

For Existing Projects

  1. Analyze First - Understand current state before changes
  2. Preserve Custom Content - Don't overwrite your specific guidelines
  3. Validate Regularly - Check quality when stack or team changes
  4. Iterate - Start with enhancements, full regeneration if needed

General Guidelines

  1. Keep Root Concise - Max 150 lines, use as navigation hub
  2. Use Context Files - backend/, frontend/, etc. for details
  3. Avoid Duplication - Each guideline appears once
  4. Link External Docs - Don't copy official documentation
  5. Update Quarterly - Review and refresh every 3 months

Configuration

Project Context Parameters

{
  "type": "fullstack",                              // Project type
  "tech_stack": ["typescript", "react", "node"],    // Technologies
  "team_size": "small",                             // Team size
  "phase": "mvp",                                   // Development phase
  "workflows": ["tdd", "cicd"],                     // Key workflows
  "modular": true,                                  // Modular architecture
  "subdirectories": ["backend", "frontend"]         // Subdirs for context files
}

Type Options

  • web_app - Frontend-focused
  • api - Backend services
  • fullstack - Full-stack application
  • cli - Command-line tool
  • library - Reusable package
  • mobile - Mobile application
  • desktop - Desktop application

Team Size Options

  • solo - 1 developer
  • small - 2-9 developers
  • medium - 10-49 developers
  • large - 50+ developers

Phase Options

  • prototype - Early exploration
  • mvp - Minimum viable product
  • production - Production system
  • enterprise - Enterprise-grade

Troubleshooting

Quality Score Lower Than Expected

Issue: Quality score is 35/100

Solutions:

  1. Check file length (should be 20-300 lines)
  2. Add missing required sections (Core Principles, Workflow)
  3. Include code examples
  4. Add tech stack references
  5. Consider modular architecture if >300 lines

Generated Content Too Generic

Issue: CLAUDE.md lacks specific guidance

Solutions:

  1. Provide detailed tech stack (specific frameworks/versions)
  2. Specify workflows (TDD, CI/CD, documentation-first)
  3. Include team size for appropriate complexity
  4. Add development phase for priority focus
  5. Customize generated content for your needs

Modular Architecture Not Recommended

Issue: Single file generated, wanted modular

Solutions:

  1. Set "modular": true explicitly
  2. Ensure project type is fullstack
  3. Use team size medium or large
  4. Specify phase as production or enterprise
  5. Provide 3+ tech stack components

Version

Version: 1.0.0 Last Updated: November 2025 Compatible: Claude Code 2.0+, Claude Apps, Claude API

Contributing

Found a bug or have a suggestion? This skill is part of the claude-code-skills-factory repository.

License

MIT License - See LICENSE file for details

Companion Agent: claude-md-guardian 🛡️

For automatic CLAUDE.md maintenance throughout your project lifecycle, use the claude-md-guardian agent:

What It Does

  • Auto-Sync: Updates CLAUDE.md based on project changes
  • Background Operation: Works independently after milestones
  • Smart Detection: Only updates when significant changes occur
  • Token-Efficient: Uses haiku model for routine updates

When It Triggers

Automatically:

  • SessionStart (checks git changes)
  • After feature completion
  • After major refactoring
  • After new dependencies added
  • After architecture changes

Manually:

  • Via /enhance-claude-md slash command
  • Direct invocation

Installation

# User-level (all projects)
cp generated-agents/claude-md-guardian/claude-md-guardian.md ~/.claude/agents/

# Project-level (current project)
cp generated-agents/claude-md-guardian/claude-md-guardian.md .claude/agents/

How They Work Together

claude-md-guardian (agent) → Uses → claude-md-enhancer (skill)
                      ↓
         Detects changes → Invokes skill → Updates CLAUDE.md

Result: Your CLAUDE.md stays synchronized with your codebase automatically!

See generated-agents/claude-md-guardian/README.md for complete agent documentation.

Support

  • Documentation: See SKILL.md for complete documentation
  • Examples: See HOW_TO_USE.md for usage examples
  • Companion Agent: See ../../generated-agents/claude-md-guardian/README.md
  • Slash Command: See ../../generated-commands/enhance-claude-md/README.md
  • Issues: Report bugs in the main repository
  • Community: Share your CLAUDE.md setups and best practices

Happy coding with Claude! 🚀

Make your AI-assisted development more efficient with well-structured CLAUDE.md files and automatic maintenance via claude-md-guardian!