rulegen

Analyze codebases and auto-generate AI coding rules for Claude Code, Cursor, Codex, and more

---

Why This Exists

Every developer using AI coding assistants (Claude Code, Cursor, Codex, Cline) needs a rules file -- CLAUDE.md, .cursorrules, codex.md, .clinerules. Writing these by hand is tedious: you have to describe your project's language, frameworks, conventions, test setup, and architectural patterns from scratch. Every time.

rulegen scans your codebase, detects everything automatically, and generates platform-specific rules in seconds. Not templates. Actual analysis of your code -- naming conventions, indentation, frameworks, linters, test setup, CI/CD, and more.

$ rulegen .
Generated CLAUDE.md (23 rules) -> /path/to/project/CLAUDE.md

What It Detects

Category	Examples
Languages	Python, TypeScript, JavaScript, Go, Rust, Java, C#, Ruby, and 20+ more
Frameworks	FastAPI, Django, Flask, Next.js, React, Vue, Express, NestJS, Gin, Echo, Axum, and more
Test frameworks	pytest, Jest, Vitest, Mocha, Playwright, Cypress, Go test
Linters	ESLint, Ruff, Pylint, Flake8, golangci-lint, Clippy, Biome
Formatters	Prettier, Black, isort, rustfmt, editorconfig
Package managers	npm, yarn, pnpm, bun, pip, Poetry, Pipenv, Go modules, Cargo
CI/CD	GitHub Actions, GitLab CI, CircleCI, Jenkins, Travis
Conventions	Naming style, indentation, docstring format, type annotations, strict mode
Structure	Source/test/doc directories, monorepo detection

Installation

pip install rulegen

Or run directly:

python -m rulegen .

Quick Start

Generate CLAUDE.md (default)

rulegen /path/to/project

Generate for Cursor

rulegen . --platform cursor

Generate for all platforms at once

rulegen . --platform all

This generates CLAUDE.md, .cursorrules, codex.md, and .clinerules in one command.

Preview without writing files

rulegen . --dry-run

Analyze only (JSON output)

rulegen . --analyze-only --format json

CLI Reference

rulegen [PATH] [OPTIONS]

Arguments:
  PATH                    Path to analyze (default: current directory)

Options:
  -p, --platform PLATFORM  Target: claude, cursor, codex, cline, all (default: claude)
  -o, --output PATH        Custom output file path
  -n, --dry-run            Preview output without writing files
  -a, --analyze-only       Only analyze, don't generate rules
  -f, --format FORMAT      Output format for --analyze-only: text, json
      --include CATS       Only include these rule categories (comma-separated)
      --exclude CATS       Exclude these rule categories (comma-separated)
  -v, --verbose            Show detailed analysis information
  -V, --version            Show version

Rule Categories

Filter rules with --include or --exclude:

Category	Description
style	Naming, indentation, formatting, linters
architecture	Directory structure, framework patterns, monorepo
testing	Test framework, test patterns, coverage
dependencies	Package manager, version pinning
security	Secrets, input validation, framework security
documentation	Docstrings, doc directories
workflow	CI/CD configuration

Example:

# Only style and testing rules
rulegen . --include style,testing

# Everything except security rules
rulegen . --exclude security

Output Example

For a Python FastAPI project with pytest, ruff, and GitHub Actions:

# Project Rules

> Auto-generated by rulegen. Review and customize as needed.

## Project Overview

Languages: Python (100.0%)
Frameworks: FastAPI
Package Manager: pip
Test Framework: pytest
Linters: ruff
Formatters: black
CI/CD: github-actions

## Code Style

- **[MUST]** Use snake_case naming convention
  This codebase uses snake_case for identifiers. Follow this convention for all new code.
- **[MUST]** Use 4-space indentation
  This project uses 4-space indentation. Maintain consistent indentation in all files.
- **[SHOULD]** Use type annotations
  This codebase uses type annotations in Python. Add type annotations to all new functions.
- **[SHOULD]** Use google-style docstrings
  Follow the google docstring convention for all public functions and classes.
- **[MUST]** Code must pass ruff
  All code must pass ruff checks. Run the ruff command before committing.
- **[MUST]** Format code with black
  Use black to format all code. Run black before committing.

## Architecture

- **[MUST]** Follow existing directory structure
  Source code is organized in: src. Place new source files in the appropriate directory.
- **[SHOULD]** Follow FastAPI patterns
  Use dependency injection for services. Define Pydantic models for request/response schemas.

## Testing

- **[MUST]** Use pytest for tests
  This project uses pytest. Write tests using this framework for all new features.
- **[MUST]** Place tests in tests
  Test files should be placed in: tests. Follow the existing test file naming convention.

...

Supported Platforms

Platform	File	Priority Format
Claude Code	CLAUDE.md	[MUST], [SHOULD], [MAY] with structured sections
Cursor	.cursorrules	Imperative instructions: "Always...", "Prefer to...", "Consider..."
Codex	codex.md	Required/Recommended split with HTML comment attribution
Cline	.clinerules	Numbered list with priority tags and bold titles

Architecture

rulegen/
  cli.py              # CLI interface
  models.py           # Data models (CodebaseProfile, Rule, RuleSet)
  scanner.py          # File system scanner with .gitignore support
  analyzer/
    language.py       # Language detection by file extension
    structure.py      # Directory structure analysis
    dependencies.py   # Framework/package manager detection
    testing.py        # Test framework detection
    config.py         # Linter/formatter/CI detection
    conventions.py    # Code convention analysis (naming, indent, etc.)
    pipeline.py       # Orchestrates all analyzers
  generator/
    claude.py         # CLAUDE.md generator
    cursor.py         # .cursorrules generator
    codex.py          # codex.md generator
    cline.py          # .clinerules generator
  rules/
    registry.py       # Rule generation from CodebaseProfile

Development

# Clone
git clone https://github.com/JSLEEKR/rulegen.git
cd rulegen

# Run tests
python -m pytest tests/ -v

# Run rulegen on itself
python -m rulegen . --dry-run

License

MIT