Creating AI Agent Rules

Rules provide persistent instructions the agent follows across sessions. Each platform uses a different mechanism—choose based on the current environment.

Platform Overview

.mdc

.cursor/rules/

globs

alwaysApply

.mdc

.gemini/rules/

globs

alwaysApply

AGENTS.md

Gather Requirements

Before creating a rule, determine:

1. Purpose: What should this rule enforce or teach?
2. Scope: Should it always apply, or only for specific files/directories?
3. File patterns: If file-specific, which glob patterns?

If the user hasn't specified scope, ask:

• "Should this rule always apply, or only when working with specific files?"

If they mentioned specific files without providing patterns, ask:

• "Which file patterns should this rule apply to?" (e.g.,

  **/*.ts

  ,

  backend/**/*.py

  )

Use a structured question tool if available, otherwise ask conversationally.

Cursor & Gemini CLI:

.mdc

Rule Files

Rules are

.mdc

.cursor/rules/      # Cursor
.gemini/rules/      # Gemini CLI

File Structure

---
description: Brief description of what this rule does
globs: **/*.ts
alwaysApply: false
---

# Rule Title

Your rule content here...

Frontmatter Fields

description

globs

alwaysApply

true

Rule Configurations

Always Apply — universal standards that apply to every conversation:

---
description: Core coding standards for the project
alwaysApply: true
---

Apply to Specific Files — conventions scoped to file types:

---
description: TypeScript conventions for this project
globs: **/*.ts
alwaysApply: false
---

Codex:

AGENTS.md

Files

Codex reads

AGENTS.md

<!-- AGENTS.md at repo root — applies project-wide -->

- Always use `async/await` over `.then()` chains.
- Run `npm test` after any logic change.
- Follow the error handling pattern defined in `src/errors.ts`.

Placement guide:

AGENTS.md

src/AGENTS.md

src/

src/api/AGENTS.md

src/api/

Best Practices

• Under 50 lines: Keep rules concise and focused.
• One concern per rule: Split large rules into separate files.
• Actionable: Write like clear internal docs, not vague guidelines.
• Concrete examples: Show the bad pattern and the correct pattern.

Example (

.mdc

)

---
description: TypeScript error handling standards
globs: **/*.ts
alwaysApply: false
---

# Error Handling

\`\`\`typescript
// ❌ BAD
try { await fetchData(); } catch (e) {}

// ✅ GOOD
try {
await fetchData();
} catch (e) {
logger.error('Failed to fetch', { error: e });
throw new DataFetchError('Unable to retrieve data', { cause: e });
}
\`\`\`

Checklist

• Correct format for current platform (

  .mdc

  vs

  AGENTS.md

  )
• Frontmatter configured correctly (Cursor/Gemini CLI only)
• Content under 500 lines
• Includes at least one concrete example