Skip to content

Quick Start

Get AI-Rulez running in 5 minutes. This page covers the first two lifecycle stages, author and generate, then validates the result; Next steps points to bundling, publishing and governance.

ai-rulez init and generate: one .ai-rulez source becomes the native files of four AI tools

Step 1: Initialize Your Project

Create a new configuration:

ai-rulez init "my-project"

This creates a .ai-rulez/ directory with:

.ai-rulez/
├── config.toml
├── rules/
│   └── code-quality.md
├── context/
│   └── architecture.md
├── skills/
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── ai-rulez/
│       └── SKILL.md
└── agents/

Step 2: Configure Your Presets

Edit .ai-rulez/config.toml to specify which tools to generate for:

version = "5.0"
name = "my-project"
description = "My awesome project"

# Tools to generate configuration for
presets = ["claude", "cursor", "gemini"]

# Default profile when none specified
default = "full"

# Named profiles for different team needs
[profiles]
full = []  # Empty = root content only

Step 3: Add Your Rules

Create rule files in .ai-rulez/rules/:

.ai-rulez/rules/code-quality.md:

---
priority: high
---

# Code Quality

- Use meaningful variable names
- Comment complex logic
- All tests must pass before merge

.ai-rulez/rules/git-workflow.md:

---
priority: medium
---

# Git Workflow

1. Feature branches from main
2. Squash commits before merge
3. Require code review before merge

Step 4: Add Context Documentation

Create context files in .ai-rulez/context/:

.ai-rulez/context/architecture.md:

# Architecture

## System Design

- 3 microservices behind an API Gateway
- PostgreSQL for persistence
- Kubernetes for orchestration

## Stack

- Backend: Go
- Frontend: React
- Infrastructure: Kubernetes

Step 5: Define Skills (Optional)

Create specialized AI prompts in .ai-rulez/skills/:

.ai-rulez/skills/code-reviewer/SKILL.md:

---
priority: high
description: "Code reviewer for quality assurance"
---

# Code Reviewer

Review code for:

- Quality and maintainability
- Test coverage
- Performance issues

Responsibilities:

1. Review pull requests for correctness
2. Suggest improvements
3. Verify test coverage

Step 6: Generate Outputs

Generate configuration files for all your tools:

ai-rulez generate

This creates:

  • AGENTS.md and .agents/skills/ (shared by the presets that read them; agents_md is on by default)
  • CLAUDE.md, which imports @AGENTS.md, and .claude/rules/ (from claude preset; with the default split mode your path-scoped rules are in .claude/rules/)
  • .cursor/rules/ (from cursor preset)
  • .gemini/settings.json, which points Gemini at AGENTS.md (from gemini preset)

Set agents_md = false to get a separate file per tool (GEMINI.md, and so on) instead.

Step 7: Verify and Commit

Check that files were generated:

ls -la AGENTS.md CLAUDE.md .agents/skills/ .gemini/settings.json

Commit the sources and the generated files:

git add .ai-rulez/ AGENTS.md CLAUDE.md .agents/ .claude/ .cursor/ .gemini/
git commit -m "docs: initialize AI assistant configuration"

Generated files are not gitignored by default. To keep them out of git and let teammates run ai-rulez generate themselves, set gitignore = true in config.toml (or pass generate --gitignore); generate then maintains a managed block in .gitignore.

Personal notes that should not be shared go in .ai-rulez/local/ (ai-rulez add rule my-notes --local); see Local Configuration.

Multi-Team Setup

For projects with multiple teams, add domains:

1. Create domain structure:

mkdir -p .ai-rulez/domains/backend/rules
mkdir -p .ai-rulez/domains/frontend/rules

2. Add domain-specific rules:

.ai-rulez/domains/backend/rules/database.md:

---
priority: critical
---

# Database Standards

- Use prepared statements
- Add migrations for schema changes
- Index foreign keys

3. Update config.toml:

version = "5.0"
name = "my-platform"

presets = ["claude", "cursor"]

default = "full"

[profiles]
full = ["backend", "frontend"]
backend = ["backend"]
frontend = ["frontend"]

4. Generate for specific teams:

# Backend team gets root + backend content
ai-rulez generate --profile backend

# Frontend team gets root + frontend content
ai-rulez generate --profile frontend

# CI/QA gets everything
ai-rulez generate --profile full

Common Tasks

Update Rules

Edit any file in .ai-rulez/rules/ and regenerate:

# Edit a rule
vim .ai-rulez/rules/code-quality.md

# Regenerate outputs
ai-rulez generate

Add a New Domain

mkdir -p .ai-rulez/domains/newdomain/rules
mkdir -p .ai-rulez/domains/newdomain/context

# Add rules and context files...

# Update config.toml to reference the domain

Change Tool Configuration

Edit presets in config.toml:

presets = ["claude", "cursor", "devin", "copilot"]

Create Custom Output

For tools not in the built-in list:

[[presets]]
name = "my-tool"
type = "markdown"
path = "docs/MY_TOOL.md"

Troubleshooting

Generated files aren't updating

Make sure you ran ai-rulez generate:

ai-rulez generate

Content not appearing in output

Check that your file is in the correct location:

  • Root content: .ai-rulez/rules/, .ai-rulez/context/
  • Domain content: .ai-rulez/domains/{name}/rules/, etc.

Validation fails

Check your configuration:

ai-rulez validate

This will show errors in your setup.

Next Steps

Continue along the lifecycle: