Cline Rules: Complete `.clinerules` Guide with Templates (2026)

Last updated: March 2026

Cline Rules are project-level instructions stored in a .clinerules file that tell Cline exactly how to write code, structure files, run commands, and behave across every task in your project. Without them, Cline falls back to model defaults — with them, every task automatically follows your team's standards, stack conventions, and workflow preferences.

This guide covers the .clinerules file format, workspace vs. global scope, ready-to-use templates for common stacks, Plan/Act mode behaviour, rule anti-patterns, and a step-by-step debugging workflow for rules that aren't working.

1. What Are Cline Rules and How Do They Work

Cline Rules are plain-text instructions that get injected into the system prompt of every conversation Cline has within a project. Every time you give Cline a task — whether it's writing a new component, fixing a bug, or running a refactor — the rules are included automatically in the context. Cline reads them before generating any response or taking any action.

Think of .clinerules as a standing brief for a contractor. Instead of explaining your conventions every single time you start a task, you write them once, store them in the project, and Cline applies them consistently across all work.

What rules actually control:

Which files and folders Cline creates, and where
Code style and architecture patterns to follow
Commands Cline is allowed or not allowed to run
How Cline should handle errors, tests, and edge cases
When to ask for clarification vs. proceed autonomously
How Cline interacts with MCP tools and external services
Task decomposition strategy (how Cline breaks big tasks into steps)

What rules do not control:

Cline's underlying model capabilities or context window
Which model is used (that's set in VS Code settings)
Anything outside the project scope (global behaviour is managed separately via global rules)

2. File Format and Syntax

Cline Rules files are plain Markdown. There is no special syntax, schema, or required structure — just clear, imperative English instructions that Cline can follow.

File locations

Location	File	Scope
Project root	`.clinerules`	All tasks in this project
Project rules folder	`.clinerules/` (directory with multiple `.md` files)	Modular rules, loaded together
VS Code settings	Custom Instructions field	Applies across all projects globally

Primary file: `.clinerules`

Place this file in the root of your project, next to package.json, pyproject.toml, or whatever your project's root config file is.

my-project/
├── .clinerules          ← Cline reads this automatically
├── .gitignore
├── package.json
└── src/

Directory-based rules: `.clinerules/`

For larger projects, you can split rules into multiple files inside a .clinerules/ directory. Cline loads and merges all .md files from this directory.

my-project/
├── .clinerules/
│   ├── general.md       ← General task and code standards
│   ├── testing.md       ← Testing-specific rules
│   ├── api.md           ← API design rules
│   └── mcp.md           ← MCP tool usage rules

This is useful when rules grow beyond ~150 lines, or when different team members maintain different rule files.

Syntax guidelines

Write in imperative sentences: "Always use named exports." not "Named exports should be preferred."
Be specific and measurable: "Functions must not exceed 40 lines." not "Keep functions short."
Avoid ambiguity: "Use async/await instead of .then() chains." not "Handle async properly."
Group related rules under Markdown headings (##, ###) — Cline uses these as structural context.
Use bullet lists for sets of related constraints.
Use code blocks (` or ```) for exact patterns, naming conventions, or examples.

Minimal working example

# Project Rules

## Language and environment
- Use TypeScript strict mode throughout the project.
- Node.js version: 20+. Do not use CommonJS `require()` — use ES module `import`.

## File structure
- New components go in `src/components/`.
- Each component gets its own folder: `src/components/Button/Button.tsx` + `Button.test.tsx`.

## Code style
- Functional components only. No class components.
- Use named exports for all components and utilities.
- No `any` types. If the type is unknown, use `unknown` and narrow it.

## Task behaviour
- Before implementing, write a 3-step plan in a comment block.
- Run `npm test` after every implementation to confirm nothing is broken.
- If requirements are ambiguous, ask one clarifying question before starting.

3. Workspace Rules vs. Global Rules

Cline supports two levels of rule scope. Understanding the difference prevents confusion about which rules apply where.

Dimension	Workspace Rules (`.clinerules`)	Global Rules (Custom Instructions)
Location	Project root or `.clinerules/` directory	VS Code Cline settings → Custom Instructions
Scope	This project only	All projects, all tasks
Priority	Higher — overrides global rules on conflict	Lower — baseline defaults
Version controlled	Yes — lives in the repo, shared with team	No — stored locally in VS Code
Best for	Project-specific stack, architecture, naming conventions	Personal preferences, general agent behaviour
Examples	"Use Prisma for DB access", "All API routes go in `app/api/`"	"Always ask before deleting files", "Use British English"

Rule priority on conflict

When a workspace rule and a global rule contradict each other, the workspace rule wins. This is intentional: project context is more specific and should take precedence.

Example conflict:

Global rule: "Use console.log for debug output."
Workspace rule: "Never use console.log. Use the project's logger utility from src/lib/logger.ts."

Cline will follow the workspace rule and use logger.

What to put in global rules

Global rules are your personal defaults as a developer — things you want everywhere, regardless of project:

## General behaviour
- Always show a brief implementation plan before writing code.
- Never delete files without asking for confirmation first.
- When creating new files, check if a similar file already exists.
- Prefer composition over inheritance.

## Communication
- Keep explanations concise. Skip preamble — get to the answer.
- If a task is unclear, ask one specific question rather than proceeding with assumptions.

What to put in workspace rules

Workspace rules encode project-specific knowledge that Cline cannot infer from the codebase alone:

## Stack
- Frontend: Next.js 14 App Router. Backend: FastAPI. Database: PostgreSQL via Prisma.
- Do not use the Pages Router. All routes go in `app/`.

## Architecture decisions
- State management: Zustand only. Do not introduce Redux or Context API for state.
- All database queries go through service functions in `src/services/`. Never query directly from components.

## Conventions
- API response format: always `{ success: boolean, data?: T, error?: string }`.
- Environment variables: access only through `src/config/env.ts`, never `process.env` directly.

4. Cline Rules vs. Custom Instructions vs. Cline Docs

Cline provides three mechanisms for giving it contextual information. They serve different purposes and should not be used interchangeably.

Mechanism	What it is	Persists across tasks	Version controlled	Best for
`.clinerules` (workspace)	Project-level standing instructions	Yes	Yes	Architecture, stack conventions, naming, workflow rules
Custom Instructions (global)	Personal developer defaults in VS Code settings	Yes	No	Personal preferences, agent behaviour, communication style
Cline Docs (`@` mentions)	Files or documentation referenced in a specific task	No — per-task only	Yes (the files)	Task-specific context: a spec doc, a design file, an API schema
In-task instructions	Instructions given directly in the chat message	No — one task only	No	One-off overrides, unique task requirements

The practical decision rule:

If you'll need this instruction in more than one task → put it in .clinerules
If it's personal preference that doesn't belong in the repo → put it in Custom Instructions
If it's specific to one task's context (a spec, a schema) → use @ to reference the file
If it's a one-time override → say it in the task message

5. How to Set Up Cline Rules

Method 1: Create a `.clinerules` file

This is the recommended approach for any project with more than one developer or any project you'll work on for longer than a week.

# In your project root
touch .clinerules

Then add your rules in Markdown. Cline detects the file automatically — no configuration needed.

Should you commit .clinerules to git?

Yes. In most cases, .clinerules should be committed. It encodes project conventions that every contributor (human and AI) should follow. Treat it like .eslintrc or prettier.config.js — it's part of the project's code quality infrastructure.

If the file contains personal preferences that don't belong to the project, put those in global Custom Instructions instead.

Method 2: Directory-based rules

mkdir .clinerules
touch .clinerules/general.md
touch .clinerules/testing.md

Cline will load all .md files from this directory. Use this when:

Your rules exceed ~150 lines
Different categories of rules are maintained by different people
You want to be able to enable/disable rule sets by adding/removing files

Method 3: Global Custom Instructions

Open Cline in VS Code (sidebar icon)
Click the gear icon (⚙️) in the Cline panel
Find the Custom Instructions field
Add your global rules there

These apply to every project, every task. Keep them short and generic.

Method 4: In-task instructions

Pass instructions directly in your task prompt for one-off requirements:

"Following the patterns in src/services/userService.ts, create a similar 
service for product management. Include CRUD operations and error handling 
matching the existing conventions."

This doesn't persist — the instructions only apply to that task.

6. Ready-to-Use `.clinerules` Templates

These are complete, production-ready .clinerules files for common stacks. They are starting points — adapt them to your project's specifics.

Template 1: Next.js 14 App Router + TypeScript + Prisma

# Project Rules — Next.js 14 / TypeScript / Prisma

## Environment
- Framework: Next.js 14 with App Router. TypeScript strict mode.
- Database: PostgreSQL via Prisma ORM.
- Styling: Tailwind CSS only. Do not introduce CSS Modules or styled-components.
- Testing: Vitest + React Testing Library.

## File structure rules
- All routes go in `app/`. Never use `pages/`.
- Server components are the default. Mark client components with `'use client'` only when necessary (event handlers, browser APIs, useState/useEffect).
- API routes go in `app/api/[resource]/route.ts`.
- Shared UI components go in `src/components/`.
- Business logic and data access go in `src/services/` — never in components or route handlers directly.
- Types and interfaces go in `src/types/`.

## Component rules
- Functional components only. No class components.
- Named exports for all components (`export const Button = ...`, not `export default`).
- Props interfaces go directly above the component definition.
- No `any` type. Use `unknown` and narrow it, or define a proper interface.

## Data access rules
- All Prisma queries go through service functions in `src/services/`.
- Service functions must return `{ data: T } | { error: string }` — never throw directly to the component layer.
- Never call `prisma` directly inside a component, page, or route handler.

## API response format
All API routes must return responses in this shape:
- Success: `{ success: true, data: T }`
- Error: `{ success: false, error: string, code?: string }`

## Task behaviour
- Before implementing any new feature, confirm the file locations for new files.
- Run `npm run build` after major changes to catch type errors.
- When creating a new database model, also create its corresponding service file.
- After writing tests, run them to confirm they pass before completing the task.
- If a task requires installing a new package, show me the package and reason before running `npm install`.

Template 2: FastAPI + Python + SQLAlchemy

# Project Rules — FastAPI / Python / SQLAlchemy

## Environment
- Python 3.12+. Use type hints everywhere.
- Web framework: FastAPI. Do not use Flask or Django.
- ORM: SQLAlchemy 2.0 with async sessions.
- Package manager: Poetry. Do not use pip directly.
- Testing: pytest + pytest-asyncio.

## Project structure
- API routes go in `app/routers/` — one file per resource (e.g., `users.py`, `products.py`).
- Business logic goes in `app/services/` — keep route handlers thin.
- Database models go in `app/models/`.
- Pydantic schemas go in `app/schemas/`.
- Database queries go in `app/repositories/` — no direct ORM queries in services.

## Code style
- Use `async def` for all route handlers and service functions.
- Use Pydantic models for all request bodies and response shapes — never return raw dicts.
- Response models must be defined as Pydantic schemas and passed to `response_model=` in route decorators.
- All database operations must be inside try/except blocks with proper rollback on error.

## API conventions
- HTTP methods: GET (read), POST (create), PUT (replace), PATCH (update), DELETE (remove).
- Use plural nouns for all resource paths: `/users`, `/products`, not `/user`, `/product`.
- Versioning prefix: all routes start with `/api/v1/`.
- Status codes: 200 for GET/PUT/PATCH success, 201 for POST success, 204 for DELETE.

## Error handling
- Define custom exception classes in `app/exceptions.py`.
- Register exception handlers in `app/main.py` — not inline in routes.
- Never expose internal error details to the client. Use generic messages in the response and log the full error.

## Task behaviour
- When adding a new endpoint, always create or update the corresponding Pydantic schema first.
- After adding a new model, generate a migration with `alembic revision --autogenerate`.
- Run `pytest` after implementation. Show me the output.
- If a task would require modifying more than 3 files, show me the plan first.

Template 3: React + TypeScript SPA (Vite + Zustand + React Query)

# Project Rules — React SPA / TypeScript / Zustand / React Query

## Environment
- React 18, TypeScript strict mode, Vite as bundler.
- State: Zustand for client state. React Query (TanStack Query) for server state.
- Styling: Tailwind CSS. No inline styles, no CSS Modules.
- Testing: Vitest + React Testing Library.

## Component conventions
- One component per file.
- File and component name must match: `UserCard.tsx` exports `UserCard`.
- All components use named exports.
- Props interfaces defined directly above the component: `interface UserCardProps { ... }`.
- Hooks at the top of the component, before any other logic.
- No `useEffect` for data fetching — use React Query instead.

## State management
- Zustand stores go in `src/stores/`. One store per domain (e.g., `useAuthStore`, `useCartStore`).
- Server state (API data) is managed by React Query only — do not duplicate it in Zustand.
- Zustand store actions must be defined inside the store, not as standalone functions.

## Data fetching
- All API calls go through service functions in `src/services/`.
- Service functions return typed responses — never `any`.
- Use React Query's `useQuery` for reads, `useMutation` for writes.
- Set appropriate `staleTime` and `gcTime` per query — do not rely on defaults.

## File structure

src/ components/ # Reusable UI components features/ # Feature-scoped components and logic services/ # API service functions stores/ # Zustand stores hooks/ # Custom hooks types/ # Shared TypeScript types utils/ # Pure utility functions


## Task behaviour
- When creating a new feature, follow this order: types → service function → React Query hook → component.
- Never add a library without asking first. Show me what it does and why we need it.
- Run `npm run type-check` after completing a task.

Template 4: Node.js + Express + TypeScript + PostgreSQL (pg)

# Project Rules — Node.js / Express / TypeScript / PostgreSQL

## Environment
- Node.js 20+, TypeScript 5+, Express 4.
- Database: PostgreSQL via `pg` (node-postgres). No ORM — raw SQL with parameterized queries.
- Testing: Jest + Supertest.
- Process manager in production: PM2.

## Project structure

src/ routes/ # Express Router definitions — thin, no logic controllers/ # Request handling, input validation services/ # Business logic db/ # Database queries, connection pool middleware/ # Auth, error handling, rate limiting types/ # Shared TypeScript interfaces


## Database rules
- All SQL goes in `src/db/queries/` — never inline in services or controllers.
- Always use parameterized queries: `db.query('SELECT * FROM users WHERE id = $1', [id])`.
- Never concatenate user input into SQL strings.
- Use a single connection pool initialized in `src/db/pool.ts`.
- Wrap multi-step operations in transactions.

## API rules
- Input validation happens in the controller, before calling any service function.
- Error responses: `{ success: false, error: string }`. Never expose stack traces.
- Successful responses: `{ success: true, data: T }`.
- All route handlers must be wrapped in `asyncHandler()` — no unhandled promise rejections.

## Security
- Never log sensitive fields (passwords, tokens, PII) — log the user ID and action instead.
- Set `helmet()` and `cors()` in `src/app.ts`.
- Rate limiting on all public routes.
- JWT secrets from environment variables only — never hardcoded.

## Task behaviour
- When adding a new route, update the corresponding controller, service, and query file.
- Before writing migration SQL, show me the schema change and ask for confirmation.
- Run `npm test` after completing a task.

Template 5: Go + Gin + PostgreSQL

# Project Rules — Go / Gin / PostgreSQL

## Environment
- Go 1.22+. Web framework: Gin. Database driver: `pgx`.
- No ORM. Use raw SQL via `pgx` with named queries.
- Testing: standard `testing` package + `testify`.

## Project structure

cmd/ # Entrypoints (main.go) internal/ handlers/ # HTTP handler functions services/ # Business logic repository/ # Database access layer models/ # Struct definitions middleware/ # Gin middleware config/ # Environment and config loading


## Code conventions
- Errors are always returned, never panicked on (except in `main.go` init failures).
- Every exported function must have a godoc comment.
- Interfaces go in the package that uses them, not the package that implements them.
- Use `context.Context` as the first parameter in all service and repository functions.

## Error handling
- Return `(T, error)` from service and repository functions.
- Handlers translate errors to HTTP status codes — services never set status codes.
- Log the full error internally; return a generic message to the client.

## Database
- All queries go in `internal/repository/`.
- Use pgx named arguments for all queries with more than one parameter.
- Use database transactions for operations that modify more than one table.

## Task behaviour
- Run `go build ./...` and `go vet ./...` after completing a task.
- When adding a new endpoint, follow this order: model → repository → service → handler → route registration.
- If a task involves modifying the database schema, write the migration SQL and show it to me before applying.

7. Rules for Specific Workflows

Beyond stack conventions, you can write rules that govern how Cline approaches specific types of work.

Refactoring rules

## Refactoring behaviour
- Before refactoring, identify which tests cover the target code. List them.
- Refactor in small steps — one logical change at a time. Do not combine refactoring with feature changes.
- Run tests after each step to confirm nothing is broken.
- If no tests exist for the target code, write them before refactoring.
- Do not change public interfaces (function signatures, exported types) during refactoring without flagging it.

Debugging rules

## Debugging behaviour
- When investigating a bug, first reproduce it with a minimal test case. Show me the test.
- Explain the root cause before proposing a fix.
- Do not add `console.log` statements as a permanent fix — use the project's logger.
- If the fix touches more than 3 files, explain the change propagation path.

Code review preparation rules

## Code review preparation
- After completing a task, summarize the changes in this format:
  - What changed (brief description)
  - Why it was changed
  - Files affected
  - Edge cases considered
  - What to review carefully
- Flag any technical debt introduced with a `// TODO:` comment and a reason.

Large codebase navigation rules

## Codebase navigation
- Before creating a new utility function, search for an existing one with `grep -r`.
- Before creating a new component, check `src/components/` for similar ones.
- When unsure where a new file belongs, look at 2–3 similar files in the codebase and follow their pattern.
- Never create a new folder without first checking if an appropriate one already exists.

8. Plan Mode vs. Act Mode and How Rules Apply

Cline has two operating modes. Understanding how rules behave in each mode helps you write rules that work correctly regardless of mode.

Dimension	Plan Mode	Act Mode
What Cline does	Reasons through the task, produces a plan	Executes actions: creates files, runs commands
File system access	Read-only	Read and write
Terminal access	None	Full (with your approval)
When rules apply	Yes — Cline uses rules to inform the plan	Yes — Cline uses rules to govern execution
Rule types that matter most	Task decomposition rules, clarification rules	Code style rules, file structure rules, command restrictions

Rules that are primarily relevant in Plan mode

## Planning behaviour
- Break any task estimated at more than 30 minutes into discrete steps.
- If a task requires touching more than 5 files, produce a step-by-step plan and wait for approval.
- Identify dependencies between steps before starting.
- Flag tasks that require new package installations before including them in a plan.

Rules that are primarily relevant in Act mode

## Execution behaviour
- Never run `npm install <package>` without prior approval.
- Never modify files in `src/config/` without asking first.
- Always run the test suite after implementation, before marking a task complete.
- When creating a new file, do not copy-paste boilerplate — generate it from first principles.

Rules that apply in both modes

## Always apply
- Follow the file structure defined in this rules file.
- Use the project's existing utilities — do not re-implement what already exists.
- Prefer explicit over implicit. Clear code over clever code.

9. MCP-Aware Rules

If your project uses Cline with MCP (Model Context Protocol) servers, you can write rules that govern how Cline interacts with those tools.

Why MCP rules matter

Without rules, Cline may use MCP tools in inconsistent ways — calling the wrong tool for a task, failing to handle MCP errors properly, or not knowing which MCP server to prefer when multiple are available.

Example: rules for a project using a database MCP and a file storage MCP

## MCP tool usage

### Database (postgres-mcp)
- Use `postgres-mcp` for all database introspection tasks (schema inspection, table listing, query testing).
- Never run `DROP` or `DELETE` queries via MCP without showing me the query first and waiting for approval.
- For large queries, add `LIMIT 100` unless I've explicitly asked for full results.

### File storage (s3-mcp)
- Use `s3-mcp` only for tasks explicitly involving file uploads or downloads.
- Never list or access files in the `production/` prefix without my approval.
- After any file upload, confirm the URL and file size.

### Error handling for MCP calls
- If an MCP tool call fails, report the error message before attempting a retry or alternative approach.
- Do not silently fall back to a different tool if the primary MCP call fails — ask how to proceed.

Example: rules for a project using GitHub MCP

## GitHub MCP rules
- Use `github-mcp` when I ask about issues, pull requests, or repository metadata.
- When creating issues via MCP, always include: title, description, and at least one label.
- Never close or delete issues via MCP without confirmation.
- For PRs: always check existing open PRs for conflicts before creating a new one.

10. Rule Anti-Patterns: What Not to Write

Poorly written rules are often worse than no rules — they consume token budget without improving Cline's behaviour, or they create conflicts that lead to unpredictable results.

Anti-pattern	Example	Problem	Better alternative
Vague instruction	"Write clean code."	Cline cannot operationalise "clean" — it will follow this rule in name only	"Functions must not exceed 40 lines. Max 3 levels of nesting."
Restating the obvious	"Use good variable names."	Cline already follows standard naming conventions	Remove it — wastes token budget
Business logic in rules	"If the user is on a free plan, do not show the export button."	Rules are not the right place for application logic	Put this in code, not in `.clinerules`
One-time instruction	"Today, rename all `btn` classes to `button`."	`.clinerules` persists across all future tasks	Give this as an in-task instruction instead
Contradictory rules	"Always write tests." + "Only write tests when asked."	Cline cannot resolve this ambiguity deterministically	Pick one and remove the other
Overly long explanation	"The reason we use Zustand instead of Redux is that in 2022 our team decided..."	Backstory is noise — Cline needs the decision, not the history	"Use Zustand for state management. Do not introduce Redux."
Scope-incorrect rules	Putting personal preferences ("Use British English") in a team `.clinerules`	These will affect all contributors' Cline sessions	Put personal preferences in global Custom Instructions
Negative-only rules	"Don't use class components. Don't use Redux. Don't use CSS Modules."	Cline needs to know what to do, not just what to avoid	"Use functional components, Zustand, and Tailwind CSS."
Instruction that belongs in code	"Always validate email with this regex: `/^[^\s@]+@[^\s@]+\.[^\s@]+$/`"	This creates a maintenance problem — the regex lives in two places	Put validation logic in a shared utility; reference it in rules
Ambiguous scope	"Follow the existing patterns."	Which patterns? Existing code may be inconsistent	Reference a specific file: "Follow the pattern in `src/services/userService.ts`."

11. Token Budget and Rule Length

Every character in your .clinerules file is included in every Cline request. Longer rules consume more of the context window, which reduces how much space is left for code, conversation, and task context.

Practical guidelines by rule file size

Rule file size	Effect	Recommendation
< 50 lines (~500 words)	Minimal context impact	Fine for any project
50–150 lines (~500–1500 words)	Noticeable but acceptable	Review for redundancy before adding more
150–300 lines (~1500–3000 words)	Significant context consumption	Split into `.clinerules/` directory; prioritise rules
> 300 lines (~3000+ words)	Risk of rule truncation or reduced attention	Refactor aggressively; extract to Cline Docs

How to reduce rule file size without losing coverage

Merge related rules: Instead of 5 separate bullet points about the same topic, write one concise rule that covers all of them.
Reference files instead of repeating patterns: "Follow the structure of src/services/userService.ts" is shorter than reproducing that structure in the rules file.
Delete rules for things Cline does correctly by default: Test this by removing the rule and running a task. If Cline's behaviour doesn't change, the rule wasn't needed.
Move task-specific context to @ mentions: If a rule only applies when working on a specific module, reference that module's file in-task rather than encoding it in global rules.

12. Troubleshooting: Why Your Rules Aren't Working

When Cline doesn't follow your rules, it's almost always one of five causes. Work through this checklist in order.

Step 1: Confirm Cline is reading the file

Open a Cline task and ask: "What rules are you currently following from the .clinerules file?"

Cline will either quote your rules back (confirming it read the file) or indicate it found nothing. If it found nothing:

Confirm the file is named exactly .clinerules (no extension, starts with a dot)
Confirm it is in the project root, not a subdirectory
Reload VS Code (Ctrl+Shift+P → "Developer: Reload Window")

Step 2: Check rule specificity

Vague rules are ignored in practice even when they're technically being read. Run a minimal test:

Pick one rule from your file
Give Cline a small task where that rule clearly applies
Check if the output follows the rule

If it doesn't, the rule is too vague. Make it more specific and retry.

Step 3: Check for conflicting rules

If you have both workspace rules and global Custom Instructions, check for contradictions. A conflict between them will produce inconsistent behaviour — Cline may follow different rules on different tasks depending on which one it weights more heavily.

Resolve by making the workspace rule more explicit: if the workspace rule says "use Zustand" and the global rule says "minimise external dependencies", add a clarification: "Use Zustand for state management — this is the approved state library for this project."

Step 4: Check rule position in the file

Rules near the top of the file receive more attention than rules at the bottom, especially in long files. Move your most critical rules to the top. Use a ## Critical rules or ## Always apply section at the very beginning of the file for rules that must never be violated.

Step 5: Check token budget

If your rules file is very long (> 200 lines), Cline may not be giving adequate attention to rules in the middle or bottom sections. Symptoms: rules at the top are followed consistently, rules at the bottom are frequently ignored.

Fix: cut the file down by removing redundant, obvious, or low-value rules. Target < 150 lines for optimal rule adherence.

Common issues and fixes

Symptom	Likely cause	Fix
Cline follows rules in short tasks but not long ones	Context window pressure — rules are de-prioritised as conversation grows	Move critical rules to the top; reduce rule file size
Cline follows rules on new files but not on edits	Rule is written in terms of creation, not modification	Rewrite: "All components, new and existing, must use named exports."
Rules work in Act mode but not Plan mode	Rule is phrased as an action (execution) rather than a constraint (planning)	Rewrite the rule to apply to both: "Always plan with named exports in mind."
Cline ignores a rule after a few turns	In-task conversation has introduced conflicting instructions	Remind Cline explicitly: "Continue following the .clinerules file."
A specific rule is ignored consistently	Rule is ambiguous or conflicts with Cline's defaults	Test the rule in a new empty task; rewrite with a concrete example in the rule itself

13. FAQ

Where exactly should I put my .clinerules file?

In your project root — the same directory as your package.json, pyproject.toml, go.mod, or equivalent. Cline looks for .clinerules starting at the workspace root as detected by VS Code.

Do Cline rules apply in Plan mode?

Yes. Rules apply in both Plan and Act mode. In Plan mode, rules influence how Cline decomposes tasks and what it includes in its proposed steps. In Act mode, rules govern the actual code and commands produced.

Can I have multiple .clinerules files in one project?

Not multiple .clinerules files at the root — only one is supported there. But you can use a .clinerules/ directory with multiple .md files inside. Cline loads and merges all of them.

What's the maximum size of a .clinerules file?

There is no hard limit, but practical performance degrades beyond ~300 lines. Rules consume context window space in every task. Keep your rules file under 150 lines for reliable rule adherence. If you need more, split into a .clinerules/ directory and keep each file focused on one topic.

Do workspace rules override my global Custom Instructions?

Yes. Workspace rules (.clinerules) take priority over global Custom Instructions when they conflict. Global instructions are your personal defaults; workspace rules are project-specific and are more specific, so they win.

Should I commit .clinerules to git?

Yes, in almost all cases. The .clinerules file is project infrastructure — like .eslintrc or tsconfig.json. Committing it means every contributor's Cline sessions follow the same standards. If it contains personal preferences, those belong in your global Custom Instructions instead.

Can I write rules in a language other than English?

Yes. Cline understands rules written in any language the underlying model supports. That said, English tends to produce the most consistent instruction-following because model training data is predominantly English for technical content.

How do I override a rule for a single task without editing the file?

Give the override directly in your task prompt: "For this task only, use class components instead of functional components." In-task instructions take precedence over rules for that single conversation.

Do rules work the same way with all models (Claude, GPT-4, etc.)?

Rules are injected into the system prompt regardless of which model backs Cline. However, instruction-following quality varies by model. Claude models (especially Sonnet and Opus) tend to follow detailed rules more reliably than smaller or less capable models.

How do I know if a rule is actually improving Cline's output?

Test empirically: remove the rule, run the same type of task, compare the output. If the output is identical, the rule wasn't doing anything. If the output changes for the worse, the rule was useful. This also helps identify rules that are truly load-bearing vs. rules that just make you feel safer.

Windsurf Rules Guide — Cascade AI rules configuration
GitHub Copilot Instructions — .github/copilot-instructions.md setup
Cline on cursor-alternatives.com — Cline overview and comparison

Cline Rules: Autonomous Coding Agent Best Practices (2026)

Cline Rules: Complete .clinerules Guide with Templates (2026)