Effective Rule Writing Guide
How to write rules that AI agents actually follow — patterns that work.
1. Be Specific, Not Aspirational
Rules are constraints, not goals. The agent needs to know exactly what to do and what not to do. Vague instructions like "write clean code" give the agent no actionable guidance.
Use const by default. Use let only when reassignment is needed. Never use var.
Use modern JavaScript best practices.
The good version is verifiable — you can check the output and confirm compliance. The bad version is subjective and unenforceable.
All API responses must include { data, error, status } fields. Return null for data on error, null for error on success.
Handle errors properly in API responses.
Concrete structure gives the agent a template to follow. 'Handle errors properly' means different things to different people.
2. Include Examples
Examples are the most effective part of any rule. The agent pattern-matches against examples more reliably than it interprets abstract instructions. Show what good output looks like.
Example: A well-structured rule with code examples
---
name: component-patterns
description: React component conventions for this project. Apply when creating or modifying TSX files.
globs: ["**/*.tsx"]
---
# Component Patterns
## Rules
- Use functional components exclusively (no class components)
- Props interfaces must be defined above the component
- Destructure props in the function signature
- Use `cn()` utility for conditional classNames (never string concatenation)
## Naming
- Component files: PascalCase.tsx (e.g., UserProfile.tsx)
- Hook files: use-kebab-case.ts (e.g., use-auth.ts)
- Utility files: kebab-case.ts (e.g., format-date.ts)
## Examples
### Good
```tsx
interface UserCardProps {
name: string;
email: string;
isActive?: boolean;
}
function UserCard({ name, email, isActive = true }: UserCardProps) {
return (
<div className={cn("card", isActive && "card-active")}>
<h3>{name}</h3>
<p>{email}</p>
</div>
);
}
```Pattern
3. Get the Frontmatter Right
The frontmatter determines when and how Antigravity activates the rule. Getting this wrong means your rule either fires when it shouldn't or doesn't fire when it should.
name
Lowercase, hyphenated identifier. Used for @rule-name mentions. Keep it short and descriptive.
description
For model-decision activation, this is what the model reads to decide relevance. Be specific: "Apply when writing React components or modifying TSX files" not "React stuff."
alwaysApply
Set to true only for rules that must apply to every conversation (governance, meta-learning). This consumes tokens on every interaction.
globs
Array of file patterns. Use the most specific pattern possible.["**/*.tsx"] is better than ["**/*"]. You can combine multiple patterns: ["src/api/**/*.ts", "src/routes/**/*.ts"].
4. One Rule, One Concern
A rule that covers "coding standards, testing, deployment, and documentation" is trying to do too much. Split it into focused rules that each handle one domain.
Separate rules: coding-standards, testing-patterns, deployment-config, documentation-format
One mega-rule: project-standards (covers everything)
Focused rules can use different activation modes. Your testing rule only needs to fire when editing test files. Your deployment rule only fires for config files. A mega-rule wastes context on irrelevant instructions.
5. State Both Dos and Don'ts
Rules that only say what to do leave ambiguity about what not to do. Pairing positive instructions with explicit prohibitions makes the constraint clearer.
Always use named exports for components. Never use default exports except for page-level route components.
Use named exports.
The 'never' clause prevents the agent from defaulting to common patterns (most tutorials use default exports). The exception clause handles the legitimate use case.
6. Test Your Rules
After writing a rule, test it by asking the agent to perform a task that should trigger it. If the agent doesn't follow the rule:
1. Check that the activation mode is correct (is the rule actually being loaded?)
2. Verify the wording is concrete enough (add examples if it's too abstract)
3. Check for conflicting rules that might override this one
4. Simplify — shorter, clearer rules are followed more reliably than long, complex ones
Rule of Thumb
Rules vs. Skills: When to Use Which
This distinction matters for proper Learner Brain design:
Rules (RULE.md)
- • Passive constraints — "always do X, never do Y"
- • Injected into the system prompt
- • Govern behavior across all tasks
- • Live in
.agent/rules/ - • Can be always-on, glob, model-decision, or manual
Skills (SKILL.md)
- • Active procedures — "when doing X, follow these steps"
- • Loaded on demand via progressive disclosure
- • Invoked for specific tasks
- • Live in
.agent/skills/ - • Require a
descriptionin frontmatter
References
- Antigravity Rules & Workflows Documentation — Official documentation on rule activation modes and structure
- Antigravity Skills Documentation — Skills format, frontmatter fields, and progressive disclosure
This template was last reviewed in April 2026 against the official Antigravity rules & workflows docs. Spot something out of date? Let us know.