Engineer Rule

Rule Creator

This skill guides through creating persistent rules — instructions that automatically apply to AI agent sessions, enforcing coding standards, project conventions, and file-specific patterns.

About Rules

Rules are markdown files with metadata that provide persistent context to AI agents. They differ from skills in that rules are automatically injected into every relevant session without explicit invocation.

Rules serve two purposes:

1. Always-apply rules — universal standards for every conversation (coding style, architecture decisions, project conventions)
2. Conditional rules — file-specific patterns triggered when matching files are open (TypeScript conventions for *.ts, React patterns for *.tsx)

IDE Detection and Rule Placement

Rules work across multiple IDEs but use different file formats and locations. Before creating a rule, determine the current environment.

Control Primitives Map by IDE

Rule-Specific Paths

Detection Strategy

1. Check for IDE-specific markers in the project:
   • .cursor/ directory -> Cursor
   • .claude/ directory -> Claude Code
   • .opencode/ directory or opencode.json -> OpenCode
2. If multiple detected or none -> ask the user
3. Ask: always-apply or conditional (file-specific)?

Gather Requirements

Before creating a rule, determine:

1. Purpose: What should this rule enforce or teach?
2. Scope: Always apply, or only for specific files?
3. File patterns: If conditional, which glob patterns? (e.g., **/*.ts, backend/**/*.py)

Inferring from Context

If prior conversation context exists, infer rules from what was discussed. Create multiple rules if the conversation covers distinct topics. Don't ask redundant questions if context provides answers.

Required Questions

If scope not specified:

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

If file-specific but no concrete patterns:

• "Which file patterns should this rule apply to?"

Rule Format by IDE

Cursor

Directory-based rules in .cursor/rules/<rule-name>/RULE.md:

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

# Rule Title

Rule content here...

Legacy format (.cursor/rules/*.mdc) still works but is deprecated. Prefer directory format.

Claude Code

Rules in .claude/rules/*.md (subdirectories discovered recursively). Frontmatter fields: paths (array of glob strings), description (optional, informational only — does NOT scope the rule). Cursor-specific fields (globs, alwaysApply) are silently ignored (rule becomes always-apply).

Conditional rule (loads when Claude reads a matching file):

---
paths:
  - "src/**/*.ts"
---

# Rule Title

Rule content here...

Multiple glob patterns:

---
paths:
  - "src/**/*.ts"
  - "lib/**/*.{ts,tsx}"
  - "tests/**/*.test.ts"
---

Always-apply rule: omit paths frontmatter entirely, or use CLAUDE.md (project root / subdirectory).

Limitations: paths: triggers on Read only — Write/Edit to a matching path without prior Read does NOT load the rule.

OpenCode

Always-apply rules in AGENTS.md (project root, plain markdown):

# Rule Title

Rule content here...

Or via opencode.json field instructions (array of paths, globs, or URLs):

{
  "instructions": [
    "AGENTS.md",
    ".cursor/rules/**/*.md",
    "https://example.com/standards.md"
  ]
}

Global user rules: ~/.config/opencode/AGENTS.md. Falls back to ~/.claude/CLAUDE.md unless OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1.

Core Principles

Keep Rules Concise

• Under 50 lines preferred, max 500 lines
• One concern per rule: split large rules into focused pieces
• Actionable: write like clear internal docs
• Concrete examples: show good/bad patterns with code

Structure

Every rule should contain:

1. Clear title — what aspect it covers
2. Brief context — why this rule exists (1-2 sentences max)
3. The rules themselves — concrete, actionable instructions
4. Examples — good/bad code patterns when applicable

Naming

• Cursor: directory name = kebab-case (e.g., typescript-standards/RULE.md)
• Claude Code: filename = kebab-case.md (e.g., typescript-standards.md)
• Others: section heading in the shared file

Rule Creation Process

Phase 1: Discovery

1. Determine IDE (auto-detect or ask)
2. Determine scope (always-apply vs conditional)
3. Determine file patterns if conditional
4. Gather the actual standards/conventions to encode

Phase 2: Implementation

1. Create the rule file in the correct location for the detected IDE
2. Write frontmatter with appropriate fields
3. Write concise, actionable rule content
4. Include concrete code examples (good/bad patterns)

Phase 3: Verification

Run validation:

deno run -A scripts/validate_rule.ts <path/to/rule-file-or-directory>

Checklist:

• Correct file format for target IDE
• Frontmatter configured correctly for target IDE (Cursor: description, globs, alwaysApply; Claude Code: paths required, description optional)
• Content under 500 lines (prefer under 50)
• Includes concrete examples
• One concern per rule
• No redundancy with existing rules

Common Rule Categories

Example Rules

Error Handling (TypeScript) — Cursor

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

# Error Handling

Always use typed errors with context:

\`\`\`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 });
}
\`\`\`

Error Handling (TypeScript) — Claude Code

---
paths:
  - "**/*.ts"
---

# Error Handling

Always use typed errors with context:

\`\`\`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 });
}
\`\`\`

React Patterns — Cursor

---
description: React component patterns
globs: "**/*.tsx"
alwaysApply: false
---

# React Patterns

- Use functional components
- Extract custom hooks for reusable logic
- Colocate styles with components
- Props interface named `{ComponentName}Props`

React Patterns — Claude Code

---
paths:
  - "**/*.tsx"
  - "**/*.jsx"
---

# React Patterns

- Use functional components
- Extract custom hooks for reusable logic
- Colocate styles with components
- Props interface named `{ComponentName}Props`

Project Architecture (Always Apply) — Cursor

---
description: Core architecture rules
alwaysApply: true
---

# Architecture

- Domain logic in `src/domain/` — no framework imports
- API handlers in `src/api/` — thin, delegate to domain
- Shared types in `src/types/` — no runtime code

Project Architecture (Always Apply) — Claude Code

# Architecture

- Domain logic in `src/domain/` — no framework imports
- API handlers in `src/api/` — thin, delegate to domain
- Shared types in `src/types/` — no runtime code