Cline AGENTS.md & .clinerules Integration Guide (2026)

Cline natively reads four rule file formats: .clinerules/, AGENTS.md, .cursorrules, and .windsurfrules. Most guides focus on just one of these — this one explains how all four fit together and when to use each.

If your team already uses AGENTS.md for OpenAI Codex, GitHub Copilot, or other agents, you do not need to rewrite anything. Cline picks it up automatically. If you want Cline-specific behavior, .clinerules/ gives you more control.

How Cline Reads Rule Files

When you open a project in Cline, it scans for rule files in this order:

1. .clinerules/ — directory of markdown/txt files, processed and merged
2. AGENTS.md — project-root file, cross-tool standard
3. .cursorrules — Cursor’s rule format, auto-detected
4. .windsurfrules — Windsurf’s rule format, auto-detected
5. Global Cline rules — stored in ~/Documents/Cline/Rules (macOS/Linux)
6. ~/.agents/AGENTS.md — global cross-tool rules for all agents

All detected files appear in the Cline Rules panel (sidebar) with individual toggles. You can enable or disable any rule file per session without editing files.

.clinerules vs AGENTS.md: Which to Use

Rule of thumb: Start with AGENTS.md for project standards that all AI tools should follow. Add .clinerules/ for anything Cline-specific — conditional activation, sidebar-managed toggles, or behavior that other tools shouldn’t inherit.

You can use both in the same project. Cline merges them.

Setting Up .clinerules/

Basic Structure

your-project/
├── .clinerules/
│   ├── 01-coding-standards.md
│   ├── 02-testing.md
│   ├── 03-git-workflow.md
│   └── 04-architecture.md
├── AGENTS.md
├── package.json
└── src/

The numeric prefix (01-, 02-) controls the order Cline processes files. Without prefixes, files load alphabetically.

Example: 01-coding-standards.md

# Coding Standards

## TypeScript
- Use `type` over `interface` for object shapes
- Prefer `const` assertions for readonly values
- Avoid `any`; use `unknown` with type guards

## File naming
- Components: PascalCase (`UserCard.tsx`)
- Utilities: camelCase (`formatDate.ts`)
- Constants: SCREAMING_SNAKE_CASE (`MAX_RETRIES`)

## Imports
- Group: external → internal → relative
- No default exports from utility files

Example: 02-testing.md

# Testing Requirements

- Every new function needs a unit test
- Integration tests go in `__tests__/integration/`
- Use `vi.mock()` not `jest.mock()` — this project uses Vitest
- Snapshot tests are banned; use explicit assertions
- Run `pnpm test:affected` before committing, not the full suite

Global Rules (apply across all projects)

Place files in ~/Documents/Cline/Rules/ (macOS) for rules that apply everywhere:

~/Documents/Cline/Rules/
├── global-preferences.md
└── security.md

Setting Up AGENTS.md for Cline

If you already have an AGENTS.md for other tools, Cline reads it without any extra configuration. If you’re creating one specifically with Cline in mind, include sections that matter across all AI tools.

Recommended AGENTS.md Structure

# AGENTS.md

## Project Overview
This is a Next.js 15 application with a PostgreSQL backend (Drizzle ORM).
Deployments go to Vercel. The main branch is `main`.

## Core Rules

### Never modify
- `src/lib/auth/` — authentication logic, security-reviewed
- `drizzle.config.ts` — database schema config

### Always do
- Run `pnpm typecheck` after any TypeScript changes
- Update `CHANGELOG.md` for user-facing changes
- Check `src/types/` before defining new types

## Code Style
- Tabs, not spaces
- Trailing commas in multiline expressions
- Prettier config is in `.prettierrc` — do not override inline

## Testing
- `pnpm test` runs Vitest
- `pnpm e2e` runs Playwright tests (requires a running dev server)
- Never skip tests on PRs to `main`

## Commands
- Dev: `pnpm dev`
- Build: `pnpm build`
- Type check: `pnpm typecheck`
- Lint: `pnpm lint`

Cline reads this alongside .clinerules/. If the same instruction appears in both, .clinerules/ takes precedence.

Conditional Rules (Cline-Only Feature)

Conditional rules are the main reason to use .clinerules/ over a flat AGENTS.md. They activate only when Cline is working with files matching your glob patterns.

Syntax

---
paths:
  - "src/components/**"
  - "*.stories.tsx"
---

# Component Rules

- Use Storybook stories for all new UI components
- Follow the Atomic Design hierarchy (atoms → molecules → organisms)
- Props must be documented with JSDoc
- No logic in presentational components — extract to hooks

This rule only applies when Cline edits component or story files. It does not consume context tokens on backend tasks.

Practical Patterns

Database-specific rules:

---
paths:
  - "src/db/**"
  - "drizzle/**"
  - "migrations/**"
---

# Database Rules

- Never drop columns in migrations, mark as deprecated
- All new tables need `created_at` and `updated_at` timestamps
- Foreign keys must have explicit ON DELETE behavior

API route rules:

---
paths:
  - "src/app/api/**"
  - "src/pages/api/**"
---

# API Rules

- Validate all inputs with Zod before processing
- Return errors as `{ error: string; code: string }`
- Log requests with correlation IDs
- No business logic in route handlers — use service layer

Test file rules:

---
paths:
  - "**/*.test.ts"
  - "**/*.spec.ts"
  - "__tests__/**"
---

# Test Rules

- Describe blocks mirror the module structure
- Each test file imports only what it tests
- Factory functions over manual object construction
- Use `expect.assertions(n)` in async tests

Global Cross-Tool Rules with ~/.agents/AGENTS.md

For rules that should apply to every project across all AI tools (Cline, Codex, Copilot, etc.), create a global AGENTS.md:

mkdir -p ~/.agents
nano ~/.agents/AGENTS.md

# Global Agent Rules

## Security
- Never hardcode API keys, tokens, or credentials
- Do not commit `.env` files
- Flag if asked to generate auth bypass code

## Communication
- Explain what you're about to change before making changes
- List affected files when making cross-cutting changes
- Ask before deleting files

## Git
- Commit messages follow Conventional Commits (feat/fix/chore/docs)
- No `--force` pushes without explicit instruction

Cline reads ~/.agents/AGENTS.md for every project. Project-level files override it when there’s a conflict.

Integration Pattern for Teams

For teams already using multiple AI tools, this layout lets every tool read its relevant rules:

your-project/
├── AGENTS.md                    # All AI tools: project standards
├── .clinerules/
│   ├── 01-standards.md          # Cline: general (mirrors AGENTS.md key points)
│   ├── 02-components.md         # Cline: conditional, src/components/**
│   └── 03-database.md           # Cline: conditional, src/db/**
├── .cursorrules                 # Cursor: kept minimal, links to AGENTS.md
├── .github/
│   └── copilot-instructions.md  # Copilot: workspace instructions
└── src/

We analyzed 200+ projects in our gallery that use this pattern. The most common approach is to keep AGENTS.md as the authoritative source and use .clinerules/ only for conditional rules and Cline-sidebar toggles.

FAQ

Does Cline read AGENTS.md automatically? Yes. Since Cline v3, AGENTS.md at the project root is read automatically alongside .clinerules/. No configuration needed.

What happens when .clinerules/ and AGENTS.md conflict? .clinerules/ takes precedence. Cline processes workspace rules first, then cross-tool files.

Can I use .clinerules as a single file instead of a directory? Yes. A single .clinerules file (no directory) still works. The directory form is preferred for larger projects because you can toggle individual files in the sidebar.

Do .clinerules support comments? Rules are plain markdown, so there’s no comment syntax. Add context inline as regular text — Cline treats everything as instruction.

What’s the token cost of loading multiple rule files? Each rule file consumes tokens in every request. We’ve found 3–5 focused files under 150 lines each outperform one monolithic 600-line file. Conditional rules help because they only load when the file patterns match.

Can I symlink AGENTS.md to .clinerules/? Yes, but not recommended. Cline reads both files independently, so symlinking creates duplicate instructions. Keep them separate with distinct purposes.

Quick Reference

# Project rule files Cline reads automatically
.clinerules/          # Cline-specific, conditional rules, team toggles
AGENTS.md             # Cross-tool project standards
.cursorrules          # Cursor compat (Cline reads this too)
.windsurfrules        # Windsurf compat (Cline reads this too)

# Global rule files
~/Documents/Cline/Rules/     # Global Cline rules (macOS/Linux)
~/.agents/AGENTS.md          # Global cross-tool rules

See the Cline community’s clinerules repository for 100+ real-world .clinerules examples, including rules for React, FastAPI, Ruby on Rails, and more.

For cross-tool rule file examples, browse our gallery where we track 500+ AGENTS.md and CLAUDE.md files from open-source projects.