AI Rules

Supercharge your AI coding tools with framework-specific rules, skills, and best practices.

AI Rules installs curated configuration boilerplates that teach your AI tools your stack's conventions, patterns, and guardrails. Works with Claude Code, Cursor, GitHub Copilot, and Windsurf. Stop explaining the same things over and over — let your AI understand your architecture from the start.

Why Use This?

Quick Start

# Interactive setup (recommended)
npx @malamute/ai-rules init

# Or specify your stack directly
npx @malamute/ai-rules init angular nestjs

# Multi-tool setup
npx @malamute/ai-rules init angular --targets claude,cursor

That's it. Your AI tools now understand your stack.

Installation

# Global install
npm install -g @malamute/ai-rules

# Or use with npx (no install needed)
npx @malamute/ai-rules <command>

Supported AI Tools

Supported Technologies

Commands

ai-rules init [tech...]     # Install configs (interactive if no tech)
ai-rules add <tech>         # Add technology to existing installation
ai-rules update             # Update to latest rules
ai-rules status             # Show installation info
ai-rules list               # List available technologies

Options

By default, init installs everything (skills + shared rules) for Claude Code. Use --targets to install for multiple AI tools, and --minimal to skip extras.

What Gets Installed

Claude Code (default)

your-project/
├── CLAUDE.md                    # Your project-specific info (not touched)
└── .claude/
    ├── settings.json            # Allowed/denied commands
    ├── rules/                   # Framework-specific patterns
    │   ├── nextjs/
    │   │   ├── core.md          # Stack, architecture, conventions
    │   │   ├── components.md
    │   │   └── ...
    │   ├── conventions/         # Shared conventions
    │   │   └── core.md
    │   └── security/
    └── skills/                  # Optional workflows
        ├── learning/
        ├── review/
        └── debug/

Multi-target (e.g. --targets claude,cursor,copilot)

your-project/
├── .claude/                     # Claude Code
│   ├── settings.json
│   ├── rules/angular/core.md
│   └── skills/
├── .cursor/                     # Cursor
│   ├── rules/angular/core.mdc  # .mdc extension, paths → globs
│   └── .cursorrules             # Aggregated global rules
├── .github/                     # GitHub Copilot
│   ├── instructions/angular/core.instructions.md
│   └── copilot-instructions.md  # Aggregated global rules
└── .windsurf/                   # Windsurf
    ├── rules/angular/core.md    # paths → globs + trigger
    ├── global_rules.md          # Aggregated global rules
    └── workflows/               # Skills → Workflows

Note: Your project's CLAUDE.md is never modified. Use it for project-specific context (business domain, team conventions, etc.).

Rules

Context-aware rules that activate based on file paths:

---
paths:
  - '**/*.component.ts'
---

# Angular Component Rules

- Use `ChangeDetectionStrategy.OnPush`
- Use `input()`, `output()`, not decorators
- Template in separate `.html` file

Skills

Interactive workflows invoked with /skill-name:

Shared Rules

Cross-framework rules included by default (use --minimal to skip):

Recommended MCP Servers

MCP (Model Context Protocol) servers extend your AI tool's capabilities with framework-specific context. These are not installed by AI Rules — set them up manually via claude mcp add or ~/.claude/settings.json.

Tip: After adding an MCP server, verify with claude mcp list.

Examples

Fullstack Setup

# Angular frontend + NestJS backend
ai-rules init angular nestjs

# Next.js frontend + FastAPI backend
ai-rules init nextjs fastapi

# Add a technology to existing installation
ai-rules add nestjs

# Minimal install (no skills/shared rules)
ai-rules init angular --minimal

Multi-Tool Setup

# Install for Claude Code + Cursor
ai-rules init angular --targets claude,cursor

# Install for all supported tools
ai-rules init angular --targets claude,cursor,copilot,windsurf

# Install for Cursor only
ai-rules init angular --targets cursor

Preview Before Installing

ai-rules init angular --targets claude,cursor --dry-run

Output:

DRY RUN - No files will be modified

ℹ Would install to: /your/project
ℹ Targets: claude, cursor

ℹ Would install for Claude Code...
○   settings.json (create)
○   rules/angular/ (13 files)

ℹ Would install for Cursor...
○   rules/angular/ (13 files)
○   .cursorrules (aggregated global rules)

Summary:
  27 file(s) would be created
  0 file(s) would be modified

Update Configs

# Check current version
ai-rules status

# Preview updates
ai-rules update --dry-run

# Apply updates (auto-backup enabled, reinstalls all targets)
ai-rules update

Technology Conventions

How It Works

1. Rules are loaded by your AI tool based on file paths you're editing
2. rules/core.md with alwaysApply: true provides framework conventions
3. Skills are invoked on-demand with /skill-name (Claude Code only)
4. Settings define what commands Claude can run (Claude Code only)
5. Adapters transform rules to each tool's format automatically:
   • Claude: paths frontmatter, .md extension
   • Cursor: globs frontmatter, .mdc extension
   • Copilot: applyTo frontmatter, .instructions.md extension
   • Windsurf: globs + trigger: glob frontmatter, .md extension

Your project's CLAUDE.md stays clean for project-specific context, while framework conventions live in rules.

Contributing

# Clone and install
git clone https://github.com/malamute/ai-rules.git
cd ai-rules
npm install

# Run tests
npm test

# Add a new technology
mkdir -p configs/your-tech/rules
# Add rules/core.md and other rules

Adding a Technology

1. Create configs/[tech]/rules/core.md with framework conventions
2. Add rules in configs/[tech]/rules/
3. Add configs/[tech]/settings.json for permissions
4. Add tests
5. Submit a PR

See CONTRIBUTING.md for details on skills structure.

License

MIT © Mehdi Chaabi