Skip to content

alirezarezvani/claude-code-skill-factory / generated-skills/claude-md-enhancer

claude-md-enhancer

Verified

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.

FileKindSize
HOW_TO_USE.mdmarkdown12.2 KB
README.mdmarkdown15.8 KB
SKILL.mdskill md16.1 KB
analyzer.pyscript12.9 KB
examples/README.mdmarkdown5.3 KB
examples/core-small-team-CLAUDE.mdmarkdown5.5 KB
examples/minimal-solo-CLAUDE.mdmarkdown1.8 KB
examples/modular-backend-CLAUDE.mdmarkdown9.1 KB
examples/modular-frontend-CLAUDE.mdmarkdown10.5 KB
examples/modular-root-CLAUDE.mdmarkdown6.4 KB
examples/python-api-CLAUDE.mdmarkdown13.0 KB
expected_output.jsonconfig9.8 KB
generator.pyscript19.1 KB
sample_input.jsonconfig4.4 KB
template_selector.pyscript16.7 KB
validator.pyscript14.9 KB
workflow.pyscript15.5 KB

generator.py

View on GitHub
"""
CLAUDE.md Content Generator

Generates new CLAUDE.md files or enhances existing ones based on templates and analysis.
Supports modular architecture with context-specific files.
"""

from typing import Dict, List, Any, Optional
from template_selector import TemplateSelector
import re


class ContentGenerator:
    """Generates and enhances CLAUDE.md files based on project context."""

    def __init__(self, project_context: Dict[str, Any]):
        """
        Initialize content generator with project context.

        Args:
            project_context: Dictionary containing project type, tech_stack, team_size, etc.
        """
        self.project_context = project_context
        self.template_selector = TemplateSelector(project_context)

    def generate_root_file(self) -> str:
        """
        Generate root CLAUDE.md file (navigation hub).

        Returns:
            Complete CLAUDE.md content as string
        """
        template = self.template_selector.select_template()

        # Use template selector's customization
        if template.get('modular_recommended'):
            return self._generate_modular_root(template)
        else:
            return self._generate_standalone_file(template)

    def _generate_modular_root(self, template: Dict[str, Any]) -> str:
        """Generate root file for modular architecture (navigation hub)."""
        lines = []

        # Title
        lines.append("# CLAUDE.md")
        lines.append("")
        lines.append(f"This file provides top-level guidance for Claude Code when working with this {self.project_context.get('type', 'project')}.")
        lines.append("")

        # Quick Navigation
        lines.append("## Quick Navigation")
        lines.append("")
        lines.extend(self._generate_navigation_section(template))
        lines.append("")

        # Core Principles (concise, 5-7 principles)
        lines.append("## Core Principles")
        lines.append("")
        principles = self._generate_core_principles(template, max_count=5)
        lines.extend(principles)
        lines.append("")

        # Tech Stack (summary only)
        if self.project_context.get('tech_stack'):
            lines.append("## Tech Stack")
            lines.append("")
            lines.extend(self._generate_tech_stack_summary())
            lines.append("")

        # Key Commands/Shortcuts
        lines.append("## Quick Reference")
        lines.append("")
        lines.extend(self._generate_quick_reference())
        lines.append("")

        # Footer
        lines.append("---")
        lines.append("")
        lines.append("For detailed guidelines, see context-specific CLAUDE.md files in subdirectories.")

        return '\n'.join(lines)

    def _generate_standalone_file(self, template: Dict[str, Any]) -> str:
        """Generate standalone CLAUDE.md file (all-in-one)."""
        return self.template_selector.customize_template(template)

    def generate_context_file(self, context: str) -> str:
        """
        Generate context-specific CLAUDE.md file (e.g., backend, frontend).

        Args:
            context: Context name ('backend', 'frontend', 'database', etc.)

        Returns:
            Context-specific CLAUDE.md content
        """
        generators = {
            'backend': self._generate_backend_file,
            'frontend': self._generate_frontend_file,
            'database': self._generate_database_file,
            'docs': self._generate_docs_file,
            '.github': self._generate_github_file
        }

        generator = generators.get(context, self._generate_generic_context_file)
        return generator()

    def _generate_backend_file(self) -> str:
        """Generate backend-specific CLAUDE.md."""
        lines = []
        lines.append("# Backend Development Guidelines")
        lines.append("")
        lines.append("This file provides guidance for backend development in this project.")
        lines.append("")

        # API Design
        lines.append("## API Design")
        lines.append("")
        lines.append("- Use RESTful conventions for API endpoints")
        lines.append("- Implement proper HTTP status codes (200, 201, 400, 404, 500)")
        lines.append("- Version APIs when breaking changes are needed (/api/v1/, /api/v2/)")
        lines.append("- Document all endpoints with OpenAPI/Swagger")
        lines.append("")

        # Database Guidelines
        lines.append("## Database Operations")
        lines.append("")
        lines.append("- Use migrations for all schema changes")
        lines.append("- Implement proper indexes for query performance")
        lines.append("- Use transactions for multi-step operations")
        lines.append("- Avoid N+1 queries - use joins or batch loading")
        lines.append("")

        # Error Handling
        lines.append("## Error Handling")
        lines.append("")
        lines.append("- Implement global error handling middleware")
        lines.append("- Log errors with context (request ID, user ID, timestamp)")
        lines.append("- Return consistent error response format")
        lines.append("- Never expose stack traces to clients in production")
        lines.append("")

        # Testing
        lines.append("## Testing Requirements")
        lines.append("")
        lines.append("- Write unit tests for business logic")
        lines.append("- Write integration tests for API endpoints")
        lines.append("- Mock external services in tests")
        lines.append("- Aim for 80%+ code coverage")
        lines.append("")

        return '\n'.join(lines)

    def _generate_frontend_file(self) -> str:
        """Generate frontend-specific CLAUDE.md."""
        lines = []
        lines.append("# Frontend Development Guidelines")
        lines.append("")
        lines.append("This file provides guidance for frontend development in this project.")
        lines.append("")

        # Component Standards
        lines.append("## Component Standards")
        lines.append("")
        tech_stack = [t.lower() for t in self.project_context.get('tech_stack', [])]

        if 'react' in tech_stack:
            lines.append("- Prefer functional components with hooks over class components")
            lines.append("- Use TypeScript for type safety")
            lines.append("- Keep components small and focused (< 200 lines)")
            lines.append("- Extract reusable logic into custom hooks")
        elif 'vue' in tech_stack:
            lines.append("- Use Composition API for complex components")
            lines.append("- Keep components small and focused (< 200 lines)")
            lines.append("- Use TypeScript with Vue 3")
            lines.append("- Extract reusable logic into composables")
        else:
            lines.append("- Keep components small and focused")
            lines.append("- Extract reusable logic into utilities")
            lines.append("- Use TypeScript for type safety")
        lines.append("")

        # State Management
        lines.append("## State Management")
        lines.append("")
        lines.append("- Keep component state local when possible")
        lines.append("- Use global state only for truly shared data")
        lines.append("- Avoid prop drilling - use context/store for deep state")
        lines.append("- Document state shape and update patterns")
        lines.append("")

        # Styling
        lines.append("## Styling Guidelines")
        lines.append("")
        lines.append("- Use consistent naming conventions (BEM, CSS Modules, etc.)")
        lines.append("- Avoid inline styles except for dynamic values")
        lines.append("- Use design tokens for colors, spacing, typography")
        lines.append("- Ensure responsive design for all breakpoints")
        lines.append("")

        # Performance
        lines.append("## Performance Optimization")
        lines.append("")
        lines.append("- Lazy load routes and heavy components")
        lines.append("- Optimize images (use WebP, lazy loading)")
        lines.append("- Minimize bundle size - code split where possible")
        lines.append("- Use memoization for expensive calculations")
        lines.append("")

        return '\n'.join(lines)

    def _generate_database_file(self) -> str:
        """Generate database-specific CLAUDE.md."""
        lines = []
        lines.append("# Database Guidelines")
        lines.append("")
        lines.append("This file provides guidance for database operations and migrations.")
        lines.append("")

        # Schema Design
        lines.append("## Schema Design")
        lines.append("")
        lines.append("- Use meaningful table and column names")
        lines.append("- Always include created_at and updated_at timestamps")
        lines.append("- Use proper foreign key constraints")
        lines.append("- Add indexes for frequently queried columns")
        lines.append("")

        # Migrations
        lines.append("## Migration Guidelines")
        lines.append("")
        lines.append("- Never edit existing migrations - create new ones")
        lines.append("- Test migrations on copy of production data")
        lines.append("- Include both up and down migrations")
        lines.append("- Document breaking changes in migration comments")
        lines.append("")

        # Query Optimization
        lines.append("## Query Optimization")
        lines.append("")
        lines.append("- Use EXPLAIN to analyze slow queries")
        lines.append("- Avoid SELECT * - specify needed columns")
        lines.append("- Use appropriate JOIN types")
        lines.append("- Limit result sets with pagination")
        lines.append("")

        return '\n'.join(lines)

    def _generate_docs_file(self) -> str:
        """Generate documentation-specific CLAUDE.md."""
        lines = []
        lines.append("# Documentation Guidelines")
        lines.append("")
        lines.append("This file provides guidance for project documentation.")
        lines.append("")

        lines.append("## Documentation Standards")
        lines.append("")
        lines.append("- Keep README.md updated with setup instructions")
        lines.append("- Document all public APIs with examples")
        lines.append("- Include architecture diagrams for complex systems")
        lines.append("- Maintain changelog with semantic versioning")
        lines.append("")

        return '\n'.join(lines)

    def _generate_github_file(self) -> str:
        """Generate .github-specific CLAUDE.md for CI/CD."""
        lines = []
        lines.append("# CI/CD Workflows")
        lines.append("")
        lines.append("This file provides guidance for GitHub Actions and CI/CD processes.")
        lines.append("")

        lines.append("## Workflow Guidelines")
        lines.append("")
        lines.append("- Run linting and tests on all pull requests")
        lines.append("- Automate deployments to staging on main branch")
        lines.append("- Require manual approval for production deployments")
        lines.append("- Cache dependencies to speed up builds")
        lines.append("")

        return '\n'.join(lines)

    def _generate_generic_context_file(self) -> str:
        """Generate generic context-specific file."""
        return "# Context-Specific Guidelines\n\n[Add guidelines specific to this context]\n"

    def generate_section(self, section_name: str) -> str:
        """
        Generate a specific section for CLAUDE.md.

        Args:
            section_name: Name of section to generate

        Returns:
            Section content as string
        """
        generators = {
            'Core Principles': self._generate_core_principles_section,
            'Tech Stack': self._generate_tech_stack_section,
            'Workflow Instructions': self._generate_workflow_section,
            'Testing Requirements': self._generate_testing_section,
            'Error Handling': self._generate_error_handling_section,
            'Documentation Standards': self._generate_documentation_section
        }

        generator = generators.get(section_name, self._generate_generic_section)
        return generator(section_name)

    def _generate_core_principles_section(self, section_name: str) -> str:
        """Generate Core Principles section."""
        template = self.template_selector.select_template()
        lines = [f"## {section_name}", ""]
        lines.extend(self._generate_core_principles(template, max_count=7))
        return '\n'.join(lines)

    def _generate_tech_stack_section(self, section_name: str) -> str:
        """Generate Tech Stack section."""
        lines = [f"## {section_name}", ""]
        lines.extend(self._generate_tech_stack_summary())
        return '\n'.join(lines)

    def _generate_workflow_section(self, section_name: str) -> str:
        """Generate Workflow Instructions section."""
        lines = [f"## {section_name}", ""]

        workflows = self.project_context.get('workflows', [])
        if workflows:
            for i, workflow in enumerate(workflows, 1):
                workflow_title = workflow.replace('_', ' ').title()
                lines.append(f"{i}. **{workflow_title}**: [Add {workflow} workflow description]")
        else:
            lines.append("[Add workflow instructions specific to your project]")

        return '\n'.join(lines)

    def _generate_testing_section(self, section_name: str) -> str:
        """Generate Testing Requirements section."""
        lines = [f"## {section_name}", ""]
        lines.append("- Write tests before or alongside feature implementation")
        lines.append("- Maintain minimum 80% code coverage")
        lines.append("- Include unit, integration, and e2e tests")
        lines.append("- Mock external dependencies in tests")
        return '\n'.join(lines)

    def _generate_error_handling_section(self, section_name: str) -> str:
        """Generate Error Handling section."""
        lines = [f"## {section_name}", ""]
        lines.append("- Implement comprehensive error handling from the start")
        lines.append("- Log errors with context (user ID, request ID, timestamp)")
        lines.append("- Provide helpful error messages to users")
        lines.append("- Never expose sensitive information in error messages")
        return '\n'.join(lines)

    def _generate_documentation_section(self, section_name: str) -> str:
        """Generate Documentation Standards section."""
        lines = [f"## {section_name}", ""]
        lines.append("- Keep documentation in sync with code")
        lines.append("- Document all public APIs and interfaces")
        lines.append("- Include code examples in documentation")
        lines.append("- Update README.md with setup and usage instructions")
        return '\n'.join(lines)

    def _generate_generic_section(self, section_name: str) -> str:
        """Generate generic section placeholder."""
        return f"## {section_name}\n\n[Add {section_name.lower()} guidelines specific to your project]\n"

    def merge_with_existing(self, existing_content: str, new_sections: List[str]) -> str:
        """
        Merge new sections with existing CLAUDE.md content.

        Args:
            existing_content: Current CLAUDE.md content
            new_sections: List of new sections to add

        Returns:
            Merged content as string
        """
        lines = existing_content.split('\n')
        existing_sections = self._extract_existing_sections(existing_content)

        # Add new sections that don't already exist
        for new_section in new_sections:
            section_name = new_section.split('\n')[0].replace('## ', '')
            if section_name not in existing_sections:
                lines.append("")
                lines.append(new_section)

        return '\n'.join(lines)

    def _extract_existing_sections(self, content: str) -> List[str]:
        """Extract section names from existing content."""
        sections = []
        for line in content.split('\n'):
            if line.startswith('## '):
                sections.append(line[3:].strip())
        return sections

    def _generate_navigation_section(self, template: Dict[str, Any]) -> List[str]:
        """Generate navigation section for modular architecture."""
        project_type = self.project_context.get('type')
        links = []

        if project_type == 'fullstack':
            links.append("- [Backend Guidelines](backend/CLAUDE.md)")
            links.append("- [Frontend Guidelines](frontend/CLAUDE.md)")
            links.append("- [Database Operations](database/CLAUDE.md)")

        if 'cicd' in self.project_context.get('workflows', []):
            links.append("- [CI/CD Workflows](.github/CLAUDE.md)")

        if not links:
            links.append("- [Add links to context-specific CLAUDE.md files]")

        return links

    def _generate_core_principles(self, template: Dict[str, Any], max_count: int = 7) -> List[str]:
        """Generate core principles list."""
        principles = []
        workflows = self.project_context.get('workflows', [])

        # Add workflow-based principles
        if 'tdd' in workflows:
            principles.append("1. **Test-Driven Development**: Write tests before implementation")

        # Add tech-specific principles
        tech_custom = template.get('tech_customization', {})
        for guideline in tech_custom.get('specific_guidelines', [])[:3]:
            principle_num = len(principles) + 1
            principles.append(f"{principle_num}. **{guideline.split(':')[0] if ':' in guideline else 'Guideline'}**: {guideline}")

        # Add generic essential principles
        generic = [
            "**Code Quality**: Maintain high code quality with clear, readable implementations",
            "**Documentation**: Keep documentation in sync with code changes",
            "**Error Handling**: Implement comprehensive error handling from the start",
            "**Performance**: Consider performance implications in implementation decisions",
            "**Security**: Follow security best practices and avoid common vulnerabilities"
        ]

        for principle in generic:
            if len(principles) >= max_count:
                break
            principle_num = len(principles) + 1
            principles.append(f"{principle_num}. {principle}")

        return principles

    def _generate_tech_stack_summary(self) -> List[str]:
        """Generate tech stack summary."""
        lines = []
        template = self.template_selector.select_template()
        tech_custom = template.get('tech_customization', {})

        if tech_custom.get('languages'):
            lines.append(f"- **Languages**: {', '.join(tech_custom['languages'])}")

        if tech_custom.get('frameworks'):
            lines.append(f"- **Frameworks**: {', '.join(tech_custom['frameworks'])}")

        if tech_custom.get('tools'):
            lines.append(f"- **Tools**: {', '.join(tech_custom['tools'])}")

        if not lines:
            lines.append("- [Add your tech stack details here]")

        return lines

    def _generate_quick_reference(self) -> List[str]:
        """Generate quick reference commands."""
        lines = []
        lines.append("```bash")
        lines.append("# Common development commands")
        lines.append("npm test          # Run tests")
        lines.append("npm run lint      # Run linter")
        lines.append("npm run build     # Build for production")
        lines.append("```")
        return lines
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall