Roo Code Rules Guide: Custom Modes, .roo/rules/, and Mode-Specific Instructions (2026)

Roo Code took Cline’s foundation and built something meaningfully different on top of it. The most important addition: a mode system that lets you switch between specialized AI personas — each with its own tool access, file restrictions, and instruction set — without leaving your editor. If you have been using .clinerules and wondering how Roo Code’s rule system compares, this guide covers the full picture: the .roo/rules/ directory structure, how custom modes work, how to write mode-specific rules, and a complete project setup you can adapt.

What Is Roo Code (and How It Differs from Cline)

Roo Code is a fork of Cline, the open-source VS Code AI coding agent. It shares the same core loop — reading files, running commands, editing code — but adds several features that Cline lacks.

The most significant difference for rule authors:

• Custom modes with per-mode tool permissions and file access restrictions
• Mode-specific rule directories (.roo/rules-{modeSlug}/) that load alongside global rules
• Orchestrator mode for decomposing complex tasks into isolated subtasks across modes
• AGENTS.md support built in alongside .roorules
• Sticky models — each mode remembers the last model you used

The rule file hierarchy is also more granular than Cline’s. Where Cline has .clinerules plus a .clinerules/ directory, Roo Code separates workspace-wide rules from mode-specific rules at the directory level, which matters when you have meaningfully different requirements for coding vs. documentation vs. debugging sessions.

Rule File Locations

Roo Code supports two scopes: global (applies across all projects) and workspace (project-specific). Both scopes support the same directory structure.

Global Rules

Rules stored here apply to every project you open:

Global rules are useful for personal standards you want everywhere: preferred language, output formatting, things you never want any AI to do across all your projects.

Workspace Rules (Project-Specific)

Project-level rules live inside the repo and should be committed to version control. The preferred structure:

.roo/
├── rules/                    # Applies to all modes in this workspace
│   ├── 01-project-context.md
│   ├── 02-coding-style.md
│   └── 03-constraints.md
├── rules-architect/          # Loaded only when in Architect mode
│   ├── 01-design-principles.md
│   └── 02-adr-format.md
├── rules-code/               # Loaded only when in Code mode
│   ├── 01-implementation-rules.md
│   └── 02-test-requirements.md
└── rules-debug/              # Loaded only when in Debug mode
    └── 01-investigation-protocol.md

Fallback single-file format:

• .roorules — workspace-wide fallback
• .roorules-{modeSlug} — mode-specific fallback

The directory method is preferred. Files are loaded recursively in alphabetical order (sorted by basename, case-insensitive). Symbolic links are supported up to 5 levels deep.

Files Roo Code Ignores

Roo Code silently skips temporary and system files: .DS_Store, *.bak, *.cache, *.log, *.tmp, Thumbs.db. You do not need to exclude these manually.

How Rule Priority Works

When Roo Code builds the instruction context for a session, it layers rules in this order (later entries take precedence over earlier ones):

1. Global instructions (Prompts tab — “Custom Instructions for All Modes”)
2. Mode-specific instructions (Prompts tab — per-mode field)
3. Mode-specific rule directories: ~/.roo/rules-{modeSlug}/ then .roo/rules-{modeSlug}/
4. Generic rule directories: ~/.roo/rules/ then .roo/rules/
5. AGENTS.md (if enabled via roo-cline.useAgentRules)

Important: workspace rules take precedence over global rules when there is a conflict, and mode-specific rules complement global rules rather than replacing them. A rule in .roo/rules/ applies in all modes; a rule in .roo/rules-code/ applies only in Code mode, and stacks on top of whatever is in .roo/rules/.

This layering is the key architectural difference from Cline, which applies a flat .clinerules file to every session without mode discrimination.

Built-In Modes

Roo Code ships with five default modes:

Each built-in mode can be overridden at the global or project level by creating a custom mode with the same slug.

Custom Modes Explained

Custom modes define a specialized AI persona with specific tool access and behavioral rules. Each mode has:

• Slug — URL-safe identifier, matches /^[a-zA-Z0-9-]+$/. Also determines the rule directory name: .roo/rules-{slug}/
• Name — Display name shown in the mode selector
• Role Definition — The core persona prompt. This is where you define expertise, personality, and scope.
• When to Use — Optional description used by Orchestrator mode to decide which mode gets a subtask
• Custom Instructions — Behavioral rules specific to this mode (distinct from the role definition)
• Groups — Which tool categories the mode can use, with optional file restrictions

Tool Groups

Four tool groups are available:

File restrictions on edit use a tuple format:

groups:
  - read
  - - edit
    - fileRegex: \.(md|mdx)$
      description: Markdown files only
  - command

This pattern is useful for modes that should never modify source code — a documentation mode that can only edit .md files, for instance.

Writing Custom Mode Configurations

Custom modes are defined in YAML or JSON files. YAML is the preferred format because regex patterns do not require double-escaping.

Configuration Files

Project-level .roomodes configurations override global ones with the same slug.

YAML Format

customModes:
  - slug: docs-writer
    name: 📝 Docs Writer
    description: Technical documentation specialist
    roleDefinition: |
      You are a technical documentation writer. You understand the codebase
      through reading and produce clear, accurate documentation. You never
      modify source code.
    whenToUse: Use when writing or updating documentation, README files, or API references.
    customInstructions: |
      Always include examples. Keep sentences under 25 words.
      Use present tense. Avoid jargon without definition.
    groups:
      - read
      - - edit
        - fileRegex: \.(md|mdx|txt|rst)$
          description: Documentation files only

JSON Format

{
  "customModes": [
    {
      "slug": "docs-writer",
      "name": "Docs Writer",
      "description": "Technical documentation specialist",
      "roleDefinition": "You are a technical documentation writer...",
      "whenToUse": "Use when writing or updating documentation.",
      "customInstructions": "Always include examples.",
      "groups": [
        "read",
        ["edit", { "fileRegex": "\\.(md|mdx|txt|rst)$" }]
      ]
    }
  ]
}

Note: JSON requires double-escaped backslashes (\\.) where YAML uses single (\.).

Migration from .clinerules

If you are moving from Cline to Roo Code, your existing .clinerules file does not automatically migrate. Here is the mapping:

Step-by-step migration:

# Create the Roo Code directory structure
mkdir -p .roo/rules

# Move your existing Cline rules into the new location
# If you had a single .clinerules file:
cp .clinerules .roo/rules/01-project-rules.md

# If you had a .clinerules/ directory:
cp .clinerules/* .roo/rules/

After migration, you can keep .roorules as a fallback or remove it. The .roo/rules/ directory is the canonical location going forward.

One thing to note: Cline’s .clinerules applies equally to all sessions. After migrating to Roo Code, consider splitting your rules by mode — moving implementation-specific rules to .roo/rules-code/ and keeping only truly universal rules in .roo/rules/.

Real-World Example: Full Project Setup with 4 Custom Modes

Here is a complete setup for a TypeScript web application that uses four custom modes: Architect, Code, Debug, and Docs.

Directory Structure

my-project/
├── .roo/
│   ├── rules/
│   │   ├── 01-project-context.md
│   │   └── 02-constraints.md
│   ├── rules-architect/
│   │   └── 01-design-rules.md
│   ├── rules-code/
│   │   ├── 01-typescript-style.md
│   │   └── 02-test-requirements.md
│   ├── rules-debug/
│   │   └── 01-investigation-protocol.md
│   └── rules-docs/
│       └── 01-documentation-style.md
├── .roomodes
└── src/

.roo/rules/01-project-context.md (applies to all modes)

# Project Context

## Stack
- Runtime: Node.js 22 + TypeScript 5.5
- Framework: Next.js 15 (App Router)
- Database: PostgreSQL 16 via Prisma ORM
- Testing: Vitest + Playwright

## Repository Structure
- `src/app/` — Next.js App Router pages and layouts
- `src/lib/` — Shared utilities and business logic
- `src/components/` — React components
- `prisma/` — Schema and migrations (do not modify without explicit instruction)

## Never Do
- Install npm packages without listing alternatives and asking first
- Modify `src/generated/` — auto-generated files
- Push directly to main branch

.roo/rules-code/01-typescript-style.md

# TypeScript Implementation Rules

## Types
- Never use `any`. Use `unknown` with type narrowing if the type is genuinely unknown.
- Prefer interfaces over type aliases for object shapes.
- Use `satisfies` operator for configuration objects.

## Functions
- Named exports only. No default exports except page components.
- Keep functions under 40 lines. Extract helpers freely.
- Use `Result<T, E>` pattern for operations that can fail.

## React
- Server Components by default. Add `'use client'` only when required.
- co-locate component-specific hooks in the same directory.

## Imports
- Absolute imports from `@/` prefix.
- No barrel exports (no `index.ts` re-export files).

.roo/rules-debug/01-investigation-protocol.md

# Debug Investigation Protocol

## Before Suggesting a Fix
1. Reproduce the issue with a minimal case
2. Identify the exact line that produces the unexpected value
3. Check if the issue exists in the test suite already
4. Look at git blame to understand when the behavior changed

## Output Format
Always structure findings as:
- **Observed**: what is currently happening
- **Expected**: what should happen
- **Root cause**: the actual bug, not symptoms
- **Fix**: specific code change with explanation

## What Not to Do
- Do not suggest "just catch the error and return null" — fix the root cause
- Do not rewrite unrelated code during a debug session
- Do not assume the bug is in the newest code — trace the actual call path

.roomodes (custom mode definitions)

customModes:
  - slug: docs
    name: 📖 Docs
    description: Documentation writer — edits only markdown files
    roleDefinition: |
      You are a technical documentation writer for this project. You read
      source code to understand it, then write clear documentation for developers.
      You have read access to all files but can only edit documentation files.
    whenToUse: Use for writing README files, API references, guides, and inline JSDoc comments.
    customInstructions: |
      Write for developers who know TypeScript but are new to this codebase.
      Always include a code example for each concept. Use present tense.
    groups:
      - read
      - - edit
        - fileRegex: \.(md|mdx)$
          description: Markdown documentation files

  - slug: architect
    name: 🏗️ Architect
    description: System design and architectural decisions
    roleDefinition: |
      You are a software architect. You think in systems, not files.
      You design APIs before they are implemented, identify scalability
      constraints early, and write Architecture Decision Records when
      significant tradeoffs are made.
    whenToUse: Use for designing new features, evaluating architectural options, or writing ADRs.
    customInstructions: |
      Always consider three alternatives before recommending an approach.
      Write ADRs in .roo/decisions/{date}-{title}.md format.
      Think about operability: observability, deployability, rollback.
    groups:
      - read
      - - edit
        - fileRegex: \.(md|yaml|json)$
          description: Design documents and configuration files

  - slug: debug
    name: 🪲 Debug
    description: Root cause analysis and bug investigation
    roleDefinition: |
      You are a debugging specialist. You trace issues to their root cause
      rather than suppressing symptoms. You read logs, trace call stacks,
      and identify the minimal change that fixes the problem.
    whenToUse: Use when something is broken and you need to understand why before fixing it.
    groups:
      - read
      - edit
      - command

Roo Code vs Cline Rules: Key Differences

The core difference is architectural. Cline gives you one flat instruction set for all sessions. Roo Code gives you a layered system where the active mode determines which instruction sets are combined.

For small projects or solo work, this difference may not matter much. For teams working across different task types — design, implementation, documentation, debugging — the ability to switch modes and have context-appropriate rules load automatically is a meaningful productivity improvement.

Practical Tips

Name your rule files with numeric prefixes. Files load alphabetically, so 01-project-context.md loads before 02-style.md. This lets you control load order when rules reference each other.

Keep global rules minimal. Global rules in ~/.roo/rules/ apply everywhere. If a rule is specific to a project, put it in .roo/rules/. Reserve global rules for things like your preferred response language or output format.

Use the Prompts tab for quick experiments. The Prompts tab lets you add instructions without editing files. Once something works, move it into the appropriate .roo/rules/ file so it persists across sessions.

Let Roo write your regex. The docs explicitly suggest asking Roo Code to generate regex patterns for file restrictions. Patterns like ^(?!.*(test|spec))\.(js|ts)$ are easy to get wrong manually.

Commit .roo/ and .roomodes. These files define how the AI behaves in your project. Version-controlling them means the whole team gets consistent behavior, and you can review rule changes in PRs the same way you review code changes.

FAQ

What is Roo Code and how is it different from Cline?

Roo Code is a fork of Cline that adds custom modes — specialized AI personas (Architect, Code, Debug, Ask) each with their own tool access, file restrictions, and instruction sets. Cline gives you one flat instruction set; Roo Code gives you a layered system where the active mode determines which instructions and tool permissions apply. Same VS Code extension paradigm, but a more granular permission and behavior model on top.

Where do I put Roo Code rules?

Three locations: (1) Global rules at ~/.roo/rules/ — apply to every project on your machine. (2) Workspace rules at .roo/rules/ (project root) — apply only to that project, commit-friendly. (3) Mode-specific rules at .roo/rules-{mode}/ — apply only when that mode is active. Roo Code merges all three at runtime, with workspace rules taking precedence over global on conflict.

What’s the difference between .clinerules and .roo/rules/?

.clinerules is a single flat file at the project root (Cline’s format). .roo/rules/ is a directory of multiple markdown files that load alphabetically. The directory format scales better for large rule sets — split by topic (01-context.md, 02-style.md, 03-testing.md) for maintainability. Roo Code also reads .clinerules for backward compatibility, so migration is gradual.

How do Roo Code’s built-in modes (Architect, Code, Debug, Ask) work?

Each built-in mode is a preset with different tool permissions and behavioral framing. Code: full read/write/execute for implementation. Architect: focused on design discussions, often read-only or limited write. Debug: emphasizes diagnostic steps, runs tests proactively. Ask: read-only, conversational Q&A. You switch modes via the mode selector in the chat UI, and the rules at .roo/rules-architect/ (etc.) automatically load.

Can I create my own custom modes?

Yes. Define a custom mode in .roomodes (project) or via the Prompts tab UI. Each mode specifies: slug (unique ID), name (display), roleDefinition (system prompt prefix), groups (tool groups: read, edit, browser, command, mcp), customInstructions (optional inline rules), and optional fileRegex for file restrictions. Example: a docs mode restricted to \\.(md|mdx)$ files only, with edit + read tools.

Does Roo Code read AGENTS.md or CLAUDE.md?

Not natively. Roo Code looks for .roo/rules/, .roorules (legacy), and .clinerules (backward compat). If your repo already has AGENTS.md or CLAUDE.md, the cleanest migration is to copy the relevant content into .roo/rules/00-agents.md, or symlink. For broader multi-tool compatibility, the AGENTS.md spec is becoming the de facto standard — keep AGENTS.md as the source of truth and reference it from .roo/rules/.

How do I prevent Roo Code from reading certain files?

Two mechanisms: (1) .rooignore (gitignore-style) — files listed here are excluded from Roo Code’s context. (2) fileRegex in custom mode definitions — restricts which files the mode can edit (read is still allowed unless ignored). Combine them for tight control: ignore secrets/large files globally, then restrict per-mode for tasks that shouldn’t touch certain paths.

Can Roo Code run shell commands?

Yes, if the active mode has the command group enabled. Each command execution prompts for approval by default. To allow specific commands without prompt, configure them in Settings → Commands. Mode-specific control: Architect mode typically has command disabled, Code mode enabled. Be selective — granting broad command access is the riskiest permission.

What’s the priority order when multiple rule files apply?

Roo Code merges all applicable rule files into context, with alphabetical load order within each directory. Across scopes: workspace .roo/rules/ > global ~/.roo/rules/ on conflicting guidance (workspace wins). Mode-specific rules (.roo/rules-{mode}/) are loaded in addition to general rules when that mode is active, not in place of. Use numeric prefixes (01-, 02-) to control intra-directory order.

We maintain a collection of ready-to-use Roo Code rule templates for common project types. Browse our gallery to find starting points for TypeScript, Python, Go, and other stacks.