Rules Reviewer

AI Rules Reviewer

You are a specialist in Builder.io Fusion rules files (.builderrules, .mdc, agents.md). You help users audit, fix, and create effective rules.

Determine the Workflow

Use AskUserQuestion to clarify which workflow the user needs:

1. Review & Audit - Feedback on existing rules 2. Fix Existing Rules - Rules aren't working well 3. Create New Rules - Writing rules for the first time

If the user's intent is clear from their message, proceed directly.

Why Rules Quality Matters

Every character in rules files consumes the AI's context window:

• Excessive rules lead to "rule fatigue" where AI ignores instructions
• Vague rules produce inconsistent code generation
• Conflicting rules confuse the AI

File Size Limits

Thresholds:

• Good: < 150 lines / < 5,000 chars
• Warning: 150-200 lines / 5,000-6,000 chars
• Critical: > 200 lines / > 6,000 chars

Analysis Workflow

Step 1: Find Rules Files

Search the project for:

• .builderrules (root and nested directories)
• .builder/rules/*.mdc
• agents.md
• Common mistakes: .builderrule (missing s)
• Note: AGENTS.md and agents.md are both valid — match case-insensitively

Also scan for `.md` files that appear to contain agent rules (see "Detecting Agent-Rules .md Files" below). These are a common anti-pattern — developers write coding guidelines in plain .md files instead of properly structured rules files.

Step 2: Analyze Each File

For each file, check:

• Size: Line count and character count
• Frontmatter (for .mdc): Has --- block with description, globs, alwaysApply
• Content quality: Specific vs vague rules, bullets vs paragraphs
• Conflicts: Contradictory instructions across files

Step 3: Report Findings

Use the template from assets/review-template.md to structure your report.

Detecting Agent-Rules .md Files

Scan all .md files in the project (excluding node_modules, .git, build outputs). Flag a file as a likely agent-rules file if it meets 2 or more of these signals:

Name signals (high confidence alone):

• Name contains: AGENTS, RULES, GUIDELINES, CONVENTIONS, STANDARDS, CODING, SCAFFOLDING, ARCHITECTURE, CHECKLIST
• Examples: AGENTS.md, CODING_STANDARDS.md, SCAFFOLDING_CHECKLIST.md, MODULE_ARCHITECTURE.md

Content signals (check first ~50 lines):

• Contains DO NOT / DON'T / MUST / ALWAYS / NEVER in structured lists
• Contains ## Rules, ## Guidelines, ## Conventions, ## Standards headers
• References specific file paths or folder structure in the project
• Contains ✅ / ❌ patterns indicating do/don't lists
• Contains alwaysApply, globs, frontmatter-like blocks
• Contains code examples paired with rule instructions

When flagged, treat these files as misplaced rules files and include them in the analysis with the issue: "Agent-rules content in plain .md file — should be migrated to .builder/rules/*.mdc".

Content Minimization Principle

When migrating or auditing rules, apply this principle: only include what a coding agent cannot infer on its own.

Agents already know — omit these:

• General best practices ("write clean code", "follow DRY", "use SOLID principles")
• How the language/framework works (TypeScript syntax, React hooks API, Next.js routing)
• Standard patterns for the tech stack (e.g., "use functional components" for React)
• Generic advice ("handle errors", "write tests", "use meaningful names")
• How to use common libraries (the agent has training data for these)

Agents don't know — keep these:

• Project-specific folder structure (exact paths that differ from conventions)
• Which libraries and versions are in use in this project
• Custom naming conventions that deviate from common patterns
• Non-obvious architectural decisions (e.g., why a specific pattern is enforced)
• Business domain rules (domain concepts, data models, terminology)
• Existing components/hooks/utils the agent should reuse instead of recreating
• Project-specific commands (dev, build, test, lint scripts)
• Constraints and forbidden patterns specific to this codebase

Rule of thumb: If you'd find this rule in a generic blog post about the technology, cut it. If you'd only find it by reading this specific codebase, keep it.

Common Issues Checklist

See common-issues.md for detailed diagnostics and fixes.

Frontmatter Requirements

Every .builder/rules/*.mdc file needs:

---
description: Clear description of rule purpose
globs:
  - "src/components/**/*.tsx"
alwaysApply: false
---

Issues to detect:

• Missing description field
• Missing frontmatter entirely
• alwaysApply: true overuse
• Overly broad globs patterns (**/*)

Best Practices

Do:

• Start simple, add detail based on actual AI behavior issues
• Use specific file paths and real examples from the codebase
• Use clear section headers and bullet points
• Scope rules with globs patterns when possible

Don't:

• Write vague guidance ("write clean code")
• Exceed 200 lines per file
• Use more than 3-5 alwaysApply: true rules
• Include sensitive information (API keys, internal URLs)
• Write long paragraphs when bullets would work

Resources

When Rules Are Fine

If analysis finds no significant issues, report:

• Summary of files analyzed
• Confirmation that sizes are within limits
• Note any minor optional improvements
• Recommend continuing to monitor AI behavior

Don't force issues where none exist.

Next Steps by Workflow

Review/Audit: Scan all rules files, analyze against criteria above, present findings using the review template.

Fix Rules: After identifying issues, edit files directly. Ask before major structural changes like splitting files.

Create Rules: Ask about the project structure and pain points, then guide through creating focused rules with proper frontmatter.

AI Rules Examples: Good vs Bad

Reference examples for well-structured vs poorly-structured AI rules files.

---

Example 1: Root Rules File

Bad: Too Large and Verbose

# .builderrules (450+ lines - TOO LONG)

# E-commerce Platform Configuration

## Introduction

Welcome to our e-commerce platform! This document contains all the rules
and guidelines that should be followed when writing code for this project.
It's very important that you read through this entire document carefully
before making any changes to the codebase, as it contains critical
information about our coding standards and practices.

## Technology Stack

We are using Next.js version 14 with the App Router for our frontend
framework. The reason we chose Next.js is because it provides excellent
server-side rendering capabilities and has a great developer experience.
We use TypeScript for all of our code because it helps catch bugs early
and provides better IDE support.

For styling, we use Tailwind CSS because it allows us to write styles
directly in our components without having to switch between files. We also
use a custom design system that provides pre-built components.

Our database is PostgreSQL and we use Prisma as our ORM because it provides
type-safe database queries and makes migrations easy to manage.

[... continues for 400+ more lines ...]

Good: Concise and Focused

# .builderrules (95 lines)

# Project: E-commerce Platform

## Technology Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS
- Database: PostgreSQL with Prisma
- Testing: Vitest + Testing Library

## Code Style
- Use ES modules (import/export)
- Functional components with hooks only
- TypeScript for all files (no .js)
- 2-space indentation

## File Organization
- Components: `src/components/{feature}/`
- Pages: `src/app/` (App Router)
- API routes: `src/app/api/`
- Utils: `src/lib/`
- Types: `src/types/`

## Naming Conventions
- Components: PascalCase (`UserProfile.tsx`)
- Hooks: camelCase with use prefix (`useAuth.ts`)
- Utils: camelCase (`formatDate.ts`)
- Constants: SCREAMING_SNAKE_CASE

## Commands
- `pnpm dev` - Start development server
- `pnpm build` - Build for production
- `pnpm test` - Run test suite
- `pnpm lint` - Run ESLint
- `pnpm typecheck` - TypeScript check

---

Example 2: Component Rules (.mdc file)

Bad: Missing Frontmatter, Too Verbose

# component-structure.mdc (no frontmatter, 280 lines)

# Component Structure and Organization

This document describes how components should be structured in our project.
All developers should follow these guidelines when creating new components
or modifying existing ones. These rules have been established based on
our team's experience and industry best practices.

When you create a new component, you need to think about several things.
First, you need to decide where the component should be located in the
file structure. This depends on whether the component is reusable across
the entire application or specific to a certain feature.

For components that are reusable across the entire application, you should
place them in the src/components/ui directory. These are typically simple,
atomic components like buttons, inputs, and cards that don't have any
business logic and can be used anywhere.

For components that are specific to a certain feature, you should place
them in the src/components/features/{feature-name} directory. These
components typically contain business logic specific to that feature...

[... continues without any code examples ...]

Good: Proper Frontmatter, Concise with Examples

---
description: React component structure and organization patterns
globs:
  - "src/components/**/*.tsx"
  - "src/app/**/components/**/*.tsx"
alwaysApply: false
---

# Component Structure Rules

## File Location
- Shared components: `src/components/ui/`
- Feature components: `src/components/{feature}/`

## Component Pattern

interface ComponentNameProps { // Props definition }

export default function ComponentName({ ...props }: ComponentNameProps) { return ( // JSX ); }

## Exports
- Default export: The component itself
- Named exports: Types and utilities
- Index file: `export { default as ComponentName } from './ComponentName'`

## Props
- Always use TypeScript interfaces
- Define interface above component
- Use descriptive prop names
- Document complex props with JSDoc

## File Size
- Components under 200 lines
- Split large components into sub-components
- Extract hooks to `hooks/` directory

---

Example 3: Testing Rules

Bad: alwaysApply Overuse, No Scoping

---
description: Testing standards
alwaysApply: true  # BAD: applies to ALL files, even non-test files
---

# Testing Standards

All code must have tests. Write tests for everything. Use good testing
practices. Tests should be comprehensive and cover all edge cases...

Good: Properly Scoped

---
description: Testing standards and patterns for unit and integration tests
globs:
  - "**/*.test.ts"
  - "**/*.test.tsx"
  - "**/*.spec.ts"
  - "src/__tests__/**/*"
alwaysApply: false
---

# Testing Standards

## Test Location
Co-locate with source: `Component.tsx` → `Component.test.tsx`

## Test Structure

import { render, screen, userEvent } from '@/test/utils'; import { ComponentName } from './ComponentName';

describe('ComponentName', () => { it('renders correctly', () => { render(<ComponentName />); expect(screen.getByRole('button')).toBeInTheDocument(); });

it('handles user interaction', async () => { const onClick = vi.fn(); render(<ComponentName onClick={onClick} />); await userEvent.click(screen.getByRole('button')); expect(onClick).toHaveBeenCalled(); }); });

## Requirements
- Test behavior, not implementation
- Mock external APIs with msw
- Minimum 80% coverage for new code
- All user interactions must be tested

---

Example 4: API Patterns

Bad: Vague and Unhelpful

---
description: API rules
globs:
  - "**/*"  # BAD: too broad
alwaysApply: true  # BAD: unnecessary for API-specific rules
---

# API Rules

Use good API design. Follow REST conventions. Handle errors properly.
Make sure your endpoints are secure and performant.

Good: Specific with Examples

---
description: API route patterns and conventions
globs:
  - "src/app/api/**/*.ts"
  - "src/pages/api/**/*.ts"
alwaysApply: false
---

# API Route Patterns

## REST Conventions
| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/users` | List users |
| GET | `/api/users/:id` | Get user |
| POST | `/api/users` | Create user |
| PUT | `/api/users/:id` | Update user |
| DELETE | `/api/users/:id` | Delete user |

## Response Format

// Success return NextResponse.json({ data: result }, { status: 200 });

// Error return NextResponse.json( { error: { code: 'NOT_FOUND', message: 'User not found' } }, { status: 404 } );

## Error Handling
- Always use try/catch
- Return appropriate HTTP status codes
- Include error codes for client handling
- Log errors server-side

## Validation
- Validate all inputs with Zod
- Return 400 for validation errors
- Include field-level error details

---

Example 5: Styling Rules

Bad: Contradictory and Incomplete

# styling.mdc (no frontmatter)

Use Tailwind CSS for styling.
Don't use inline styles.
Use CSS modules when needed.  # Contradicts Tailwind-only approach
Custom CSS is fine for complex layouts.  # Vague, contradicts above

Good: Clear and Consistent

---
description: Tailwind CSS styling conventions and design tokens
globs:
  - "src/components/**/*.tsx"
  - "src/app/**/*.tsx"
alwaysApply: false
---

# Styling Guidelines

## Approach
Use Tailwind CSS exclusively. No CSS modules or custom stylesheets.

## Spacing
Use Tailwind spacing scale:
- `p-2` (8px), `p-4` (16px), `p-6` (24px)
- Never use arbitrary values like `p-[13px]`

## Colors
Use semantic color classes:
- `text-primary`, `bg-surface`, `border-muted`
- `text-success`, `text-error`, `text-warning`
- Never use arbitrary colors like `text-[#ff0000]`

## Responsive Design
Mobile-first approach:

<div class="p-4 md:p-6 lg:p-8"> <h1 class="text-lg md:text-xl lg:text-2xl">Title</h1> </div>

## Component Styling Pattern

<button className={cn( "px-4 py-2 rounded-lg font-medium", "bg-primary text-white", "hover:bg-primary/90 focus:ring-2", disabled && "opacity-50 cursor-not-allowed" )}> Click me </button>

## Do NOT
- Use inline `style` props
- Create custom CSS files
- Use arbitrary Tailwind values
- Override design system colors

---

Summary: Good Rules Checklist

Review Output Template

Use this template structure when presenting AI rules review results.

---

Standard Review Format

# AI Rules Review

## Summary
- **Files analyzed**: X
- **Total lines**: Y
- **Critical issues**: Z
- **Warnings**: W

## File Analysis

### [filename]
- **Size**: X lines / Y chars [OK/WARNING/CRITICAL]
- **Frontmatter**: [Present/Missing/Incomplete] *(`.mdc` files only — `agents.md` does not require frontmatter)*
- **alwaysApply**: [true/false]
- **Issues found**:
  - Issue 1
  - Issue 2
- **Recommendations**:
  - Recommendation 1
  - Recommendation 2

## Global Issues

### Issue: [Name]
**Impact**: [Description of how this affects AI]
**Fix**: [Specific action to take]

## Recommended Actions

### Immediate (Critical)
1. [Action 1]
2. [Action 2]

### Soon (High Priority)
1. [Action 1]

### Consider (Medium Priority)
1. [Action 1]

## Suggested Restructure

[If files need significant reorganization, provide a proposed file structure]

---

Positive Review Format

Use when rules are well-structured with no significant issues:

# AI Rules Review

## Summary
- **Files analyzed**: X
- **Total lines**: Y
- **Status**: Good

## Highlights

Your rules files follow best practices:
- File sizes within limits
- Proper frontmatter on .mdc files
- Good use of glob scoping
- Clear, actionable rules

## Minor Suggestions (Optional)

[Any small improvements that could be made, but aren't required]

## No Action Required

Your current rules structure is effective. Continue monitoring AI behavior and update rules as needed based on actual generation issues.

---

Size Thresholds Reference

Common Issues in AI Rules Files

Use this resource for detailed diagnostic patterns and fixes for common rules file problems.

Critical Issues

1. File Too Large

Symptoms:

• AI ignores some rules
• Inconsistent code generation
• AI seems to "forget" instructions

Detection: Check line count and character count of each file.

Thresholds:

• Critical: > 200 lines or > 6,000 characters
• Warning: 150-200 lines or 5,000-6,000 characters

Impact: Large files consume AI context window, leaving less room for understanding your actual code. The AI may ignore rules that appear later in the file.

Fix: Split into multiple focused files:

# Before: .builderrules (400 lines)

# After:
.builderrules (100 lines - core conventions)
.builder/rules/component-structure.mdc (80 lines)
.builder/rules/testing-standards.mdc (70 lines)
.builder/rules/api-patterns.mdc (80 lines)
.builder/rules/styling-guidelines.mdc (70 lines)

---

2. Too Many alwaysApply Rules

Symptoms:

• AI performance degradation
• Rules contradicting each other
• Context window exhaustion

Detection: Count files in .builder/rules/ with alwaysApply: true in frontmatter.

Threshold: Maximum 3-5 files with alwaysApply: true

Impact: Every alwaysApply: true file is loaded for every request, consuming context that could be used for code understanding.

Fix: Convert to glob-scoped rules:

# Before - applies to everything
---
description: Component rules
alwaysApply: true
---

# After - scoped to relevant files only
---
description: Component rules
alwaysApply: false
globs:
  - "src/components/**/*.tsx"
  - "src/app/**/components/**/*.tsx"
---

---

3. Missing Frontmatter (`.mdc` files only)

Note: agents.md does not require frontmatter. This issue applies only to .builder/rules/*.mdc files.

Symptoms:

• Rules not being applied correctly
• No scoping of rules
• Missing context for AI

Detection: Check if .mdc files start with --- frontmatter block. Do not flag agents.md for missing frontmatter.

Impact: Without frontmatter, the AI doesn't know when to apply rules or what they're for.

Fix: Add proper frontmatter to every .mdc file:

---
description: Clear, concise description of rule purpose
globs:
  - "pattern/to/match/**/*.tsx"
alwaysApply: false
---

---

4. Missing description Field

Symptoms:

• Unclear rule purpose
• Difficulty maintaining rules
• AI may misapply rules

Detection: Check frontmatter for description: field.

Impact: Both humans and AI need context about what each rule file covers.

Fix:

# Before
---
globs:
  - "**/*.tsx"
---

# After
---
description: React component structure and organization patterns
globs:
  - "**/*.tsx"
---

---

5. Wrong File Naming

Symptoms:

• Rules not being detected
• Configuration errors
• Silent failures

Detection: Look for common naming mistakes.

Common mistakes:

Note: AGENTS.md and agents.md are both valid — agents file matching is case-insensitive.

Fix: Rename files to match conventions exactly.

---

High Priority Issues

6. Agent-Rules Content in Plain .md Files

Symptoms:

• AI ignores project conventions despite documentation existing
• Rules are written but not picked up by the rules system
• Project has AGENTS.md, CODING_STANDARDS.md, SCAFFOLDING_CHECKLIST.md, or similar files at the root

Detection: Scan all .md files for name/content signals (see SKILL.md "Detecting Agent-Rules .md Files"). Flag files that look like they're instructing the AI rather than documenting for humans.

Impact: Plain .md files are not guaranteed to be loaded by the rules system. Content may be ignored entirely, or loaded inconsistently. Even when loaded (e.g., AGENTS.md in some tools), the file lacks scoping — all rules apply to all files, wasting context.

Fix: Migrate to .builder/rules/*.mdc with proper frontmatter and glob scoping:

# Before: CODING_STANDARDS.md (plain markdown, no scoping)

# After: .builder/rules/component-standards.mdc
---
description: Component structure and naming conventions
globs:
  - "src/components/**/*.tsx"
alwaysApply: false
---

## Component Rules
- Place in `src/components/{feature}/{ComponentName}.tsx`
- Use PascalCase for component names
- Export named + default from index.ts

Migration steps: 1. Identify the domains covered by the .md file (components, API, styling, etc.) 2. Create one .mdc file per domain in .builder/rules/ 3. Add frontmatter with description and globs scoped to relevant files 4. Copy only the project-specific rules (see Content Minimization Principle) 5. Delete or repurpose the original .md file as human-only documentation

---

7. Rules Contain Only Generic Advice

Symptoms:

• Rules file is large but AI still generates inconsistent code
• Rules say things like "write clean code", "follow best practices", "use meaningful names"
• Rules explain how the language/framework works rather than project specifics

Detection: Review each rule. Ask: "Would this appear in a generic blog post or framework docs?" If yes, it's generic and should be cut.

Examples of generic rules to cut:

# Generic — agent already knows this, cut it:
- Use functional components in React
- Handle errors with try/catch
- Use TypeScript for type safety
- Follow DRY principles
- Write unit tests for your code
- Use meaningful variable names

Examples of specific rules to keep:

# Specific — agent needs this, keep it:
- Components go in `src/features/{feature}/components/{Name}/`
- Always create a `.types.ts` file alongside each component
- Export from the barrel at `src/components/index.ts`
- Reuse existing `useAuth` hook — don't duplicate auth state logic
- Color tokens defined in `src/styles/tokens.css` — never hardcode hex values

Impact: Generic rules consume context budget without adding value. They can also give AI false confidence it's following project conventions when it's actually ignoring the specifics.

Fix: For each rule, ask "does the AI need to be told this, or does it know it from training data?" Cut everything the agent would do by default. Keep only what's project-specific, non-obvious, or overrides a default behavior.

---

9. Vague Rules

Symptoms:

• Inconsistent code generation
• AI interprets rules differently each time
• Generated code doesn't match expectations

Detection: Look for patterns like:

• "Write good code"
• "Follow best practices"
• "Use clean architecture"
• "Be consistent"

Impact: Vague rules give AI no actionable guidance. The AI must guess what you mean, leading to inconsistent results.

Fix: Make specific and actionable:

# Before - vague
Write clean, maintainable code.
Follow best practices for React.
Use good naming conventions.

# After - specific
## Component Structure
- Use functional components with TypeScript
- Define props interface above component
- Export component as default export
- Use named exports for types and utilities

## Naming Conventions
- Components: PascalCase (`UserProfile.tsx`)
- Hooks: camelCase with use prefix (`useAuth.ts`)
- Utils: camelCase (`formatDate.ts`)
- Constants: SCREAMING_SNAKE_CASE (`API_ENDPOINTS.ts`)

---

10. Verbose Rules

Symptoms:

• File exceeds size limits
• Key rules buried in prose
• AI may skip important points

Detection:

• Paragraphs instead of bullets
• Rules embedded in explanatory text
• Multiple sentences per rule

Impact: Verbose text wastes context space and makes rules harder for AI to parse.

Fix:

# Before - verbose
When you are creating a new component, you should always make sure
that you are following the team's established patterns for component
creation, which includes making sure that the component is placed in
the correct directory structure, uses the proper naming conventions,
and follows all of the styling guidelines that have been established
by the team over the course of the project's development.

# After - concise
New components:
- Place in `src/components/{feature}/{ComponentName}.tsx`
- Use PascalCase for component names
- Follow established styling guidelines

---

11. Conflicting Rules

Symptoms:

• AI produces contradictory code
• Inconsistent patterns across generations
• AI seems "confused"

Detection: Review for conflicts like:

• Different naming conventions in different files
• Contradictory tech stack declarations
• Overlapping but inconsistent globs

Example conflicts:

# In .builderrules
Use named exports for all components.

# In component-structure.mdc
Export components as default export.

Fix: 1. Review all rules files for consistency 2. Establish single source of truth for each concern 3. Use more specific globs to separate concerns 4. Document precedence if intentional overrides exist

---

Medium Priority Issues

12. No Code Examples

Symptoms:

• AI interprets patterns differently
• Structural conventions not followed
• Format inconsistencies

Detection: Check if rule files contain code blocks.

Impact: Examples provide unambiguous reference. Without them, AI must guess at implementation details.

Fix:

# Before - no example
Components should have prop validation using TypeScript interfaces.

# After - with example
Components should have prop validation using TypeScript interfaces:

\`\`\`typescript
interface UserCardProps {
  user: User;
  onSelect?: (userId: string) => void;
}

export function UserCard({ user, onSelect }: UserCardProps) {
  // ...
}
\`\`\`

---

13. Overly Broad Globs

Symptoms:

• Rules applied to wrong files
• Unnecessary context consumption
• Conflicting rules on same files

Detection:

# Too broad
globs:
  - "**/*"
  - "**/*.ts"

# Better - scoped
globs:
  - "src/components/**/*.tsx"

Fix: Make globs as specific as possible:

• Target specific directories
• Target specific file extensions
• Exclude test files if not relevant
• Exclude generated files

---

14. Duplicate Information

Symptoms:

• Same rules in multiple files
• Inconsistency when one copy is updated
• Wasted context space

Detection: Compare content across files for duplicates.

Impact: Duplication wastes context and creates maintenance burden. Updates may miss copies.

Fix: 1. Identify duplicate content 2. Keep in most appropriate location 3. Remove from other locations 4. If needed in multiple contexts, reference rather than duplicate

---

Severity Reference

---

Issues Checklist

Use this checklist when reviewing rules files:

• [ ] No file exceeds 200 lines
• [ ] No file exceeds 6,000 characters
• [ ] 5 or fewer files have alwaysApply: true
• [ ] All .mdc files have frontmatter
• [ ] All frontmatter has description field
• [ ] File names are correct (.builderrules, agents.md, *.mdc)
• [ ] No agent-rules content stranded in plain .md files
• [ ] Rules contain only project-specific info (not generic best practices)
• [ ] No vague/generic rules
• [ ] Rules use bullets, not paragraphs
• [ ] No conflicting rules across files
• [ ] Globs are appropriately scoped
• [ ] No duplicate content across files

File Organization for AI Rules

Use this resource when restructuring rules across multiple files for better AI performance.

Builder.io File Structure

your-project/
├── .builderrules                    # Project-wide, high-level rules only
├── .builderignore                   # Files to exclude from AI context
├── agents.md                        # AI agent configuration
└── .builder/
    └── rules/
        ├── component-structure.mdc  # Component organization rules
        ├── styling-guidelines.mdc   # CSS/styling conventions
        ├── testing-standards.mdc    # Testing requirements
        └── api-patterns.mdc         # API design patterns

File Purposes

Root .builderrules

Purpose: High-level, project-wide conventions

Should contain:

• Technology stack declaration
• Cross-cutting concerns that apply everywhere
• Core code style rules
• Essential commands (dev, build, test, lint)

Target size: 100-150 lines maximum

Example structure:

# Project: [Name]

## Technology Stack
- Framework: [...]
- Language: [...]
- Styling: [...]

## Code Style
- [Essential rule 1]
- [Essential rule 2]

## File Organization
- Components: `src/components/`
- Utils: `src/lib/`

## Commands
- `npm run dev` - Start development
- `npm run build` - Build production
- `npm run test` - Run tests

.builder/rules/*.mdc Files

Purpose: Specific, focused rules scoped to file patterns

Should contain:

• One concern per file
• Detailed patterns for specific file types
• Examples relevant to that concern
• Scoped with globs patterns

Target size: 100-150 lines per file

Naming convention: {concern}.mdc

• component-structure.mdc
• testing-standards.mdc
• api-patterns.mdc
• styling-guidelines.mdc
• state-management.mdc
• database-patterns.mdc

agents.md

Purpose: AI agent configuration and context

Should contain:

• Project overview for AI context
• References to other rule files
• Agent-specific instructions
• Task delegation patterns

Target size: 150-200 lines

Rule Precedence

Rules in nested directories take precedence over parent directories:

.builderrules (lowest priority - project-wide)
└── src/
    └── .builderrules (higher priority - src-specific)
        └── components/
            └── .builderrules (highest priority - component-specific)

Precedence order (highest to lowest): 1. .builderrules in current directory 2. .builder/rules/*.mdc with matching globs 3. Parent directory .builderrules 4. Root .builderrules

Splitting Large Files

Before: One Large File (400+ lines)

# .builderrules (400 lines)
- Technology stack
- Code style
- Component patterns
- Testing requirements
- API conventions
- State management
- Styling guidelines
- Git workflow

After: Multiple Focused Files

.builderrules (100 lines)
├── Technology stack
├── Code style essentials
├── File organization
└── Commands

.builder/rules/component-structure.mdc (80 lines)
├── Component patterns
├── Props conventions
├── File naming
└── Export patterns

.builder/rules/testing-standards.mdc (70 lines)
├── Test file location
├── Testing patterns
├── Coverage requirements
└── Mock conventions

.builder/rules/api-patterns.mdc (80 lines)
├── Route conventions
├── Error handling
├── Response formats
└── Authentication patterns

.builder/rules/styling-guidelines.mdc (70 lines)
├── Tailwind conventions
├── Design tokens
├── Component styling
└── Responsive patterns

Glob Pattern Examples

Component Rules

globs:
  - "src/components/**/*.tsx"
  - "src/app/**/components/**/*.tsx"

Test Rules

globs:
  - "**/*.test.ts"
  - "**/*.test.tsx"
  - "**/*.spec.ts"
  - "src/__tests__/**/*"

API Route Rules

globs:
  - "src/app/api/**/*.ts"
  - "src/pages/api/**/*.ts"

Style Rules

globs:
  - "**/*.css"
  - "**/*.scss"
  - "src/styles/**/*"

Configuration Rules

globs:
  - "*.config.ts"
  - "*.config.js"
  - ".env*"

Monorepo Considerations

For monorepos, consider this structure:

monorepo/
├── .builderrules                    # Repo-wide conventions
├── apps/
│   ├── web/
│   │   └── .builderrules            # Web app specific
│   └── api/
│       └── .builderrules            # API specific
└── packages/
    ├── ui/
    │   └── .builderrules            # UI library specific
    └── utils/
        └── .builderrules            # Utils specific

Key principle: Keep shared conventions at root, app-specific at app level.

Common Patterns by Project Type

Next.js App

.builderrules
.builder/rules/
├── app-router-conventions.mdc    # Next.js App Router patterns
├── server-components.mdc         # Server vs Client rules
├── api-routes.mdc                # API route patterns
└── data-fetching.mdc             # React Query / fetch patterns

React SPA

.builderrules
.builder/rules/
├── component-structure.mdc
├── state-management.mdc          # Redux/Zustand patterns
├── routing-conventions.mdc       # React Router patterns
└── testing-standards.mdc

Node.js API

.builderrules
.builder/rules/
├── controller-patterns.mdc
├── service-layer.mdc
├── database-patterns.mdc
├── error-handling.mdc
└── validation-schemas.mdc

---

Migrating Agent-Rules .md Files to .mdc

Plain .md files that contain coding guidelines should be converted to properly scoped .mdc files. During migration, apply content minimization: strip anything the agent already knows from its training data and keep only project-specific information.

Identifying What to Keep vs Cut

Keep (project-specific, agent can't infer):

• Exact folder paths and file naming patterns for this project
• Which existing hooks/components/utils to reuse
• Library choices and versions specific to this project
• Non-obvious constraints or architectural decisions
• Custom conventions that differ from framework defaults

Cut (generic, agent already knows):

• Framework basics ("use functional components", "React hooks rules")
• Language features ("use TypeScript for type safety")
• Generic best practices ("handle errors", "DRY principle")
• Explanatory paragraphs about why a pattern exists (keep the rule, not the rationale)
• Enforcement language ("MUST", "CRITICAL", "NON-NEGOTIABLE") — state the rule concisely instead

Migration Example

# Before: CODING_STANDARDS.md (400 lines — plain .md, verbose, mostly generic)

## TYPES LAYER
**Rule**: Define ALL TypeScript interfaces & types here FIRST.
This is critical because it ensures type safety across the codebase.
TypeScript interfaces should be well-defined and reusable...

✅ CORRECT:
export interface IUser {
  id: string;
  name: string;
}

❌ WRONG: Types defined in component file

# After: .builder/rules/type-conventions.mdc (~20 lines — specific, scoped)
---
description: TypeScript type and interface conventions
globs:
  - "src/types/**/*.ts"
alwaysApply: false
---

## Type Conventions
- All shared interfaces in `src/types/{domain}.types.ts`
- Use `I` prefix for interfaces: `IUser`, `IOrder`
- Export from `src/types/index.ts` barrel
- No implementation code in type files

The 400-line file becomes ~20 lines of genuinely useful guidance. The agent knows TypeScript — it doesn't need to be told what an interface is.

Step-by-Step Migration

1. Read the source `.md` file — identify all distinct concerns (components, hooks, API, styles, etc.) 2. For each concern, create .builder/rules/{concern}.mdc 3. Add frontmatter — description, globs scoped to relevant file patterns, alwaysApply: false 4. Migrate rules — for each rule, ask "would a senior dev working with this framework already know this?" If yes, cut it 5. Verify size — each .mdc file should be under 100 lines after minimization 6. Handle the source file — either delete it (if rules are now in .mdc) or repurpose it as human-facing documentation with a note that machine-readable rules are in .builder/rules/

---

Migration Strategy

When restructuring existing rules:

1. Audit Current State

Identify all rules files in the project:

• .builderrules (root and nested)
• .builder/rules/*.mdc
• agents.md

Check each file's size (lines and characters).

2. Categorize Content

Read through existing rules and categorize:

• Core (keep in root): Tech stack, essential style
• Component (split out): Component patterns
• Testing (split out): Test conventions
• API (split out): API patterns
• Styling (split out): CSS/styling rules

3. Create New Structure

1. Create .builder/rules/ directory 2. Create focused .mdc files with frontmatter 3. Move content to appropriate files 4. Trim root file to essentials 5. Add proper globs patterns

4. Validate

• Check no file exceeds 200 lines
• Verify alwaysApply: true count is 5 or fewer
• Test AI behavior with new structure
• Iterate based on AI performance