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

Last updated: August 2026 · Covers Cline 3.13+

---

Cline Rules are project-level instructions stored in a .clinerules file (or directory) 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 current rules format (including YAML frontmatter for conditional, glob-scoped rules — new since early 2026), workspace vs. global scope, Checkpoints, MCP Marketplace integration, ready-to-use templates, and a debugging workflow for rules that aren't working.

---

1. What Are Cline Rules and How Do They Work

Cline Rules are instructions injected into the system prompt of every conversation Cline has within a project. Every time you give Cline a task, the rules are included automatically. Cline reads them before generating any response or taking any action.

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 handles 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 (set separately per-provider); anything outside the project scope.

---

2. File Format: Plain Markdown or Conditional (YAML Frontmatter)

Cline supports two ways to write rules, and which one you need depends on project size.

Plain markdown (still fully supported)

For most projects, a plain Markdown file with no special syntax works fine — clear, imperative instructions Cline reads in full on every task:

# Project Rules

## Language and environment
- TypeScript strict mode throughout the project.
- Node.js 20+. Use ES modules (`import`), not CommonJS (`require()`).

## Code style
- Functional components only. No class components.
- Named exports for all components and utilities.

Conditional rules with YAML frontmatter (current, for larger projects)

Individual files inside .clinerules/ (or the newer .cline/rules/ directory — see below) can carry YAML frontmatter that scopes a rule to specific paths, so you don't pay the token cost of loading rules that don't apply to the current task:

---
description: API layer conventions
globs: "src/api/**/*.ts"
alwaysApply: false
---

- All handlers validate input with Zod before processing.
- Return typed responses — never raw objects.

This lets you apply different behavior to src/api/ vs. src/ui/ without manually managing which rules are relevant — Cline auto-attaches the rule when a matching file is in context, the same underlying pattern used by Cursor's .mdc and Continue.dev's globs. Not every project needs this — a small project is fine with one flat file — but for a codebase with genuinely distinct zones (API vs. UI vs. shared packages), scoped rules keep each part of the codebase getting relevant guidance without loading everything else too.

---

3. File Locations: Legacy, Current, and Global

Cline maintains backward compatibility with .clinerules and .clinerules/ — nothing breaks if that's what you already have. For new projects, .cline/rules/ is the structure Cline's own documentation now points to first, and it's where frontmatter-based conditional rules are most naturally organized.

my-project/
├── .cline/
│   └── rules/
│       ├── general.md
│       ├── api.md        ← can carry frontmatter for path-scoping
│       └── testing.md

Toggleable rules

Since v3.13, Cline's UI includes a Rules tab where you can enable or disable individual rule files with a toggle, without deleting them — useful for temporarily turning off a rule set (a strict security-review rule during rapid prototyping, for instance) without losing the file.

---

4. Workspace Rules vs. Global Rules

When a workspace rule and a global rule contradict, the workspace rule wins — project context is more specific and should take precedence.

What to put in global rules:

## General behaviour
- Always show a brief implementation plan before writing code.
- Never delete files without asking for confirmation first.
- Keep explanations concise. Skip preamble — get to the answer.

What to put in workspace rules:

## Stack
- Frontend: Next.js 14 App Router. Backend: FastAPI. Database: PostgreSQL via Prisma.
- State management: Zustand only. Do not introduce Redux or Context API.

For the broader distinction between this kind of persistent agent-behavior configuration and one-off task instructions, see System Prompts for AI Coding Agents and How to Prompt AI Coding Agents.

---

5. Checkpoints: Session-Level Rollback

Checkpoints are a Cline-specific safety mechanism worth understanding alongside rules, since they change how cautiously you need to write execution rules.

Cline creates a snapshot (via a shadow git repository, invisible to your normal git history) at each step and tool call during a task. This lets you compare changes, restore to any previous point in the session, or experiment freely — not just undo the very last action, but roll back several steps if a task went in the wrong direction partway through.

Checkpoints vs. git: treat them as two complementary undo systems. Checkpoints handle "step back two actions within this task." Your normal git workflow handles "throw out the whole branch." Committing frequently or branching before a significant Cline session remains good practice — checkpoints are a session-level safety net, not a replacement for version control discipline.

Limitation: checkpoints are disabled in multi-root VS Code workspaces (Cline displays a warning when this happens), since coordinating shadow-git state across multiple independent repositories isn't yet supported. Rules in a multi-root workspace also only apply from the primary (first) workspace folder — put shared rules there, or in global rules, if you work this way.

This safety net is part of why Cline's approval-gated design is well suited to cautious work — see Best AI Coding Tools for Legacy Codebases for how Checkpoints plus Plan/Act combine for working on undocumented or sparsely tested code.

---

6. Cline Rules vs. Other Context Mechanisms

---

7. Ready-to-Use .clinerules Templates

These are production-ready starting points using plain markdown (add frontmatter and split into .cline/rules/ if your project needs path-scoping).

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.
- 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.
- API routes go in `app/api/[resource]/route.ts`.
- Business logic and data access go in `src/services/` — never in components directly.

## Component rules
- Functional components only. Named exports for all components.
- No `any` type. Use `unknown` and narrow it.

## Data access rules
- All Prisma queries go through service functions in `src/services/`.
- Service functions return `{ data: T } | { error: string }`.

## Task behaviour
- Run `npm run build` after major changes to catch type errors.
- 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+. Type hints everywhere.
- Web framework: FastAPI. ORM: SQLAlchemy 2.0 with async sessions.
- Package manager: Poetry. Testing: pytest + pytest-asyncio.

## Project structure
- API routes in `app/routers/`. Business logic in `app/services/`.
- Database models in `app/models/`. Pydantic schemas in `app/schemas/`.
- DB queries in `app/repositories/` — no direct ORM queries in services.

## Code style
- `async def` for all route handlers and service functions.
- Pydantic models for all request/response bodies — never return raw dicts.

## Task behaviour
- When adding a new endpoint, create or update the Pydantic schema first.
- After adding a model, generate a migration with `alembic revision --autogenerate`.
- Run `pytest` after implementation and show me the output.

---

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

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

## Environment
- React 18, TypeScript strict mode, Vite.
- State: Zustand for client state. React Query for server state.
- Styling: Tailwind CSS. No inline styles, no CSS Modules.

## Component conventions
- One component per file. Named exports only.
- No `useEffect` for data fetching — use React Query instead.

## State management
- Zustand stores in `src/stores/`, one store per domain.
- Server state managed by React Query only — do not duplicate in Zustand.

## Task behaviour
- Order: types → service function → React Query hook → component.
- Never add a library without asking first.
- Run `npm run type-check` after completing a task.

---

Template 4: Node.js + Express + TypeScript + PostgreSQL

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

## Environment
- Node.js 20+, TypeScript 5+, Express 4.
- Database: PostgreSQL via `pg`. No ORM — raw SQL with parameterized queries.
- Testing: Jest + Supertest.

## Database rules
- All SQL in `src/db/queries/` — never inline in services.
- Always use parameterized queries. Never concatenate user input into SQL strings.

## API rules
- Error responses: `{ success: false, error: string }`. Never expose stack traces.
- All route handlers wrapped in `asyncHandler()`.

## Task behaviour
- 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.
- Testing: standard `testing` package + `testify`.

## Code conventions
- Errors always returned, never panicked on (except in main.go init).
- `context.Context` as first parameter in all service and repository functions.
- Handlers translate errors to HTTP status codes — services never set status codes.

## Task behaviour
- Order: model → repository → service → handler → route registration.
- Run `go build ./...` and `go vet ./...` after completing a task.

---

8. MCP-Aware Rules and the MCP Marketplace

If your project uses Cline with MCP servers, you can write rules that govern how Cline interacts with those tools — but it's worth knowing what the MCP Marketplace does first, since it changes how you'd typically set this up.

The Marketplace: Cline's MCP Marketplace lets you browse, install, and configure community-built servers with a single click, and group servers into categories with trigger keywords — mentioning "web scraping" or "database" in a task can auto-surface the relevant tool without you specifying it explicitly. Cline can also generate a new MCP server from a natural-language description when nothing existing covers your need. Full setup walkthrough: How to Set Up MCP Servers for AI Coding Agents.

Rules for MCP usage, once servers are connected:

## MCP tool usage

### Database (postgres-mcp)
- Use `postgres-mcp` for schema inspection and query testing.
- Never run DROP or DELETE queries via MCP without showing me the query first.
- For large queries, add LIMIT 100 unless full results are explicitly requested.

### Error handling for MCP calls
- If an MCP tool call fails, report the error before retrying or trying an alternative.
- Do not silently fall back to a different tool without asking how to proceed.

---

9. Rules for Specific Workflows

Refactoring rules

## Refactoring behaviour
- Before refactoring, identify which tests cover the target code.
- Refactor in small steps. Do not combine refactoring with feature changes.
- If no tests exist for the target code, write them before refactoring.

Debugging rules

## Debugging behaviour
- When investigating a bug, first reproduce it with a minimal test case.
- Explain the root cause before proposing a fix.

Large codebase navigation rules

## Codebase navigation
- Before creating a new utility function, search for an existing one first.
- When unsure where a new file belongs, follow the pattern of 2–3 similar files.

For genuinely recurring multi-step processes (not just standing conventions), consider a Workflow (.clinerules/workflows/) instead of a rule — workflows are named, invokable sequences rather than passive context.

---

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

## Planning behaviour (Plan mode)
- If a task requires touching more than 5 files, produce a step-by-step plan and wait for approval.

## Execution behaviour (Act mode)
- Never run npm install <package> without prior approval.
- Always run the test suite after implementation, before marking a task complete.

---

11. Rule Anti-Patterns

---

12. Token Budget and Rule Length

Using frontmatter-scoped rules (Section 2) is now the most effective lever here — a rule that only loads when relevant files are in context costs nothing on unrelated tasks, which a flat always-loaded file cannot achieve.

---

13. Troubleshooting: Why Your Rules Aren't Working

Step 1 — confirm Cline is reading the file. Ask: "What rules are you currently following?" If Cline doesn't quote them back, check the file is in a location Cline actually checks (Section 3), and reload VS Code.

Step 2 — check the Rules tab toggle state. Since v3.13, a rule file can be present but toggled off in the UI. Check the Rules panel to confirm the file you expect to be active actually is.

Step 3 — check rule specificity. Vague rules are technically read but practically ignored — test by giving a small task where a specific rule clearly applies and checking the output.

Step 4 — check frontmatter syntax if using conditional rules. A malformed globs pattern means the rule silently never attaches — verify with a task that touches a file matching the intended pattern.

Step 5 — check for conflicts between workspace and global rules, and check rule position (rules near the top of a file get more attention in long files).

---

14. FAQ

Is .clinerules still supported, or do I need to migrate to .cline/rules/?

.clinerules and .clinerules/ remain fully supported — nothing breaks. .cline/rules/ is the structure Cline's current documentation leads with and where conditional (frontmatter) rules are most naturally organized, but migrating is optional, not urgent, unlike Cursor's .cursorrules → .mdc situation where the legacy format is actually broken in a mode.

Can Cline rules be scoped to specific files, like Cursor's .mdc globs?

Yes, since the addition of YAML frontmatter support — see Section 2. This is a relatively recent addition; older guides (including earlier versions of this one) describe Cline rules as plain, unscoped markdown only.

What are Checkpoints and how do they relate to rules?

Checkpoints are session-level rollback snapshots (via a shadow git repo) taken at each step of a task, independent of your rules configuration — see Section 5. They matter for rules in the sense that they reduce the risk of autonomous execution, which affects how conservatively you need to write execution-behavior rules.

Should I commit .clinerules or .cline/rules/ to git?

Yes, in almost all cases — treat it like .eslintrc. Global rules (~/Documents/Cline/Rules/) are personal and not part of the repo.

Do workspace rules override global rules?

Yes, on conflict. Global rules are personal defaults; workspace rules are project-specific and win.

How does Cline compare to Aider for rules-driven, cautious work?

Both support persistent project rules, but the underlying safety models differ — Cline's Checkpoints plus approval-gated Plan/Act vs. Aider's git-native auto-commit-and-revert. See Cline vs Aider for the full comparison.

---

Related

• How to Set Up MCP Servers for AI Coding Agents — full MCP Marketplace walkthrough
• System Prompts for AI Coding Agents — persistent agent behavior vs. project rules
• How to Prompt AI Coding Agents — individual task prompts and templates
• Cline vs Aider — the two leading free open-source agents compared
• Cursor vs Cline — subscription IDE vs. free agent
• Best AI Coding Tools for Legacy Codebases — Checkpoints and Plan/Act for cautious work on undocumented code
• Cline FAQ — pricing, models, and general questions
• Cursor Rules Guide — .mdc rules configuration
• Windsurf Rules Guide — Cascade AI rules configuration
• GitHub Copilot Rules — .github/copilot-instructions.md setup
• Cline on cursor-alternatives.com — Cline overview and comparison