Creating Custom Rules Files for AI Coding Tools

Custom rules files let you define how AI coding agents (like Cline, Cursor, or Copilot) behave in your codebase. By providing explicit instructions, you ensure the AI follows your project’s coding style, architecture, and security practices. This tutorial walks you through creating a practical rules file for a TypeScript React project.

Step 1: Understand the Rules File Format

Most AI coding tools read a rules file from the project root. Common names include:

• .clinerules (Cline)
• .cursorrules (Cursor)
• .windsurfrules (Windsurf)

Rules are written in plain language (often Markdown or YAML). The AI agent uses these as system-level instructions for every task.

Step 2: Define Core Guidelines

Start with high-level instructions that apply to all code generated. For a TypeScript React app, create .clinerules with:

# Cline Rules for My Project

Always follow these conventions:

## General
- Use TypeScript strict mode.
- Prefer functional components with hooks over class components.
- Use named exports, not default exports.
- All functions must have JSDoc comments.
- Use absolute imports (using `@/` alias) for project files.
- Keep files under 200 lines; split into smaller modules if exceeded.

## Testing
- Write unit tests for every utility function.
- Use React Testing Library for component tests.
- Test file should be co-located: `Component.test.tsx`.

Step 3: Add Project-Specific Architecture Rules

Include rules that reflect your actual folder structure and patterns. For example, if you use a custom API layer:

## API Layer
- All API calls go through services/api.ts.
- Use the custom useApi hook for data fetching.
- Error handling: always catch errors and display toast via useToast.
- Never use fetch directly; use the provided Axios instance.

Step 4: Enforce Security and Best Practices

Add rules to prevent common mistakes:

## Security
- Never hardcode secrets. Use environment variables via `import.meta.env.VITE_*`.
- Sanitize user input before rendering using DOMPurify.
- Avoid `eval()` and `innerHTML`.

## Performance
- Use React.memo for heavy components.
- Lazy load routes with `React.lazy` and Suspense.

Step 5: Test and Iterate

Now test the rules by asking the AI to perform a task, like “Create a new component for user profile.” The AI should follow your rules. If it doesn’t, adjust the wording to be more explicit.

Example: Full .clinerules for a React Project

Here's a complete rules file:

# Cline Rules

## Code Style
- TypeScript strict mode, no `any`.
- Prettier formatting with 2-space indent.
- Trailing commas on all multiline statements.

## Imports
- Absolute imports from `@/`.
- Group imports: React → third-party → internal.

## Components
- Functional components only.
- Props interface defined right above the component.
- Destructure props in the function signature.

## State Management
- Use Zustand for global state.
- Local state with useState/useReducer.
- No Redux.

## Data Fetching
- Use React Query (TanStack Query) for server state.
- Custom hooks for each data domain.

## Testing
- Jest + React Testing Library.
- Test user interactions, not implementation details.
- Aim for 80%+ coverage on new code.

Going Further

You can create multiple rules files for different environments (e.g., frontend vs backend) by placing them in subdirectories. Some tools support partial rules or inheritance.

Custom rules files are a simple but powerful way to make AI coding agents work for you, not against you. Start small, iterate, and watch your AI-generated code become more consistent and reliable.