---
trigger: glob
globs: .rulesync/rules/**/*.md
---
# Meta-Rules: Writing AI Agent Rules
**Keep rules under 300 lines. Be specific, actionable, concise.**
## Frontmatter
```yaml
---
version: 1.0.0
globs: .rulesync/rules/**/*.md
alwaysApply: false
last_updated: 2025-12-06
---
```
**Glob patterns:**
- Specific: `app/components/ui/**/*.tsx`
- Multiple: `**/*.css,**/*.tsx`
- Avoid overly broad: `**/*` (slows AI, use targeted paths)
## Structure
**Required sections (in order):**
1. Bold opening statement (purpose/scope)
2. Core standards with measurable values
3. ✓/✗ examples (both correct and wrong)
4. Quick reference (scannable)
**Optional sections:**
- Component-specific guidance
- Anti-patterns
- Verification steps
## Best Practices from Research
**AI agent recommendations:**
- Rules under 300 lines (AI context efficiency)
- Specific and actionable (no vague guidance)
- Concrete examples (both correct/wrong)
- Trust AI to generalize (don't over-explain)
### Be Concise
**❌ Wrong:** Verbose
```markdown
In order to ensure that your interactive elements are accessible to all users,
including those using touch devices, you should make sure that buttons and other
clickable elements have adequate size, specifically a minimum of 44 pixels...
```
**✅ Correct:** Concise
```markdown
All buttons must be minimum 44×44px (h-11 w-11) for WCAG AAA compliance.
```
### Always Include Both ✅ and ❌
**✅ Correct:** Meets 44px minimum
```tsx
```
**❌ Wrong:** Too small (32px)
```tsx
```
### Explain Why (Briefly)
```markdown
Use h-11 (44px) for buttons - WCAG Level AAA requires 44×44px touch targets.
```
### Cross-Reference
```markdown
See @.rulesync/rules/accessibility.md
Real example: @app/components/ui/Button/Button.tsx:23-26
```
### Avoid Inline Comment Markers in Examples
> **Important:** Don't use `// ✓ Correct` or `// ✗ Wrong` inside code blocks. AI agents learn from examples and will mimic comment patterns in actual code.
**✓ Use markdown prose labels above code blocks:**
```markdown
**✅ Correct:**
\`\`\`tsx
\`\`\`
```
## Length Guidelines
- **Target:** 100-200 lines (like react-hooks.mdc, design-system.mdc, core-standards.mdc)
- **Maximum:** 300 lines before splitting
- **Red flag:** 400+ lines (too verbose, split into multiple files)
## Rule Scope Decision
**New file when:**
- Distinct domain (testing ≠ styling ≠ accessibility)
- Different globs
**Extend existing when:**
- Same domain
- Same globs
- Brief addition (<30 lines)
## File Naming
**Prefer semantic names** over numbered prefixes (self-documenting, no renumbering on insert):
```
✓ accessibility.mdc, design-system.mdc, testing.mdc
✗ 001-accessibility.mdc, 002-design-system.mdc
```
**Exception:** Use `000-` prefix for meta-rule only if ordering matters.
## Common Pitfalls
❌ Repeating examples across multiple sections
❌ Over-explaining obvious patterns
❌ Too many component-specific subsections
❌ Redundant anti-pattern examples
❌ Verbose prose instead of bullet points
✅ One clear example per pattern
✅ Bullet points over paragraphs
✅ Trust AI to generalize from examples
✅ Link to code instead of duplicating
✅ Quick reference table/list
## Self-Check
Before saving a rule:
- [ ] Under 300 lines?
- [ ] Each example has ✓ or ✗ marker?
- [ ] Measurable standards stated?
- [ ] Cross-references instead of duplication?
- [ ] No redundant sections?
## Template
````markdown
---
globs: app/target/**/*.tsx
alwaysApply: false
---
# Title
**One-sentence purpose.**
## Standard
**Min: Xpx** | **Recommended: Ypx**
**✅ Correct:**
```tsx
```
**❌ Wrong:**
```tsx
```
## Quick Reference
- ✅ Do this
- ❌ Not this
See: @path/file.tsx
````
---
## Validation Before Committing
**Run this prompt with AI to validate your rules:**
```
Review the agent rule file I've created and check for quality.
FILE: [your-rule-name].mdc
LINES: [count]
Validate against these 8 criteria:
1. LENGTH: Under 300 lines? (Target: 100-200)
2. STRUCTURE: Bold opening + measurables + ✓/✗ + quick ref?
3. EXAMPLES: Every pattern has ✓ and ✗ markers?
4. SPECIFICITY: Uses exact numbers (44px, <100ms) not vague terms?
5. REFERENCES: Uses @ notation for real files?
6. FRONTMATTER: Has globs + alwaysApply + last_updated?
7. REDUNDANCY: No repeated examples or explanations?
8. ACTIONABLE: AI can enforce without ambiguity?
Provide:
- Overall score: Pass / Needs Revision / Fail
- Line count: X / 300
- Issues found: [list specific problems]
- Recommended fixes: [concrete improvements]
- Grade: A+ / A / B / C / D / F
Use this scoring:
- A/A+ (90-100%): Ready to use
- B/B+ (80-89%): Fix 1-2 issues
- C/C+ (70-79%): Fix 3-4 issues
- D (60-69%): Major revision
- F (<60%): Rewrite from scratch
```
**Validation checklist:**
- [ ] Under 300 lines?
- [ ] Opens with bold statement?
- [ ] Has specific numbers?
- [ ] Every example has ✓ or ✗?
- [ ] References real files with @?
- [ ] Has quick reference?
- [ ] Glob patterns specific?
- [ ] No vague language?
Only commit rules that score B+ or higher.