The Problem

You use AI coding agents. Maybe Claude Code, maybe Cursor, maybe both. Each has its own rules file:

| Agent | File | |-------|------| | Claude Code | CLAUDE.md | | Cursor | .cursorrules | | Windsurf | .windsurfrules | | GitHub Copilot | .github/copilot-instructions.md | | Gemini | .gemini/settings.json |

They're all slightly different. They get out of sync. They get bloated until the AI ignores them. You wrote them by hand and half the rules are too vague to be useful.

The Solution

npx agentrules init

Scans your codebase, detects your stack, generates rules for all your agents. One command.

Detected: Next.js 15 + TypeScript + Tailwind + Prisma + Vitest

Generated 24 rules from your stack:
  12 from detected frameworks
   8 from @agentrules/nextjs pack
   4 from @agentrules/typescript pack

Wrote:
  CLAUDE.md (24 rules)
  .cursorrules (24 rules)
  .github/copilot-instructions.md (24 rules)

Install

npm install -g agentrules
# or use directly
npx agentrules init

Quick Start

# 1. Generate rules from your codebase
npx agentrules init

# 2. Check rule quality
npx agentrules lint

# 3. Add community rule packs
npx agentrules add nextjs
npx agentrules add tailwind

# 4. Sync to all agents
npx agentrules sync

Commands

agentrules init

Scans your project and generates rules for all detected AI agents.

agentrules init                    # Auto-detect everything
agentrules init --agents claude,cursor  # Only generate for specific agents
agentrules init --force            # Overwrite existing rules

Detects:

• Framework (Next.js, React, Vue, Svelte, Express, FastAPI, Django...)
• Language (TypeScript, JavaScript, Python, Go, Rust...)
• Package manager (npm, yarn, pnpm, bun, pip, cargo...)
• Testing (Jest, Vitest, Pytest, Go test...)
• Linter/formatter (ESLint, Prettier, Biome, Black, Ruff...)
• Database (Prisma, Drizzle, Supabase, SQLAlchemy...)
• CSS (Tailwind, CSS Modules, styled-components...)
• Monorepo (Turborepo, Nx, Lerna...)

agentrules sync

Syncs your source-of-truth rules to all agent formats.

agentrules sync                    # Sync to all agents
agentrules sync --agents claude    # Sync to specific agent
agentrules sync --dry-run          # Preview without writing

Your rules live in .agentrules/rules.md. Edit that file, run sync, and every agent gets the update.

agentrules lint

Catches problems in your rules before they confuse your AI.

agentrules lint

Catches:

• Rules that are too vague ("write good code")
• Contradictory rules ("always use semicolons" + "never use semicolons")
• Duplicate rules
• File too long (AI agents ignore bloated rule files)
• Missing rules for your detected stack

  2 errors, 3 warnings

  error  Line 14: Rule is too vague: "Write clean code"
         Suggestion: Specify what "clean" means for your project

  error  Line 23 conflicts with Line 45:
         "Always use arrow functions" vs "Use function declarations for hoisting"

  warn   Rules file is 847 lines. AI agents lose accuracy above 500 lines.
         Consider splitting into essential vs nice-to-have rules.

  warn   No testing rules found. Your stack uses Vitest.
         Run: agentrules add testing

  warn   Duplicate rule on lines 34 and 67:
         Both say "Use TypeScript strict mode"

agentrules add <pack>

Install community rule packs for your framework.

agentrules add nextjs              # Next.js best practices
agentrules add react               # React patterns
agentrules add typescript          # TypeScript conventions
agentrules add tailwind            # Tailwind CSS
agentrules add supabase            # Supabase patterns
agentrules add prisma              # Prisma ORM
agentrules add testing             # Testing best practices
agentrules add python              # Python conventions

agentrules doctor

Health check for your entire rules setup.

agentrules doctor

Rules Health Check
  Source of truth: .agentrules/rules.md (24 rules)
  Config: .agentrules/config.json

  Agent Files:
    CLAUDE.md           24 rules  in sync
    .cursorrules        22 rules  OUT OF SYNC (2 rules missing)
    .windsurfrules      not found

  Quality:
    Rule count: 24 (good, under 50)
    Avg length: 12 words (good)
    Vague rules: 0
    Contradictions: 0

  Overall: 8/10

agentrules diff

See what's different across your agent files.

agentrules diff

Shows colorized output of rules that are present in some agents but missing from others.

Rule Packs

Built-in Packs

| Pack | Rules | Description | |------|-------|-------------| | nextjs | 15 | App Router, server components, next/image, API routes | | react | 12 | Hooks, component patterns, state management | | typescript | 14 | Strict mode, type safety, generics, utility types | | python | 12 | Type hints, virtual envs, async patterns | | tailwind | 10 | Utility-first patterns, responsive design, dark mode | | supabase | 10 | RLS, edge functions, realtime, auth | | prisma | 8 | Schema design, migrations, client usage | | testing | 12 | Test structure, mocking, assertion patterns |

Example: Next.js Pack

- Use the App Router exclusively. Never suggest Pages Router patterns.
- Components are server components by default. Only add 'use client' when the component needs browser APIs, event handlers, or React state/effects.
- Use next/image for all images. Never use raw <img> tags.
- Use next/link for all internal navigation. Never use <a> tags for internal links.
- Use Route Handlers (app/api/) for API endpoints. Include proper HTTP method exports.
- Use server actions for form mutations. Prefer them over API routes for data mutations.
- Put shared layouts in layout.tsx files at the appropriate route level.
- Use loading.tsx for suspense boundaries, not manual Suspense components.
- Use error.tsx for error boundaries at route levels.
- Static pages should use generateStaticParams for SSG.

Contributing a Pack

Create a PR adding a new file to src/packs/. Each pack exports:

export const pack = {
  name: 'my-framework',
  description: 'Rules for My Framework',
  detect: (deps: string[]) => deps.includes('my-framework'),
  rules: [
    'Rule 1: Be specific about what the AI should do.',
    'Rule 2: Another actionable rule.',
  ]
};

Supported Agents

| Agent | File | Status | |-------|------|--------| | Claude Code | CLAUDE.md | Full support | | Cursor | .cursorrules | Full support | | Windsurf | .windsurfrules | Full support | | GitHub Copilot | .github/copilot-instructions.md | Full support | | Gemini CLI | .gemini/settings.json | Full support |

How It Works

1. Detection scans package.json, pyproject.toml, Cargo.toml, etc. for your stack
2. Generation builds rules from detected frameworks + installed packs
3. Rules are stored in .agentrules/rules.md (your single source of truth)
4. Sync converts rules to each agent's format and writes the files
5. Lint statically analyzes rules for quality issues

No AI calls. No cloud. Everything is deterministic and runs locally.

Config

.agentrules/config.json is auto-generated by init:

{
  "agents": ["claude", "cursor", "copilot"],
  "packs": ["nextjs", "typescript", "tailwind"],
  "detected": {
    "framework": "nextjs",
    "language": "typescript",
    "packageManager": "pnpm",
    "testing": "vitest",
    "css": "tailwind",
    "database": "prisma"
  }
}

FAQ

Q: Does this use AI/LLMs? No. All detection and rule generation is deterministic. No API keys needed.

Q: Will it overwrite my existing CLAUDE.md? Not without --force. By default, init will merge with existing rules and sync preserves any custom sections you've added.

Q: How is this different from rulesync? rulesync copies files between formats. agentrules auto-detects your stack, generates rules, lints for quality, and ships with community packs. It's the difference between cp and ESLint.

Q: Can I use this with just one agent? Yes. agentrules init --agents claude only generates CLAUDE.md.

License

MIT