01-rule-format

Rule Format Specification

MDC File Structure

Every rule file MUST have this structure:

---
description: Brief explanation of what this rule does
globs: ["**/*.tsx", "**/*.ts"]
alwaysApply: false
---

# Rule Title

## Section 1
Content...

## Section 2
Content...

---

Frontmatter Fields

Field	Required	Type	Description
description	Yes	string	1-2 sentence summary for AI to understand when to use
globs	Yes	array	File patterns that trigger this rule (empty = manual)
alwaysApply	No	boolean	If true, always included in context

Globs Examples

# TypeScript/React files
globs: ["**/*.tsx", "**/*.ts"]

# Python files
globs: ["**/*.py"]

# Specific directories
globs: ["src/components/**/*", "src/hooks/**/*"]

# Empty = manual activation only
globs: []

---

Content Guidelines

DO

✅ Use clear headings (##, ###)
✅ Include practical code examples
✅ Use tables for quick reference
✅ Keep sections focused and scannable
✅ Include ✅/❌ for do/don't patterns
✅ Reference specific file paths when helpful

DON'T

❌ Write walls of text
❌ Use vague language ("consider doing X")
❌ Include outdated patterns
❌ Repeat information from other rules
❌ Use corporate/AI-slop language
❌ Exceed 500 lines (split into multiple files)

---

Section Patterns

Pattern 1: Quick Reference Table

## Overview

| Aspect | Recommendation |
|--------|----------------|
| State | Use Zustand |
| Styling | Tailwind CSS |
| Forms | React Hook Form + Zod |

Pattern 2: Do/Don't Examples

## Component Patterns

### ✅ DO: Use early returns

```tsx
function Component({ data }) {
  if (!data) return null;
  return <div>{data.name}</div>;
}

❌ DON'T: Nested conditionals

function Component({ data }) {
  return (
    <div>
      {data && data.name && <span>{data.name}</span>}
    </div>
  );
}