Step 1: Identify Project Root
Locate project root by finding manifest files:
Search for package manager files:
package.json (Node.js/JavaScript/TypeScript) requirements.txt, pyproject.toml, setup.py (Python) go.mod (Go) Cargo.toml (Rust) pom.xml, build.gradle (Java/Maven/Gradle) composer.json (PHP)
Identify project root:
Directory containing primary package manager file Handle monorepos (multiple package.json files) Detect workspace configuration
Validate project root:
Check for .git directory Verify source code directories exist Ensure manifest files are parsable Step 2: Detect Project Type
Classify project based on manifest files and directory structure:
Frontend Projects:
Indicators: React, Vue, Angular, Svelte dependencies Directory: src/components/, public/, assets/ Frameworks: Next.js, Nuxt.js, Gatsby, Vite
Backend Projects:
Indicators: Express, FastAPI, Django, Flask, Gin dependencies Directory: routes/, controllers/, models/, api/ Frameworks: Next.js API routes, FastAPI, Express
Fullstack Projects:
Indicators: Both frontend and backend frameworks Directory: Combined frontend + backend structure Frameworks: Next.js, Remix, SvelteKit, Nuxt.js
Library/Package Projects:
Indicators: No application-specific directories Files: index.ts, lib/, dist/, build/ Manifests: library field in package.json
CLI Projects:
Indicators: bin field in package.json Files: CLI entry points, command parsers Dependencies: Commander, Yargs, Inquirer
Mobile Projects:
Indicators: React Native, Flutter, Ionic dependencies Files: android/, ios/, mobile/ Frameworks: React Native, Expo, Flutter
Monorepo Projects:
Indicators: workspaces in package.json, pnpm-workspace.yaml Structure: Multiple packages in subdirectories Tools: Turborepo, Nx, Lerna
Microservices Projects:
Indicators: Multiple service directories Files: docker-compose.yml, service configs Structure: Service-based organization Step 3: Framework Detection
Identify frameworks from manifest files and imports:
Read package.json dependencies (Node.js):
Parse dependencies and devDependencies Detect framework versions Categorize by type (framework, ui-library, testing, etc.)
Read requirements.txt (Python):
Parse Python dependencies Detect FastAPI, Django, Flask Identify version constraints
Analyze imports (optional deep scan):
Scan source files for import statements Detect used vs declared dependencies Identify framework-specific patterns
Framework Categories:
Framework: React, Next.js, FastAPI, Express UI Library: Material-UI, Ant Design, Chakra UI State Management: Redux, Zustand, Pinia Testing: Jest, Vitest, Cypress, Playwright Build Tool: Vite, Webpack, Rollup, esbuild Database: Prisma, TypeORM, SQLAlchemy ORM: Prisma, Sequelize, Mongoose API: tRPC, GraphQL, REST Auth: NextAuth, Auth0, Clerk Logging: Winston, Pino, Bunyan Monitoring: Sentry, Datadog, New Relic
Confidence Scoring:
1.0: Framework listed in dependencies 0.8: Framework detected from imports 0.6: Framework inferred from structure Step 4: File Statistics
Generate quantitative project statistics:
Count files by type:
Use glob patterns for common extensions Exclude: node_modules/, .git/, dist/, build/ Group by language/file type
Count lines of code:
Read source files and count lines Exclude empty lines and comments (optional) Calculate total LOC per language
Identify largest files:
Track file sizes (line count) Report top 10 largest files Flag files > 1000 lines (violates micro-service principle)
Calculate averages:
Average file size (lines) Average directory depth Files per directory
Language Detection:
Map extensions to languages: .ts, .tsx → TypeScript .js, .jsx → JavaScript .py → Python .go → Go .rs → Rust .java → Java .md → Markdown .json → JSON .yaml, .yml → YAML Step 5: Structure Analysis
Analyze project structure and architecture:
Identify root directories:
Classify directories by purpose: source: src/, app/, lib/ tests: test/, tests/, cypress/ config: config/, .config/ docs: docs/, documentation/ build: dist/, build/, out/ scripts: scripts/, bin/ assets: assets/, static/, public/
Detect entry points:
Main entry: index.ts, main.py, app.py App entry: app.ts, server.ts, app/page.tsx Handler: handler.ts, lambda.ts CLI: cli.ts, bin/
Detect architecture pattern:
MVC: models/, views/, controllers/ Layered: presentation/, business/, data/ Hexagonal: domain/, application/, infrastructure/ Microservices: Multiple service directories Modular: Feature-based organization Flat: All files in src/
Detect module system:
Check package.json for "type": "module" (ESM) Scan for import/export (ESM) vs require (CommonJS) Identify mixed module systems Step 6: Dependency Analysis
Analyze dependency health:
Count dependencies:
Production dependencies Development dependencies Total dependency count
Check for outdated packages (optional):
Run npm outdated or equivalent Parse output for outdated packages Identify major version updates (breaking changes)
Security scan (optional):
Run npm audit or equivalent Identify vulnerabilities by severity Flag critical security issues Step 7: Code Quality Indicators
Detect code quality tooling:
Linting Configuration:
Detect: .eslintrc.json, eslint.config.js, ruff.toml Tool: ESLint, Ruff, Flake8, Pylint Run linter if configured (optional)
Formatting Configuration:
Detect: .prettierrc, pyproject.toml (Black/Ruff) Tool: Prettier, Black, Ruff
Testing Framework:
Detect: Jest, Vitest, Pytest, Cypress Count test files Check for coverage configuration
Type Safety:
Detect TypeScript: tsconfig.json Check strict mode: "strict": true Detect Python typing: mypy, pyright Step 8: Pattern Detection
Identify common patterns and anti-patterns:
Good Practices:
Modular component structure Comprehensive test coverage TypeScript strict mode enabled CI/CD configuration present
Anti-Patterns:
Large files (> 1000 lines) Missing tests Outdated dependencies No linting configuration
Neutral Patterns:
Specific architecture choices Framework-specific patterns Step 9: Technical Debt Analysis
Calculate technical debt score:
Debt Indicators:
Outdated Dependencies: Count outdated packages Missing Tests: Low test file ratio Dead Code: Unused imports/exports (optional) Complexity: Large files, deep nesting Documentation: Missing README, docs Security: Known vulnerabilities Performance: Bundle size, load time
Debt Score (0-100):
0-20: Excellent health 21-40: Good health, minor issues 41-60: Moderate debt, needs attention 61-80: High debt, refactoring recommended 81-100: Critical debt, major overhaul needed
Remediation Effort:
Trivial: < 1 hour Minor: 1-4 hours Moderate: 1-3 days Major: 1-2 weeks Massive: > 2 weeks Step 10: Generate Recommendations
Create prioritized improvement recommendations:
Categorize Recommendations:
Security: Critical vulnerabilities, outdated auth Performance: Bundle optimization, lazy loading Maintainability: Refactor large files, add tests Testing: Increase coverage, add E2E tests Documentation: Add README, API docs Architecture: Improve modularity, separation of concerns Dependencies: Update packages, remove unused
Prioritize by Impact:
P0: Critical security, blocking production P1: High impact, affects reliability P2: Medium impact, improves quality P3: Low impact, nice-to-have
Estimate Effort and Impact:
Effort: trivial, minor, moderate, major, massive Impact: low, medium, high, critical Step 11: Validate Output
Validate analysis output against schema:
Schema Validation:
Validate against project-analysis.schema.json Ensure all required fields present Check data types and formats
Output Metadata:
Analyzer version Analysis duration (ms) Files analyzed count Files skipped count Errors encountered
Target: < 30 seconds for typical projects (< 10k files) Optimization: Skip large directories: node_modules/, .git/, dist/ Use parallel file processing Cache results for incremental analysis Limit deep scans to essential files Use streaming for large file counts
Integration with Other Skills:
rule-selector: Auto-select rules based on detected frameworks repo-rag: Semantic search for architectural patterns dependency-analyzer: Deep dependency analysis
Progressive Disclosure: Start with manifest analysis, add deep scans if needed Performance First: Skip expensive operations for large projects Fail Gracefully: Handle missing files, parse errors Validate Output: Always validate against schema Cache Results: Store analysis output for reuse Incremental Updates: Re-analyze only changed files
Analyze current project
node .claude/tools/project-analyzer/analyzer.mjs
Analyze specific directory
node .claude/tools/project-analyzer/analyzer.mjs /path/to/project
Output to file
node .claude/tools/project-analyzer/analyzer.mjs --output .claude/context/artifacts/project-analysis.json
Run tests
node .claude/tools/project-analyzer/tests/analyzer.test.mjs
Agent Invocation:
Analyze current project
Analyze this project
Generate comprehensive analysis
Perform full project analysis and save to artifacts
Quick analysis (manifest only)
Quick project type detection
{ "analysis_id": "analysis-llm-rules-20250115", "project_type": "fullstack", "analyzed_at": "2025-01-15T10:30:00.000Z", "project_root": "C:\dev\projects\LLM-RULES", "stats": { "total_files": 1243, "total_lines": 125430, "languages": { "JavaScript": 45230, "TypeScript": 38120, "Markdown": 25680, "JSON": 12400, "YAML": 4000 }, "file_types": { ".js": 234, ".mjs": 156, ".ts": 89, ".md": 312, ".json": 145 }, "directories": 87, "avg_file_size_lines": 101, "largest_files": [ { "path": ".claude/tools/enforcement-gate.mjs", "lines": 1520 } ] }, "frameworks": [ { "name": "nextjs", "version": "14.0.0", "category": "framework", "confidence": 1.0, "source": "package.json" }, { "name": "react", "version": "18.2.0", "category": "framework", "confidence": 1.0, "source": "package.json" } ], "structure": { "root_directories": [ { "name": ".claude", "purpose": "config", "file_count": 543 }, { "name": "conductor-main", "purpose": "source", "file_count": 234 } ], "entry_points": [ { "path": "conductor-main/src/index.ts", "type": "main" } ], "architecture_pattern": "modular", "module_system": "esm" }, "dependencies": { "production": 45, "development": 23 }, "code_quality": { "linting": { "configured": true, "tool": "eslint" }, "formatting": { "configured": true, "tool": "prettier" }, "testing": { "framework": "vitest", "test_files": 89, "coverage_configured": true }, "type_safety": { "typescript": true, "strict_mode": true } }, "tech_debt": { "score": 35, "indicators": [ { "category": "complexity", "severity": "medium", "description": "3 files exceed 1000 lines", "remediation_effort": "moderate" } ] }, "recommendations": [ { "priority": "P1", "category": "maintainability", "title": "Refactor large files", "description": "Break down files > 1000 lines into smaller modules", "effort": "moderate", "impact": "high" } ], "metadata": { "analyzer_version": "1.0.0", "analysis_duration_ms": 2340, "files_analyzed": 1243, "files_skipped": 3420, "errors": [] } }
References
For additional detection patterns extracted from the Auto-Claude analysis framework, see:
references/auto-claude-patterns.md - Monorepo indicators, SERVICE_INDICATORS, SERVICE_ROOT_FILES, infrastructure detection, convention detection references/service-patterns.md - Service type detection (frontend, backend, library), framework-specific patterns, entry point detection references/database-patterns.md - Database configuration file patterns, ORM detection (Prisma, SQLAlchemy, TypeORM, Drizzle, Mongoose), connection string patterns references/route-patterns.md - Express, FastAPI, Flask, Django, Next.js, Go, Rust API route detection patterns
These references provide comprehensive regex patterns and detection logic for brownfield codebase analysis.
Memory Protocol (MANDATORY)
Before starting: Read .claude/context/memory/learnings.md
After completing:
New pattern -> .claude/context/memory/learnings.md Issue found -> .claude/context/memory/issues.md Decision made -> .claude/context/memory/decisions.md
ASSUME INTERRUPTION: If it's not in memory, it didn't happen.