Cline Rules: The Complete .clinerules Guide for 2026

Cline has become one of the most capable AI coding agents in the VS Code ecosystem — but raw capability without configuration produces generic output. .clinerules is how you close that gap. It is the file (or directory of files) where you tell Cline exactly how to work in your specific project: what stack you use, how you want code formatted, what it should never do, and which rules apply to which parts of the codebase.

This guide covers everything you need: file formats, YAML frontmatter, glob-based conditional rules, global vs. workspace precedence, the toggleable UI added in v3.13, and five copy-pasteable templates for React, Python, Go, TypeScript, and monorepo setups.

What .clinerules Files Are and Why They Matter

When Cline opens a workspace, it looks for .clinerules in the project root and loads whatever it finds into the system prompt context. Every task Cline performs in that session — writing code, answering questions, running terminal commands — is influenced by those rules.

Without .clinerules, Cline behaves based on its default training and whatever you type in the prompt. That works for one-off tasks, but it breaks down across a team or over the lifetime of a project. You end up correcting the same mistakes repeatedly: wrong import style, missing error handling patterns, output in the wrong format.

.clinerules solves this at the source. Rules you write once get applied automatically, session after session, for everyone on the team who uses Cline in that repo.

The practical impact:

• Cline uses your actual naming conventions, not invented ones
• It follows your error handling patterns instead of generic try/catch boilerplate
• It skips proposing changes to directories you have locked down
• Conditional rules let you apply different behavior to src/api/ vs. src/ui/ without manual context switching

Single File vs. .clinerules/ Directory

Cline supports two formats for rules, and which one you use depends on project complexity.

Single File (.clinerules)

The simplest option. Create a single file named .clinerules in your project root and write your rules in Markdown:

# Project Rules

## Stack
- Node.js 20 + TypeScript 5
- React 19 + Vite
- Tailwind CSS v4

## Code Style
- Functional components only. No class components.
- Use named exports. No default exports.
- Prefer `const` assertions for configuration objects.

## Testing
- Vitest for unit tests, Playwright for e2e.
- Test files live next to source files: `foo.ts` and `foo.test.ts`.
- Never skip tests to fix a failing build.

## What Not to Do
- Do not modify `src/generated/`. These files are auto-generated.
- Do not install packages without asking. Explain the tradeoff first.

Single-file format works well for projects up to roughly 50 rules. Beyond that, maintainability suffers and load time creeps up.

Directory Format (.clinerules/)

For larger projects, create a directory named .clinerules/ in the project root and place multiple .md files inside it. Cline loads all of them:

project-root/
├── .clinerules/
│   ├── coding-standards.md
│   ├── architecture.md
│   ├── testing.md
│   ├── api-patterns.md
│   └── security.md
├── src/
└── package.json

Each file in the directory is a standalone rules document. Cline concatenates them in alphabetical order before injecting into context, so naming matters if rule order is important — prefix with numbers (01-stack.md, 02-patterns.md) to control sequence.

Directory format also enables conditional rules via YAML frontmatter, which is where the real power lies.

YAML Frontmatter and Conditional Rules

This is the feature most Cline users miss. Individual rule files inside .clinerules/ can include YAML frontmatter that controls when those rules are activated.

The most useful frontmatter field is paths — a glob pattern (or array of patterns) that limits a rule file to specific parts of the codebase.

Basic Conditional Syntax

---
paths:
  - "src/api/**"
  - "src/services/**"
---

# API Layer Rules

All functions in this layer must return a `Result<T, Error>` type, never throw directly.
Validation happens at the boundary — internal functions can assume data is valid.
Use camelCase for JSON request/response fields regardless of database column naming.

When Cline is working on a file that matches src/api/** or src/services/**, this rule file is active. When it is working on src/components/Button.tsx, these API rules are not loaded — keeping the context focused.

Frontmatter Fields

A fully annotated example:

---
description: "Database and ORM conventions"
paths:
  - "src/db/**"
  - "src/models/**"
  - "migrations/**"
alwaysApply: false
---

# Database Rules

- Use Prisma for all database access. Raw SQL only in `src/db/queries/` with explicit comment justification.
- Never call `prisma.$executeRaw()` in feature code.
- Migration files are append-only. Never edit an existing migration.
- Model names are PascalCase singular: `User`, not `Users` or `user`.

Path Glob Patterns

Cline uses standard minimatch-style glob syntax:

src/api/**          # All files under src/api/ recursively
**/*.test.ts        # All TypeScript test files anywhere in the project
src/{components,pages}/**  # src/components/ and src/pages/
!src/generated/**   # Exclusion (use sparingly — behavior varies by version)

Global vs. Workspace Rules Precedence

Cline has two rule locations, and understanding their relationship matters when you work across multiple projects.

Global Rules

Stored in ~/.cline/rules/ on your machine. These apply to every workspace you open in Cline. Use global rules for personal preferences that transcend any single project:

# ~/.cline/rules/personal.md

## My Preferences
- Always explain what a change does before writing code.
- When I ask you to refactor, show a before/after diff in a code block first.
- Prefer explicit over clever. I will ask for the clever version if I want it.
- When generating commit messages, follow Conventional Commits format.

Workspace Rules

Stored in .clinerules or .clinerules/ at the project root. These are project-specific and should be committed to version control so the whole team benefits.

Workspace rules take precedence over global rules when they conflict. If your global rules say “always use 2-space indentation” but the workspace .clinerules says “use 4-space indentation”, Cline follows the workspace rule.

This makes sense: the project’s conventions should win over personal defaults. It also means you can commit a .clinerules that overrides team member defaults without requiring them to change their global setup.

Recommended Split

The Toggleable Rules UI (v3.13+)

Cline v3.13 added a rules management panel accessible from the Cline sidebar in VS Code. It lists all active rule files — both global and workspace — with toggle switches next to each.

This is useful for:

Debugging rules: if Cline is behaving unexpectedly, you can disable rules one at a time to identify which one is causing the issue.

Context switching: working on a security audit? Toggle on strict security rules temporarily without permanently restructuring your .clinerules/ directory.

Onboarding: new team members can see exactly which rules are active and why, rather than hunting through repo configuration.

The description frontmatter field populates the label shown next to each toggle. Without it, Cline uses the filename — which is fine, but a clear description is worth writing.

Rules toggled off in the UI do not persist between VS Code sessions. If you want a rule permanently disabled for a project, remove it from the directory or add a comment noting it is inactive.

5 Copy-Pasteable Templates

1. React + TypeScript Project

---
description: "React + TypeScript conventions"
alwaysApply: true
---

# React + TypeScript Rules

## Stack
- React 19, TypeScript 5.5+, Vite 6
- Tailwind CSS v4 for styling. No CSS modules, no styled-components.

## Components
- Functional components only. No class components.
- Props interfaces use PascalCase: `ButtonProps`, not `IButtonProps`.
- Named exports only. `export function Button()`, never `export default Button`.
- One component per file. File name matches component name.

## Hooks
- Custom hooks live in `src/hooks/`. File name: `use-feature-name.ts`.
- Never call hooks conditionally.

## State
- Local state with `useState`. Server state with React Query (TanStack Query v5).
- Avoid Redux unless the requirement explicitly calls for it.

## TypeScript
- Strict mode enabled. No `any`. Use `unknown` when type is truly unknown.
- Prefer type aliases over interfaces for object shapes.
- All async functions return explicit `Promise<T>` types.

## Testing
- Vitest + React Testing Library. Co-located test files: `Button.test.tsx`.
- Test behavior, not implementation. No snapshot tests.

2. Python Project

---
description: "Python project conventions"
alwaysApply: true
---

# Python Rules

## Stack
- Python 3.12+. Use `from __future__ import annotations` for forward references.
- Dependency management via `uv`. `requirements.txt` is auto-generated.
- Formatting: `ruff format`. Linting: `ruff check`. Type checking: `mypy --strict`.

## Code Style
- Type hints on all function signatures, including return types.
- Prefer dataclasses or Pydantic models over raw dicts for structured data.
- Use `pathlib.Path` everywhere. Never concatenate paths as strings.
- f-strings only. No `.format()` or `%` formatting.

## Error Handling
- Raise specific exceptions. Never `raise Exception("message")`.
- Custom exceptions live in `src/exceptions.py`.
- Context managers for all resource acquisition (files, connections, locks).

## Testing
- pytest with `pytest-asyncio` for async tests.
- Test files in `tests/` directory, mirroring `src/` structure.
- Fixtures in `conftest.py`. Avoid module-level setup.

## What Not to Touch
- `src/generated/` is auto-generated. Never edit directly.
- Do not modify `pyproject.toml` without explaining the dependency tradeoff.

3. Go Project

---
description: "Go project conventions"
alwaysApply: true
---

# Go Rules

## Stack
- Go 1.22+. Module path from `go.mod` is the import base.
- Standard library first. Justify every third-party dependency.

## Code Style
- Follow effective Go: https://go.dev/doc/effective_go
- Error strings are lowercase and do not end with punctuation.
- Named return values only when they aid documentation. Never for brevity.
- Use `context.Context` as the first parameter in functions that perform I/O.

## Error Handling
- Errors are values. Handle every error explicitly. Never `_ = someFunc()`.
- Wrap errors with `fmt.Errorf("doing X: %w", err)` to preserve the chain.
- Sentinel errors in package-level `var`: `var ErrNotFound = errors.New("not found")`.

## Interfaces
- Define interfaces at the point of use, not at the point of implementation.
- Keep interfaces small. One or two methods is ideal.

## Testing
- Table-driven tests. Test file: `foo_test.go` in the same package.
- Use `t.Helper()` in test utility functions.
- Integration tests in `tests/integration/` with `//go:build integration` build tag.

## Project Structure
- Do not add files to `internal/generated/`. Auto-generated by `make generate`.

4. TypeScript Node.js Backend

---
description: "TypeScript Node.js backend conventions"
alwaysApply: true
---

# TypeScript Backend Rules

## Stack
- Node.js 20 LTS, TypeScript 5.5+
- Fastify v5 for HTTP. Prisma for ORM.
- Zod for runtime validation at all API boundaries.

## Architecture
- Layer order: routes → handlers → services → repositories → database.
- No database calls in handlers. No business logic in repositories.
- Services are pure functions where possible. Inject dependencies; avoid singletons.

## TypeScript
- `strict: true` in tsconfig. No `any`. No type assertions (`as T`) without comment.
- Avoid enums. Use `const` objects with `as const` instead.
- Barrel exports (`index.ts`) only at layer boundaries, not inside layers.

## API Design
- RESTful. Resource URLs in plural nouns: `/users`, `/orders`.
- All request bodies validated with Zod before handler logic.
- Errors return `{ code: string, message: string }`. HTTP status codes follow RFC 9110.

## Async
- All I/O is async/await. No callbacks. No `.then()` chains.
- Never `await` inside a loop. Use `Promise.all()` for parallel work.

## Environment
- Config via environment variables only. No hard-coded values.
- Access env vars through a validated config module, not `process.env.X` directly.

5. Monorepo Setup

---
description: "Monorepo root — always applied"
alwaysApply: true
---

# Monorepo Root Rules

## Structure
- `apps/` — deployable applications (web, api, worker)
- `packages/` — shared libraries (ui, utils, types, config)
- `tools/` — build scripts, codegen, dev tooling

## Package Manager
- pnpm workspaces. Never use `npm install` or `yarn` in this repo.
- Add dependencies to the specific workspace: `pnpm --filter @acme/web add react`.
- Shared dev dependencies go in root `package.json`.

## Shared Packages
- `@acme/types` — TypeScript types shared across apps. No runtime code.
- `@acme/ui` — React component library. Import from here, never duplicate components.
- Never import from `apps/*` inside `packages/*`. Direction: packages → apps only.

## Cross-Package Changes
- If a change touches more than one package, describe the dependency direction.
- Do not introduce circular dependencies between packages.

## Build
- `turbo build` from root to build everything in dependency order.
- Individual packages: `pnpm --filter @acme/api build`.
- Never run `tsc` directly at root level.

---
description: "API app — active when editing apps/api/**"
paths:
  - "apps/api/**"
---

# API App Rules

See root rules for monorepo structure. Additional rules for the API app:

- Hono v4 for routing. Handlers in `apps/api/src/routes/`.
- All database access through `packages/db` — never import Prisma client directly.
- Authentication middleware applied at router level, not per-handler.

Migrating from Other Formats

From .cursorrules

If you have a .cursorrules file, the structure translates directly. The content is already Markdown-compatible rules prose, so the migration is straightforward:

1. Create .clinerules at the project root
2. Copy the content from .cursorrules
3. Adjust any Cursor-specific instructions (like @-mentions or special Cursor commands) to plain English

One difference worth noting: .cursorrules does not support YAML frontmatter or glob-based conditional rules. If your .cursorrules file has sections for different parts of the codebase separated by comments, this is a good opportunity to split them into a .clinerules/ directory with proper paths frontmatter.

From CLAUDE.md

CLAUDE.md is Claude Code’s equivalent of .clinerules. The content semantics are nearly identical — both are instruction sets for an AI coding agent. The main differences:

• CLAUDE.md supports a ! prefix to ignore content from that line forward (Cline does not)
• CLAUDE.md has a scope hierarchy (project, sub-directory, home directory) baked in; Cline uses the paths frontmatter field instead
• Some Claude Code-specific directives (STOP_WORDS, permission blocks) have no Cline equivalent and can be removed

The practical migration path: copy CLAUDE.md to .clinerules, remove Claude Code-specific directives, and optionally split into a directory structure if the file is long.

For projects where developers use both Cline and Claude Code, maintaining both files is common and reasonable — they serve the same purpose for different tools, and the content overlaps significantly.

Common Mistakes

Putting everything in one massive file. Large context blocks get deprioritized by the model when later parts of the prompt compete for attention. If your rules are over 2,000 words, split them into a directory and use conditional loading.

Writing vague prohibitions. “Don’t write bad code” does nothing. “Do not use any type. When a type is unknown at compile time, use unknown and narrow it with a type guard” is actionable.

Missing the alwaysApply field in directory mode. When you use the .clinerules/ directory, files with paths frontmatter only load when the active file matches those paths. If you want certain rules to always load (stack overview, global conventions), either set alwaysApply: true or put them in a file without any frontmatter at all.

Not committing .clinerules/ to version control. These files are project configuration. They belong in git alongside tsconfig.json and .eslintrc. The whole team benefits from consistent Cline behavior, and rule changes should go through the same review process as code changes.

Overlapping global and workspace rules without knowing which wins. Workspace always wins. If you have contradictory rules and Cline is behaving unexpectedly, check both ~/.cline/rules/ and the project .clinerules/ to find the conflict.

Ignoring the toggleable UI for debugging. When Cline does something you did not expect, the rules panel in v3.13+ is the first place to look. Toggle rules off one by one to find the source rather than reading through all your rule files trying to spot the conflict.

.clinerules rewards the time you put into it. A well-structured rules setup means less correction, more predictable output, and Cline that actually understands your project — not just generic code patterns. Start with the template closest to your stack, trim what does not apply, and expand from there as you discover what you need to say explicitly.