Monorepos and Large Projects¶

For large projects with multiple teams, organize your .ai-rulez/ configuration using domains and profiles to provide relevant context while avoiding overwhelming AI assistants with irrelevant information.

This guide outlines best practices for managing AI context at scale.

The Core Strategy: Domain-Based Organization¶

The most effective strategy for large projects is to organize related rules, context, and skills into domains. Each domain represents a team, service, or feature area.

A typical layout might look like this:

my-project/
└── .ai-rulez/
    ├── config.toml              # ⬅️ Main config: presets, profiles, domains
    ├── rules/                   # ⬅️ Shared rules (all teams)
    ├── context/                 # ⬅️ Shared context (all teams)
    ├── skills/                  # ⬅️ Shared skills (all teams)
    └── domains/
        ├── backend/             # ⬅️ Backend team content
        │   ├── rules/
        │   ├── context/
        │   └── skills/
        ├── frontend/            # ⬅️ Frontend team content
        │   ├── rules/
        │   ├── context/
        │   └── skills/
        └── qa/                  # ⬅️ QA team content
            └── rules/

When you run ai-rulez generate --profile backend, it includes root content plus backend-specific content.

Best Practice: Root Configuration¶

Your root .ai-rulez/ should contain high-level, cross-cutting concerns that apply to all teams.

.ai-rulez/config.toml:

version = "4.0"
name = "My Full-Stack Project"
description = "Microservices project with React frontend and Go backend"

presets = ["claude", "cursor", "gemini"]
default = "full"
gitignore = true

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

.ai-rulez/context/architecture.md:

# System Architecture

This is a microservices project with:

- Go backend services
- React web frontend
- PostgreSQL databases
- Kubernetes orchestration

.ai-rulez/rules/security.md:

---
priority: critical
---

# Security Standards

- All secrets use environment variables
- Validate all user input
- Use HTTPS for external APIs

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

---
priority: high
---

# Git Workflow

- Feature branches from main
- Squash commits before merge
- All PRs require code review

Best Practice: Domain-Specific Content¶

Domain directories contain specific, detailed context for that team or service.

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

---
priority: critical
---

# Database Standards

- Use prepared statements to prevent SQL injection
- Always add migrations for schema changes
- Index foreign keys

.ai-rulez/domains/backend/rules/api-design.md:

---
priority: high
---

# API Design

- Follow RESTful principles
- Use consistent error responses
- Version APIs from the start

.ai-rulez/domains/backend/context/architecture.md:

# Backend Architecture

## Services

- API Gateway (Go, port 8000)
- User Service (Go, port 8001)
- Product Service (Go, port 8002)
- Order Service (Go, port 8003)

## Database

- PostgreSQL 14+
- Replication enabled
- Automated daily backups

.ai-rulez/domains/backend/skills/database-expert/SKILL.md:

---
priority: high
description: "Database design and optimization specialist"
---

# Database Expert

You are an expert in PostgreSQL with knowledge of:

- Schema design and normalization
- Query optimization
- Performance tuning

.ai-rulez/domains/frontend/rules/components.md:

---
priority: high
---

# Component Guidelines

- One component per file
- Use TypeScript for type safety
- Write unit tests for all components
- Use composition over inheritance

.ai-rulez/domains/frontend/context/design-system.md:

# Design System

## Color Palette

- Primary: #3B82F6
- Secondary: #8B5CF6
- Neutral: #6B7280

## Typography

- Headings: Inter Bold
- Body: Inter Regular

Best Practice: Profile Selection¶

Design profiles to match your team structure and workflows.

[profiles]
# Full platform: all content
full = ["backend", "frontend", "qa", "devops"]

# Team-specific
backend-team = ["backend", "qa"]
frontend-team = ["frontend", "qa"]
qa-team = ["qa"]
devops-team = ["devops"]

# Full-stack developers
full-stack = ["backend", "frontend", "qa"]

# CI/QA environment
ci-cd = ["backend", "frontend", "qa", "devops"]

Best Practice: For Monorepos¶

If using multiple .ai-rulez/ directories in a monorepo, use the --recursive flag:

# Process all .ai-rulez/ directories recursively
ai-rulez generate --recursive

Root configuration (/.ai-rulez/config.toml):

version = "4.0"
name = "Monorepo Platform"

presets = ["claude", "cursor"]
default = "full"

[profiles]
full = ["shared"]

Service-specific (/backend/.ai-rulez/config.toml):

version = "4.0"
name = "Backend Service"

presets = ["claude"]
default = "backend"

[profiles]
backend = ["api", "database"]

By combining domain organization with thoughtful profile design, you can create scalable, maintainable configurations that grow with your project.

Scoped Rule Files¶

For [[scopes]] (see Configuration), root files such as CLAUDE.md stay in the scope directory, but native rule files are written to the root rules folder, because tools read rules folders at the workspace root only. Each scope's files get the scope path as a qualifier and as a glob prefix:

Globs in a scope's rules are relative to the scope root: a rule with paths: ["**/*.go"] gets packages/api/**/*.go, and a rule without globs applies to packages/api/**. A rule with only negated globs also gets packages/api/**. A glob that climbs out of the scope with .. (also inside braces) skips that rule for the scope with a warning. auto and manual rules keep their mode. With [rules] mode = "inline" only path-scoped items move to the root folder; everything else stays in the scope's root file. Two files that map to the same path (names compare case-insensitively) do not fail: the source that sorts later is written as <id>-<6 hex> with a warning (see File names). Generation fails only when two scopes produce the same qualifier (for example packages/api and packages-api); rename one of the scope paths.

Limitations:

• Root files left in a scope (CLAUDE.md, AGENTS.md, GEMINI.md, ...) are read by tools that load nested files. Copilot (.github/copilot-instructions.md) and Junie (.junie/guidelines.md) read theirs at the repository root only, so rules or context that stay inline in a scope's copy are never loaded; generation warns and names them. Use path-scoped rules or [rules] mode = "split" for those presets.
• Domains the root run already renders are not repeated in a scope.
• Presets without split rule files (custom provider specs with a non-split outputs.rules) keep a scope's rules in the scope directory; generation warns.