Configuration Examples¶
V4 uses a file-based directory structure (.ai-rulez/) with TOML configuration. These examples show how to organize your configuration across multiple markdown files and a config.toml file.
1. Minimal Configuration (Single Team)¶
The simplest setup for a single team with basic rules.
.ai-rulez/config.toml:
.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/context/architecture.md:
# Architecture
This is a monolithic application with:
- PostgreSQL database
- REST API backend
- React frontend
Generated Output¶
ai-rulez generate
# Creates:
# - CLAUDE.md (context and agent roster)
# - .claude/rules/code-quality.md (the rule, under the default split mode)
# - .cursor/rules/ (one .mdc file per rule and context item)
2. Multi-Team Configuration with Domains¶
For projects with multiple teams, use domains to organize team-specific content.
.ai-rulez/config.toml:
version = "4.0"
name = "Platform"
presets = ["claude", "cursor", "gemini"]
default = "full"
gitignore = true
[profiles]
full = ["backend", "frontend", "qa"]
backend = ["backend", "qa"]
frontend = ["frontend", "qa"]
qa = ["qa"]
.ai-rulez/rules/security.md:
---
priority: critical
---
# Security
- All secrets must use environment variables
- Validate all user input
- Use HTTPS for all external API calls
.ai-rulez/domains/backend/rules/database.md:
---
priority: critical
---
# Database Standards
- Use prepared statements to prevent SQL injection
- Always add database migrations
- Index foreign keys for performance
.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
Generated Output¶
# Generate for backend team
ai-rulez generate --profile backend
# Includes: root rules + backend-specific rules
# Generate for frontend team
ai-rulez generate --profile frontend
# Includes: root rules + frontend-specific rules
# Generate for QA
ai-rulez generate --profile qa
# Includes: root rules + QA-specific rules
3. Using Skills for Specialized Roles¶
Create AI skill definitions for specialized tasks.
.ai-rulez/skills/code-reviewer/SKILL.md:
---
priority: high
description: "Code reviewer for quality assurance"
---
# Code Reviewer
You are an expert code reviewer with deep knowledge of:
- Code quality and maintainability
- Testing best practices
- Performance optimization
## Your Responsibilities
1. Review pull requests for correctness
2. Suggest improvements and refactoring
3. Verify test coverage
.ai-rulez/skills/architecture-expert/SKILL.md:
---
priority: high
description: "System architecture specialist"
---
# Architecture Expert
You are a system architect specializing in:
- Microservices design
- Scalability patterns
- System reliability
## Your Responsibilities
1. Review architectural decisions
2. Suggest performance improvements
3. Identify technical debt
Usage in Generated Files¶
Each skill is written as its own file, for example .claude/skills/code-reviewer/SKILL.md and
.claude/skills/architecture-expert/SKILL.md. The assistant reads the skill's description and loads
the body when the task matches; nothing is added to CLAUDE.md for it.
4. Complex Project with Multiple Presets¶
For projects that need different output formats for different tools.
.ai-rulez/config.toml:
version = "4.0"
name = "ML Research Platform"
description = "Machine learning platform with team separation"
presets = [
"claude",
"cursor",
"gemini",
"windsurf",
{ name = "internal-guide", type = "markdown", path = "docs/AI_DEVELOPMENT_GUIDE.md" },
]
default = "full"
gitignore = true
[profiles]
full = ["research", "infrastructure"]
research = ["research"]
infrastructure = ["infrastructure"]
.ai-rulez/domains/research/rules/ml-standards.md:
---
priority: critical
targets: ["CLAUDE.md", "GEMINI.md"]
---
# ML Development Standards
- Use type hints for all functions
- Document mathematical assumptions
- Include reproducibility seeds
.ai-rulez/domains/infrastructure/rules/deployment.md:
---
priority: high
targets: ["CLAUDE.md", ".cursor/rules/"]
---
# Deployment Standards
- All changes require review
- Run tests before deployment
- Keep infrastructure as code
5. Project with Frontmatter and Custom Fields¶
Markdown files can include YAML frontmatter with custom fields.
.ai-rulez/rules/testing.md:
---
priority: critical
author: qa-team
tags: [testing, quality, ci-cd]
review_date: 2025-01-15
targets:
- "CLAUDE.md"
- ".cursor/rules/"
---
# Testing Standards
## Unit Tests
All code changes must include corresponding unit tests.
- Aim for 80%+ code coverage
- Use table-driven tests for Go
- Test both happy path and error cases
## Integration Tests
Test service interactions:
- Database operations
- API endpoints
- External service calls
6. Monorepo with Shared Rules¶
For larger projects, reuse configurations across subdirectories.
/.ai-rulez/config.toml (Root config):
version = "4.0"
name = "Platform"
presets = ["claude", "cursor"]
default = "full"
[profiles]
full = ["shared"]
/backend/.ai-rulez/config.toml (Backend-specific):
version = "4.0"
name = "Backend Service"
presets = ["claude", "cursor"]
default = "backend"
[profiles]
backend = ["api", "database"]
/backend/.ai-rulez/domains/api/rules/endpoints.md:
---
priority: high
---
# API Endpoint Guidelines
- Use consistent path structure
- Version APIs from the start
- Return consistent error responses
Generation¶
7. Environment-Specific Profiles¶
Use profiles for different deployment environments.
.ai-rulez/config.toml:
version = "4.0"
name = "Web Application"
presets = ["claude"]
[profiles]
development = ["dev-guidelines"]
staging = ["staging-checks", "security-checks"]
production = ["production-critical", "security-hardened", "compliance"]
.ai-rulez/domains/dev-guidelines/rules/debugging.md:
---
priority: medium
---
# Development Guidelines
- Enable verbose logging in dev
- Use debug endpoints for testing
- Performance is less critical than clarity
.ai-rulez/domains/production-critical/rules/reliability.md:
---
priority: critical
---
# Production Standards
- All deployments require approval
- Monitor error rates in production
- Implement circuit breakers for external services