CLAUDE.md File Enhancer
This skill provides comprehensive CLAUDE.md file generation and enhancement for Claude Code projects. It analyzes existing files, validates against best practices, and generates customized guidelines tailored to your project type, tech stack, and team size.
Capabilities
- 🆕 Interactive Initialization: Intelligent workflow that explores your repository, detects project type and tech stack, asks for confirmation, then creates customized CLAUDE.md files
- ✨ 100% Native Format Compliance: All generated files follow official Claude Code format with project structure diagrams, setup instructions, architecture sections, and file structure explanations (matching
/update-claude-md slash command)
- Analyze Existing Files: Scan and evaluate current CLAUDE.md files for structure, completeness, and quality
- Validate Best Practices: Check against Anthropic guidelines (file length, required sections, formatting standards)
- Generate New Files: Create complete CLAUDE.md files from scratch for new projects
- Enhance Existing Files: Add missing sections, improve structure, and update to latest best practices
- Modular Architecture: Support context-specific CLAUDE.md files in subdirectories (backend/, frontend/, docs/)
- Tech Stack Customization: Tailor guidelines to specific technologies (TypeScript, Python, Go, React, Vue, etc.)
- Team Size Adaptation: Adjust complexity based on team size (solo, small <10, large 10+)
- Template Selection: Choose appropriate template based on project complexity and development phase
Input Requirements
For Analysis and Enhancement
Provide existing CLAUDE.md file content or file path:
{
"mode": "enhance",
"file_path": "CLAUDE.md",
"content": "[existing CLAUDE.md content]",
"project_context": {
"type": "web_app",
"tech_stack": ["typescript", "react", "node", "postgresql"],
"team_size": "small",
"phase": "mvp"
}
}
For New File Generation
Provide project context:
{
"mode": "create",
"project_context": {
"type": "api",
"tech_stack": ["python", "fastapi", "postgresql", "docker"],
"team_size": "medium",
"phase": "production",
"workflows": ["tdd", "cicd", "documentation_first"]
},
"modular": true,
"subdirectories": ["backend", "database", "docs"]
}
Context Parameters
- type: Project type (
web_app, api, fullstack, cli, library, mobile, desktop)
- tech_stack: Array of technologies (e.g.,
["typescript", "react", "node"])
- team_size:
solo, small (<10), medium (10-50), large (50+)
- phase: Development phase (
prototype, mvp, production, enterprise)
- workflows: Key workflows (
tdd, cicd, documentation_first, agile, etc.)
Output Formats
Analysis Report
{
"analysis": {
"file_size": 450,
"line_count": 320,
"sections_found": [
"Quick Navigation",
"Core Principles",
"Tech Stack",
"Workflow Instructions"
],
"missing_sections": [
"Testing Requirements",
"Error Handling Patterns"
],
"issues": [
{
"type": "length_warning",
"severity": "medium",
"message": "File exceeds recommended 300 lines (320 lines)"
},
{
"type": "missing_section",
"severity": "low",
"message": "Consider adding 'Testing Requirements' section"
}
],
"quality_score": 75,
"recommendations": [
"Split into modular files (backend/CLAUDE.md, frontend/CLAUDE.md)",
"Add testing requirements section",
"Reduce root file to <150 lines"
]
}
}
Generated Content
Complete CLAUDE.md file content or specific sections to add:
# CLAUDE.md
This file provides guidance for Claude Code when working with this project.
## Quick Navigation
- [Backend Guidelines](backend/CLAUDE.md)
- [Frontend Guidelines](frontend/CLAUDE.md)
- [Database Operations](database/CLAUDE.md)
- [CI/CD Workflows](.github/CLAUDE.md)
## Core Principles
1. **Test-Driven Development**: Write tests before implementation
2. **Type Safety First**: Use TypeScript strict mode throughout
3. **Component Composition**: Favor small, reusable components
4. **Error Handling**: Always handle errors with proper logging
5. **Documentation Updates**: Keep docs in sync with code changes
[... additional sections based on template ...]
How to Use
Example 1: Initialize CLAUDE.md for New Project (Interactive)
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?
What Happens:
- Claude checks if CLAUDE.md exists (it doesn't)
- Claude explores your repository using built-in commands
- Claude analyzes: project type, tech stack, team size, workflows
- Claude shows discoveries and asks for confirmation
- You confirm the settings
- Claude creates customized CLAUDE.md file(s)
- Claude enhances with best practices
Interactive Flow:
- ✋ User must confirm before creation
- 🔍 Full visibility into what was discovered
- ⚙️ Option to adjust settings before proceeding
Example 2: Analyze Existing CLAUDE.md
Hey Claude—I just added the "claude-md-enhancer" skill. Can you analyze my current CLAUDE.md file and tell me what's missing or could be improved?
Example 2: Generate New CLAUDE.md for TypeScript Project
Hey Claude—I just added the "claude-md-enhancer" skill. Can you create a CLAUDE.md file for my TypeScript React project with a team of 5 developers? We use PostgreSQL, Docker, and follow TDD practices.
Example 3: Enhance Existing File
Hey Claude—I just added the "claude-md-enhancer" skill. Can you enhance my existing CLAUDE.md by adding missing sections and improving the structure? Here's my current file: [paste content]
Example 4: Generate Modular Architecture
Hey Claude—I just added the "claude-md-enhancer" skill. Can you create a modular CLAUDE.md setup for my full-stack project? I need separate files for backend (Python/FastAPI), frontend (React), and database (PostgreSQL).
Initialization Workflow (New Projects)
When CLAUDE.md doesn't exist in your project, this skill provides an intelligent initialization workflow:
Workflow Steps
Step 1: Detection
- Skill checks if CLAUDE.md exists in project root
- If not found, initialization workflow begins
Step 2: Repository Exploration
- Uses Claude Code's built-in
explore command
- Analyzes project structure, files, and directories
- Examines configuration files (package.json, requirements.txt, go.mod, etc.)
- Reviews existing documentation
Step 3: Intelligent Analysis
- Project Type Detection: web_app, api, fullstack, cli, library, mobile, desktop
- Tech Stack Detection: TypeScript, Python, React, FastAPI, PostgreSQL, Docker, etc.
- Team Size Estimation: Based on project complexity (solo, small, medium, large)
- Development Phase: prototype, mvp, production, enterprise
- Workflow Detection: TDD, CI/CD, documentation-first, agile
- Structure Recommendation: Single file vs. modular architecture
Step 4: User Confirmation ✋
- Displays all discoveries in clear format
- Shows recommended CLAUDE.md structure
- Asks user to confirm or adjust settings
- User must explicitly approve before proceeding
Step 5: File Creation
- Generates customized CLAUDE.md based on confirmed settings
- Creates modular files if recommended (backend/, frontend/, etc.)
- Applies tech-specific best practices
Step 6: Enhancement
- Validates generated content
- Adds quality improvements
- Ensures completeness
Step 7: Summary
- Shows what files were created
- Provides next steps
- Ready for immediate use
Interactive Example
User: "I need a CLAUDE.md for this project"
Claude: "I'll explore your repository first to understand the project.
[Explores using built-in commands]
Based on my exploration, here's what I discovered:
Project Type: Full-Stack Application
Tech Stack: TypeScript, React, Node.js, PostgreSQL, Docker
Team Size: Small (2-9 developers)
Development Phase: MVP
Workflows: TDD, CI/CD
Recommended Structure: Modular architecture
- Root CLAUDE.md (navigation hub)
- backend/CLAUDE.md (API guidelines)
- frontend/CLAUDE.md (React guidelines)
Would you like me to create these files?"
User: "Yes, please proceed"
Claude: "Creating customized CLAUDE.md files...
✅ Created CLAUDE.md (100 lines)
✅ Created backend/CLAUDE.md (150 lines)
✅ Created frontend/CLAUDE.md (175 lines)
Your project is ready for AI-assisted development!"
Scripts
workflow.py
Manages the interactive initialization workflow for new projects.
Key Functions:
check_claude_md_exists() - Detect if CLAUDE.md exists
generate_exploration_prompt() - Guide Claude to explore repository
analyze_discoveries() - Analyze exploration results
generate_confirmation_prompt() - Create user confirmation prompt
get_workflow_steps() - Get complete workflow steps
analyzer.py
Analyzes existing CLAUDE.md files to identify structure, sections, and quality issues.
Key Functions:
analyze_file() - Parse and analyze CLAUDE.md structure
detect_sections() - Identify present and missing sections
calculate_quality_score() - Score file quality (0-100)
generate_recommendations() - Provide actionable improvement suggestions
validator.py
Validates CLAUDE.md files against best practices and Anthropic guidelines.
Key Functions:
validate_length() - Check file length (warn if >300 lines)
validate_structure() - Verify required sections present
validate_formatting() - Check markdown formatting quality
validate_completeness() - Ensure critical information included
generator.py
Generates new CLAUDE.md content or missing sections based on templates.
Key Functions:
generate_root_file() - Create main CLAUDE.md orchestrator
generate_context_file() - Create context-specific files (backend, frontend, etc.)
generate_section() - Generate individual sections (tech stack, workflows, etc.)
merge_with_existing() - Add new sections to existing files
template_selector.py
Selects appropriate template based on project context.
Key Functions:
select_template() - Choose template based on project type and team size
customize_template() - Adapt template to tech stack
determine_complexity() - Calculate appropriate detail level
recommend_modular_structure() - Suggest subdirectory organization
Best Practices
Critical Validation Rule ⚠️
"Always validate your output against official native examples before declaring complete."
Before finalizing any CLAUDE.md generation:
- Compare output against
/update-claude-md slash command format
- Check official Claude Code documentation for required sections
- Verify all native format sections are present (Overview, Project Structure, File Structure, Setup & Installation, Architecture, etc.)
- Cross-check against reference examples in
examples/ folder
For New Projects
- Start with minimal template (50-100 lines) and grow as needed
- Use modular architecture for projects with >3 major components
- Include tech stack reference immediately
- Add workflow instructions before team grows beyond 5 people
For Enhancement
- Analyze before modifying - understand current structure first
- Preserve custom content - only enhance, don't replace
- Validate after changes - ensure improvements don't break existing patterns
- Test with Claude Code - verify guidelines work as intended
General Guidelines
- Keep root file concise - Max 150 lines, use as navigation hub
- Use context-specific files - backend/CLAUDE.md, frontend/CLAUDE.md, etc.
- Avoid duplication - Each guideline should appear once
- Link to external docs - Don't copy official documentation
- Update regularly - Review guidelines quarterly or when stack changes
Limitations
Technical Constraints
- Requires valid project context for accurate template selection
- Tech stack detection is based on keywords, may need manual refinement
- Modular file generation assumes standard directory structure
Scope Boundaries
- Focuses on CLAUDE.md structure, not project-specific business logic
- Best practice recommendations are general, may need industry-specific customization
- Validation is guideline-based, not enforcement (no automated fixes without approval)
When NOT to Use
- For non-Claude AI tools (this is Claude Code specific)
- For projects that don't use Claude Code or similar AI assistants
- When you need highly specialized domain guidelines (legal, medical compliance)
Template Categories
By Size
- Minimal (50 lines) - Solo developers, prototypes, hackathons
- Core (100-150 lines) - Small teams, MVPs, standard projects
- Detailed (200-300 lines) - Large teams, production systems, enterprise
By Project Type
- Web App - Frontend-focused (React, Vue, Angular)
- API - Backend services (REST, GraphQL, microservices)
- Full-Stack - Integrated frontend + backend
- CLI - Command-line tools and utilities
- Library - Reusable packages and frameworks
- Mobile - React Native, Flutter, native iOS/Android
By Tech Stack
- TypeScript/Node - Modern JavaScript ecosystem
- Python - Django, FastAPI, Flask
- Go - Gin, Echo, native services
- Java/Kotlin - Spring Boot, enterprise Java
- Ruby - Rails, Sinatra
Quality Metrics
File Quality Score (0-100)
Calculated based on:
- Length appropriateness (25 points) - Not too short or long
- Section completeness (25 points) - Required sections present
- Formatting quality (20 points) - Proper markdown structure
- Content specificity (15 points) - Tailored to project, not generic
- Modular organization (15 points) - Uses subdirectory files when appropriate
Recommendations Priority
- Critical - Missing required sections, file too long (>400 lines)
- High - Missing important sections, formatting issues
- Medium - Could add optional sections, minor improvements
- Low - Nice-to-have enhancements, stylistic suggestions
Advanced Features
Modular Architecture Support
Automatically generates context-specific files:
project-root/
├── CLAUDE.md # Root orchestrator (100-150 lines)
├── backend/
│ └── CLAUDE.md # Backend-specific (150-200 lines)
├── frontend/
│ └── CLAUDE.md # Frontend-specific (150-200 lines)
├── database/
│ └── CLAUDE.md # Database operations (100-150 lines)
└── .github/
└── CLAUDE.md # CI/CD workflows (100-150 lines)
Tech Stack Detection
Automatically detects technologies from:
package.json (Node.js/TypeScript)
requirements.txt or pyproject.toml (Python)
go.mod (Go)
Cargo.toml (Rust)
pom.xml or build.gradle (Java)
Team Size Adaptation
Adjusts detail level:
- Solo: Minimal guidelines, focus on efficiency
- Small (<10): Core guidelines, workflow basics
- Medium (10-50): Detailed guidelines, team coordination
- Large (50+): Comprehensive guidelines, process enforcement
References
- Anthropic Claude Code Docs: https://docs.claude.com/en/docs/claude-code
- CLAUDE.md Best Practices: Based on community patterns and Anthropic guidance
- Example CLAUDE.md Files: See
examples/ folder for 6 reference implementations covering different project types and team sizes
Version
Version: 1.0.0
Last Updated: November 2025
Compatible: Claude Code 2.0+, Claude Apps, Claude API
Remember: The goal is to make Claude more efficient and context-aware, not to create bureaucracy. Start simple, iterate based on real usage, and automate quality checks where possible.
1---2name: claude-md-enhancer3description: Analyzes, generates, and enhances CLAUDE.md files for any project type using best practices, modular architecture support, and tech stack customization. Use when setting up new projects, improving existing CLAUDE.md files, or establishing AI-assisted development standards.4metadata:5 source: https://skillmd.com/skills/alirezarezvani/claude-md-enhancer6---78# CLAUDE.md File Enhancer910This skill provides comprehensive CLAUDE.md file generation and enhancement for Claude Code projects. It analyzes existing files, validates against best practices, and generates customized guidelines tailored to your project type, tech stack, and team size.1112## Capabilities1314- **🆕 Interactive Initialization**: Intelligent workflow that explores your repository, detects project type and tech stack, asks for confirmation, then creates customized CLAUDE.md files15- **✨ 100% Native Format Compliance**: All generated files follow official Claude Code format with project structure diagrams, setup instructions, architecture sections, and file structure explanations (matching `/update-claude-md` slash command)16- **Analyze Existing Files**: Scan and evaluate current CLAUDE.md files for structure, completeness, and quality17- **Validate Best Practices**: Check against Anthropic guidelines (file length, required sections, formatting standards)18- **Generate New Files**: Create complete CLAUDE.md files from scratch for new projects19- **Enhance Existing Files**: Add missing sections, improve structure, and update to latest best practices20- **Modular Architecture**: Support context-specific CLAUDE.md files in subdirectories (backend/, frontend/, docs/)21- **Tech Stack Customization**: Tailor guidelines to specific technologies (TypeScript, Python, Go, React, Vue, etc.)22- **Team Size Adaptation**: Adjust complexity based on team size (solo, small <10, large 10+)23- **Template Selection**: Choose appropriate template based on project complexity and development phase2425## Input Requirements2627### For Analysis and Enhancement2829Provide existing CLAUDE.md file content or file path:3031```json32{33 "mode": "enhance",34 "file_path": "CLAUDE.md",35 "content": "[existing CLAUDE.md content]",36 "project_context": {37 "type": "web_app",38 "tech_stack": ["typescript", "react", "node", "postgresql"],39 "team_size": "small",40 "phase": "mvp"41 }42}43```4445### For New File Generation4647Provide project context:4849```json50{51 "mode": "create",52 "project_context": {53 "type": "api",54 "tech_stack": ["python", "fastapi", "postgresql", "docker"],55 "team_size": "medium",56 "phase": "production",57 "workflows": ["tdd", "cicd", "documentation_first"]58 },59 "modular": true,60 "subdirectories": ["backend", "database", "docs"]61}62```6364### Context Parameters6566- **type**: Project type (`web_app`, `api`, `fullstack`, `cli`, `library`, `mobile`, `desktop`)67- **tech_stack**: Array of technologies (e.g., `["typescript", "react", "node"]`)68- **team_size**: `solo`, `small` (<10), `medium` (10-50), `large` (50+)69- **phase**: Development phase (`prototype`, `mvp`, `production`, `enterprise`)70- **workflows**: Key workflows (`tdd`, `cicd`, `documentation_first`, `agile`, etc.)7172## Output Formats7374### Analysis Report7576```json77{78 "analysis": {79 "file_size": 450,80 "line_count": 320,81 "sections_found": [82 "Quick Navigation",83 "Core Principles",84 "Tech Stack",85 "Workflow Instructions"86 ],87 "missing_sections": [88 "Testing Requirements",89 "Error Handling Patterns"90 ],91 "issues": [92 {93 "type": "length_warning",94 "severity": "medium",95 "message": "File exceeds recommended 300 lines (320 lines)"96 },97 {98 "type": "missing_section",99 "severity": "low",100 "message": "Consider adding 'Testing Requirements' section"101 }102 ],103 "quality_score": 75,104 "recommendations": [105 "Split into modular files (backend/CLAUDE.md, frontend/CLAUDE.md)",106 "Add testing requirements section",107 "Reduce root file to <150 lines"108 ]109 }110}111```112113### Generated Content114115Complete CLAUDE.md file content or specific sections to add:116117```markdown118# CLAUDE.md119120This file provides guidance for Claude Code when working with this project.121122## Quick Navigation123124- [Backend Guidelines](backend/CLAUDE.md)125- [Frontend Guidelines](frontend/CLAUDE.md)126- [Database Operations](database/CLAUDE.md)127- [CI/CD Workflows](.github/CLAUDE.md)128129## Core Principles1301311. **Test-Driven Development**: Write tests before implementation1322. **Type Safety First**: Use TypeScript strict mode throughout1333. **Component Composition**: Favor small, reusable components1344. **Error Handling**: Always handle errors with proper logging1355. **Documentation Updates**: Keep docs in sync with code changes136137[... additional sections based on template ...]138```139140## How to Use141142### Example 1: Initialize CLAUDE.md for New Project (Interactive)143144```145Hey 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?146```147148**What Happens**:1491. Claude checks if CLAUDE.md exists (it doesn't)1502. Claude explores your repository using built-in commands1513. Claude analyzes: project type, tech stack, team size, workflows1524. Claude shows discoveries and asks for confirmation1535. You confirm the settings1546. Claude creates customized CLAUDE.md file(s)1557. Claude enhances with best practices156157**Interactive Flow**:158- ✋ User must confirm before creation159- 🔍 Full visibility into what was discovered160- ⚙️ Option to adjust settings before proceeding161162### Example 2: Analyze Existing CLAUDE.md163164```165Hey Claude—I just added the "claude-md-enhancer" skill. Can you analyze my current CLAUDE.md file and tell me what's missing or could be improved?166```167168### Example 2: Generate New CLAUDE.md for TypeScript Project169170```171Hey Claude—I just added the "claude-md-enhancer" skill. Can you create a CLAUDE.md file for my TypeScript React project with a team of 5 developers? We use PostgreSQL, Docker, and follow TDD practices.172```173174### Example 3: Enhance Existing File175176```177Hey Claude—I just added the "claude-md-enhancer" skill. Can you enhance my existing CLAUDE.md by adding missing sections and improving the structure? Here's my current file: [paste content]178```179180### Example 4: Generate Modular Architecture181182```183Hey Claude—I just added the "claude-md-enhancer" skill. Can you create a modular CLAUDE.md setup for my full-stack project? I need separate files for backend (Python/FastAPI), frontend (React), and database (PostgreSQL).184```185186## Initialization Workflow (New Projects)187188When CLAUDE.md doesn't exist in your project, this skill provides an intelligent initialization workflow:189190### Workflow Steps191192**Step 1: Detection**193- Skill checks if CLAUDE.md exists in project root194- If not found, initialization workflow begins195196**Step 2: Repository Exploration**197- Uses Claude Code's built-in `explore` command198- Analyzes project structure, files, and directories199- Examines configuration files (package.json, requirements.txt, go.mod, etc.)200- Reviews existing documentation201202**Step 3: Intelligent Analysis**203- **Project Type Detection**: web_app, api, fullstack, cli, library, mobile, desktop204- **Tech Stack Detection**: TypeScript, Python, React, FastAPI, PostgreSQL, Docker, etc.205- **Team Size Estimation**: Based on project complexity (solo, small, medium, large)206- **Development Phase**: prototype, mvp, production, enterprise207- **Workflow Detection**: TDD, CI/CD, documentation-first, agile208- **Structure Recommendation**: Single file vs. modular architecture209210**Step 4: User Confirmation** ✋211- Displays all discoveries in clear format212- Shows recommended CLAUDE.md structure213- Asks user to confirm or adjust settings214- **User must explicitly approve** before proceeding215216**Step 5: File Creation**217- Generates customized CLAUDE.md based on confirmed settings218- Creates modular files if recommended (backend/, frontend/, etc.)219- Applies tech-specific best practices220221**Step 6: Enhancement**222- Validates generated content223- Adds quality improvements224- Ensures completeness225226**Step 7: Summary**227- Shows what files were created228- Provides next steps229- Ready for immediate use230231### Interactive Example232233```234User: "I need a CLAUDE.md for this project"235236Claude: "I'll explore your repository first to understand the project.237 [Explores using built-in commands]238239 Based on my exploration, here's what I discovered:240241 Project Type: Full-Stack Application242 Tech Stack: TypeScript, React, Node.js, PostgreSQL, Docker243 Team Size: Small (2-9 developers)244 Development Phase: MVP245 Workflows: TDD, CI/CD246247 Recommended Structure: Modular architecture248 - Root CLAUDE.md (navigation hub)249 - backend/CLAUDE.md (API guidelines)250 - frontend/CLAUDE.md (React guidelines)251252 Would you like me to create these files?"253254User: "Yes, please proceed"255256Claude: "Creating customized CLAUDE.md files...257 ✅ Created CLAUDE.md (100 lines)258 ✅ Created backend/CLAUDE.md (150 lines)259 ✅ Created frontend/CLAUDE.md (175 lines)260261 Your project is ready for AI-assisted development!"262```263264## Scripts265266### workflow.py267Manages the interactive initialization workflow for new projects.268269**Key Functions**:270- `check_claude_md_exists()` - Detect if CLAUDE.md exists271- `generate_exploration_prompt()` - Guide Claude to explore repository272- `analyze_discoveries()` - Analyze exploration results273- `generate_confirmation_prompt()` - Create user confirmation prompt274- `get_workflow_steps()` - Get complete workflow steps275276### analyzer.py277Analyzes existing CLAUDE.md files to identify structure, sections, and quality issues.278279**Key Functions**:280- `analyze_file()` - Parse and analyze CLAUDE.md structure281- `detect_sections()` - Identify present and missing sections282- `calculate_quality_score()` - Score file quality (0-100)283- `generate_recommendations()` - Provide actionable improvement suggestions284285### validator.py286Validates CLAUDE.md files against best practices and Anthropic guidelines.287288**Key Functions**:289- `validate_length()` - Check file length (warn if >300 lines)290- `validate_structure()` - Verify required sections present291- `validate_formatting()` - Check markdown formatting quality292- `validate_completeness()` - Ensure critical information included293294### generator.py295Generates new CLAUDE.md content or missing sections based on templates.296297**Key Functions**:298- `generate_root_file()` - Create main CLAUDE.md orchestrator299- `generate_context_file()` - Create context-specific files (backend, frontend, etc.)300- `generate_section()` - Generate individual sections (tech stack, workflows, etc.)301- `merge_with_existing()` - Add new sections to existing files302303### template_selector.py304Selects appropriate template based on project context.305306**Key Functions**:307- `select_template()` - Choose template based on project type and team size308- `customize_template()` - Adapt template to tech stack309- `determine_complexity()` - Calculate appropriate detail level310- `recommend_modular_structure()` - Suggest subdirectory organization311312## Best Practices313314### Critical Validation Rule ⚠️315316**"Always validate your output against official native examples before declaring complete."**317318Before finalizing any CLAUDE.md generation:3191. Compare output against `/update-claude-md` slash command format3202. Check official Claude Code documentation for required sections3213. Verify all native format sections are present (Overview, Project Structure, File Structure, Setup & Installation, Architecture, etc.)3224. Cross-check against reference examples in `examples/` folder323324### For New Projects3251. Start with minimal template (50-100 lines) and grow as needed3262. Use modular architecture for projects with >3 major components3273. Include tech stack reference immediately3284. Add workflow instructions before team grows beyond 5 people329330### For Enhancement3311. Analyze before modifying - understand current structure first3322. Preserve custom content - only enhance, don't replace3333. Validate after changes - ensure improvements don't break existing patterns3344. Test with Claude Code - verify guidelines work as intended335336### General Guidelines3371. **Keep root file concise** - Max 150 lines, use as navigation hub3382. **Use context-specific files** - backend/CLAUDE.md, frontend/CLAUDE.md, etc.3393. **Avoid duplication** - Each guideline should appear once3404. **Link to external docs** - Don't copy official documentation3415. **Update regularly** - Review guidelines quarterly or when stack changes342343## Limitations344345### Technical Constraints346- Requires valid project context for accurate template selection347- Tech stack detection is based on keywords, may need manual refinement348- Modular file generation assumes standard directory structure349350### Scope Boundaries351- Focuses on CLAUDE.md structure, not project-specific business logic352- Best practice recommendations are general, may need industry-specific customization353- Validation is guideline-based, not enforcement (no automated fixes without approval)354355### When NOT to Use356- For non-Claude AI tools (this is Claude Code specific)357- For projects that don't use Claude Code or similar AI assistants358- When you need highly specialized domain guidelines (legal, medical compliance)359360## Template Categories361362### By Size363- **Minimal** (50 lines) - Solo developers, prototypes, hackathons364- **Core** (100-150 lines) - Small teams, MVPs, standard projects365- **Detailed** (200-300 lines) - Large teams, production systems, enterprise366367### By Project Type368- **Web App** - Frontend-focused (React, Vue, Angular)369- **API** - Backend services (REST, GraphQL, microservices)370- **Full-Stack** - Integrated frontend + backend371- **CLI** - Command-line tools and utilities372- **Library** - Reusable packages and frameworks373- **Mobile** - React Native, Flutter, native iOS/Android374375### By Tech Stack376- **TypeScript/Node** - Modern JavaScript ecosystem377- **Python** - Django, FastAPI, Flask378- **Go** - Gin, Echo, native services379- **Java/Kotlin** - Spring Boot, enterprise Java380- **Ruby** - Rails, Sinatra381382## Quality Metrics383384### File Quality Score (0-100)385386Calculated based on:387- **Length appropriateness** (25 points) - Not too short or long388- **Section completeness** (25 points) - Required sections present389- **Formatting quality** (20 points) - Proper markdown structure390- **Content specificity** (15 points) - Tailored to project, not generic391- **Modular organization** (15 points) - Uses subdirectory files when appropriate392393### Recommendations Priority394395- **Critical** - Missing required sections, file too long (>400 lines)396- **High** - Missing important sections, formatting issues397- **Medium** - Could add optional sections, minor improvements398- **Low** - Nice-to-have enhancements, stylistic suggestions399400## Advanced Features401402### Modular Architecture Support403404Automatically generates context-specific files:405406```407project-root/408├── CLAUDE.md # Root orchestrator (100-150 lines)409├── backend/410│ └── CLAUDE.md # Backend-specific (150-200 lines)411├── frontend/412│ └── CLAUDE.md # Frontend-specific (150-200 lines)413├── database/414│ └── CLAUDE.md # Database operations (100-150 lines)415└── .github/416 └── CLAUDE.md # CI/CD workflows (100-150 lines)417```418419### Tech Stack Detection420421Automatically detects technologies from:422- `package.json` (Node.js/TypeScript)423- `requirements.txt` or `pyproject.toml` (Python)424- `go.mod` (Go)425- `Cargo.toml` (Rust)426- `pom.xml` or `build.gradle` (Java)427428### Team Size Adaptation429430Adjusts detail level:431- **Solo**: Minimal guidelines, focus on efficiency432- **Small (<10)**: Core guidelines, workflow basics433- **Medium (10-50)**: Detailed guidelines, team coordination434- **Large (50+)**: Comprehensive guidelines, process enforcement435436## References437438- **Anthropic Claude Code Docs**: https://docs.claude.com/en/docs/claude-code439- **CLAUDE.md Best Practices**: Based on community patterns and Anthropic guidance440- **Example CLAUDE.md Files**: See `examples/` folder for 6 reference implementations covering different project types and team sizes441442## Version443444**Version**: 1.0.0445**Last Updated**: November 2025446**Compatible**: Claude Code 2.0+, Claude Apps, Claude API447448Remember: The goal is to make Claude more efficient and context-aware, not to create bureaucracy. Start simple, iterate based on real usage, and automate quality checks where possible.449