A specialized Claude agent that analyzes project repositories and provides actionable recommendations to align them with community best practices and industry standards.
The Repository Expert agent comprehensively analyzes your codebase structure, identifies organizational issues, and generates detailed reports with prioritized recommendations for improvement. It acts as an automated code organization consultant that understands best practices across multiple programming languages and frameworks.
- Multi-Language Support: Analyzes Node.js, Python, Go, Rust, Java, Ruby, C#/.NET projects
- Framework Detection: Recognizes Next.js, Vite, Django, Rails, Angular, and other popular frameworks
- Comprehensive Analysis: Examines directory structure, file organization, configuration, and compliance
- Prioritized Recommendations: Categorizes issues by urgency (Critical/Important/Enhancement)
- Actionable Output: Generates implementation scripts and configuration templates
- Visual Reports: Creates Mermaid diagrams showing current vs. recommended structure
- Security Analysis: Identifies exposed secrets and security anti-patterns
- Performance Optimization: Suggests improvements for build times and repository size
The agent follows a systematic 4-phase analysis process:
- Project Type Detection: Identifies language and framework from key files
- Structure Mapping: Maps directory tree and analyzes organization patterns
- Standards Compliance: Checks for documentation, CI/CD, testing, and code quality tools
- Language Standards: Compares against established conventions for each ecosystem
- Framework Patterns: Applies framework-specific organizational requirements
- Project Scale: Adjusts recommendations based on project size and complexity
- Executive Summary: High-level overview with organization score
- Detailed Findings: Categorized analysis of current state
- Priority Matrix: Critical → Important → Enhancement classification
- Implementation Guide: Step-by-step instructions for improvements
- Structure Diagrams: Before/after visualizations using Mermaid
- Migration Path: Clear roadmap for reorganization
- Templates: Ready-to-use configuration files and boilerplates
This agent works with Claude Code. To use it:
- Save the agent definition to
~/.claude/agents/repo-expert.md - Invoke the agent in Claude Code
@agent repo-expert "Analyze this repository structure and provide recommendations"
@agent repo-expert "Analyze this Next.js project for best practices compliance"
@agent repo-expert "Focus on security issues in this repository organization"
@agent repo-expert "Analyze this monorepo and suggest improvements for team workflow"
The agent generates several deliverables:
# Repository Analysis Report
Generated: [timestamp]
Repository: [repo-name]
## Executive Summary
- **Project Type:** React/TypeScript Web App
- **Organization Score:** 6/10
- **Critical Issues:** 3
- **Quick Wins:** 5
## Current Structure Analysis
### ✅ What's Working Well
- TypeScript configuration is comprehensive
- Testing infrastructure exists
### ⚠️ Areas for Improvement
- Source files mixed with config in root
- Inconsistent import paths
### 🚫 Critical Issues
- No .gitignore for sensitive files
- Missing CI/CD pipeline
## Priority-Based Recommendations
### 🔥 Priority 1: Critical (Fix This Week)
- Create comprehensive .gitignore
- Move source files to src/ directory
- Set up GitHub Actions workflow
### ⚡ Priority 2: Important (Fix This Month)
- Standardize directory naming conventions
- Separate concerns into modules
- Add pre-commit hooks
### 💡 Priority 3: Enhancement (Fix Eventually)
- Implement absolute import paths
- Add Storybook for component development
- Set up automated dependency updates
#!/bin/bash
# Repository Organization Script
# Generated by Repository Organization Expert
echo "🚀 Starting repository reorganization..."
# Create standard directories
mkdir -p src/{components,lib,types} tests/{unit,integration} docs scripts
# Move source files
find . -name "*.ts" -not -path "./node_modules/*" -exec mv {} src/ \;
# Create .gitignore
cat > .gitignore << 'EOF'
node_modules/
dist/
.env
.env.local
*.log
EOF
echo "✅ Reorganization complete!"
- Language-specific .gitignore files
- CI/CD workflow templates
- Linting and formatting configurations
- README templates
Mermaid diagrams showing current issues and recommended structure with migration paths.
- Node.js/JavaScript/TypeScript: React, Vue, Angular, Express, etc.
- Python: Django, Flask, FastAPI, CLI tools, data science projects
- Go: Web services, CLI tools, microservices
- Rust: CLI tools, web services, system programming
- Java: Spring Boot, Maven/Gradle projects
- Ruby: Rails applications, gems
- C#/.NET: Web APIs, console applications
- Web applications (SPA, SSR, static sites)
- API services and microservices
- Command-line tools
- Libraries and packages
- Mobile applications
- Documentation sites
- Monorepos and multi-package projects
The agent automatically adapts its recommendations based on:
- Project Size: Different standards for small/medium/large projects
- Team Context: Respects existing conventions in CONTRIBUTING.md
- Framework Requirements: Follows framework-specific patterns
- Monorepo Detection: Adjusts for Lerna, Nx, Rush configurations
To improve the Repository Expert agent:
- Add New Language Support: Extend the best practices mapping section
- Framework Patterns: Add detection and conventions for new frameworks
- Templates: Contribute configuration templates for different toolchains
- Analysis Rules: Suggest new organizational anti-patterns to detect
- Output Formats: Propose new report formats or visualization types
Areas particularly welcome for contribution:
- Mobile development patterns (React Native, Flutter)
- DevOps and infrastructure as code patterns
- Data science project structures
- Documentation site generators beyond standard patterns
MIT License - Feel free to use, modify, and distribute this agent definition.
Generated by: Repository Organization Expert Agent
Compatibility: Claude with changeling system
Last Updated: August 2025