Rules

Rules are persistent instructions that define how AI should behave when working with your codebase: coding standards, architectural decisions, naming conventions, and style preferences. They are advisory: the AI should follow them, but they are not enforced the way hooks are. For guaranteed enforcement, use hooks. For structured methodology, use skills. Rules fill the space in between: project-specific preferences and conventions that shape day-to-day behavior.

What Are Rules?

Rules are persistent instructions embedded in your project. Unlike chat messages that disappear, rules are always present. They tell the AI what conventions to follow: TypeScript strict mode, naming conventions, file organization, commit format. They work best for preferences that do not require structured multi-step procedures (use skills for that) or guaranteed enforcement (use hooks for that).

Rules can enforce:

• Coding standards: TypeScript patterns, naming conventions, file structure
• Architectural decisions: "Always use the repository pattern", "Never call APIs directly from components"
• Workflow requirements: "All PRs require tests", "Use conventional commits"
• Security practices: "Never commit secrets", "Sanitize all user input"

Rule Format

Rules are .mdc files (markdown with config) stored in .cursor/rules/. Each file has YAML frontmatter that controls when the rule is active, followed by the guidance itself:

---
description: Performance guidelines for hover card animations
globs: "**/*.tsx"
alwaysApply: false
---

# Hover Animation Performance Guidelines

When implementing hover animations on cards or interactive elements,
follow these patterns to avoid jitter and performance issues.

## Requirements

- Use CSS transforms instead of layout properties
- Never animate width, height, or margin
- Always use will-change on animated elements

## Examples

### Good
\`\`\`css
transform: scale(1.02);
transition: transform 0.2s ease;
\`\`\`

### Bad
\`\`\`css
margin-top: -4px;  /* triggers layout reflow */
\`\`\`

The frontmatter fields:

• description: short summary shown in rule listings
• globs: file patterns that trigger this rule (comma-separated). Leave empty if the rule is always-applied or manually activated.
• alwaysApply: when true, the rule is active in every session regardless of file context

Rule Types

Always-Applied Rules

Rules with alwaysApply: true are active in every AI session. Use these for project-wide standards:

---
description: Core development standards for the project
globs: ""
alwaysApply: true
---

# Core Development Rules

## TypeScript
- Use strict mode with \`noImplicitAny\`
- Never use \`any\` — use \`unknown\` with proper narrowing
- Define explicit types for function parameters and returns

## Code Style
- Use semicolons
- Prefer const over let
- No unused variables

Contextual Rules

Rules with globs patterns activate when the AI is working on matching files. They keep domain-specific guidance out of the global context until it is relevant:

---
description: Security rules for authentication code
globs: "src/auth/**,src/middleware/auth*"
alwaysApply: false
---

# Authentication Rules

## Requirements
- Never store passwords in plain text
- Always use bcrypt with salt rounds >= 12
- Tokens expire after 24 hours maximum
- Sanitize all user input before database queries

Agent-Specific Rules

Rules can target specific agent roles. These activate based on the task context rather than file patterns:

---
description: Guidelines for the implementation agent during coding
globs: ""
alwaysApply: false
---

# Implementation Agent

## Code Changes
- Make small, focused changes
- Don't modify unrelated files
- Run tests before submitting for review

## Git Commits
- Use conventional commit format
- Never commit directly to main

Platform Integration

Rules live in platform-specific locations:

• Cursor: .cursor/rules/*.mdc, loaded automatically by the IDE
• Claude Code: .claude/CLAUDE.md, rules are embedded in the project instructions file
• Copilot, Windsurf, and others: AGENTS.md, the cross-platform standard

FlyDocs generates the appropriate files for each platform during setup. When a skill includes a cursor-rule.mdc file, it is installed alongside the skill's SKILL.md and scripts.

Best Practices

1. Be specific: Vague rules like "write good code" don't help. Specify exactly what you mean.
2. Include examples: Show what correct and incorrect code looks like.
3. Explain why: When AI understands the rationale, it can apply the rule more intelligently.
4. Start small: Begin with your most important rules and add more as you identify patterns.
5. Review regularly: Rules should evolve with your project. Remove outdated ones.

Where Rules Fit

Rules are one of three layers that govern AI behavior:

Related Concepts

• Skills: methodological knowledge and integrations
• Hooks: deterministic enforcement the AI cannot skip
• Hooks & Guardrails: deep dive on enforcement architecture