Fixing Roo Code Custom Instructions in .roorules and .roo/rules/ That Get Silently Ignored

The Problem

A .roorules file — or its newer, preferred replacement, a .roo/rules/ folder of Markdown files — is added to a project with custom instructions meant to apply to every Roo Code task: things like "always write commit messages in Conventional Commits format" or "never touch files under legacy/." The file is saved, the task is re-run, and nothing changes. Roo Code produces output exactly as it would have before the rules existed, with no error, no warning, and no indication that the rules file was even noticed, let alone parsed or rejected.

Why It Happens

The rules live outside the workspace root, where Roo Code never looks for them

Roo Code only reads global custom-instruction files from the root of the currently open workspace folder. A .roorules file dropped into a subdirectory — a monorepo package, a src/ folder, or a nested git submodule that happens to be the one actually being edited — is invisible to it entirely, because the lookup never recurses into or out of the workspace root to find it.

The directory-based and single-file conventions are mixed, and the directory form has stricter requirements

Roo Code supports two conventions for the same purpose: a single .roorules file, or a .roo/rules/ directory containing one or more files. The directory form only loads files with a .md (or plain text) extension and only at the top level of that folder — a file saved as .roo/rules/project.txt.md, a file with no extension, or rules nested one level deeper in .roo/rules/backend/style.md are silently skipped, even though the folder itself is in the right place.

Mode-specific rules files use a mode slug that's easy to get slightly wrong

Mode-specific instructions follow the pattern .roorules-<mode-slug> or .roo/rules-<mode-slug>/, where the slug must match the mode's internal identifier exactly — for a custom mode this is whatever slug was set when the mode was created, which is not always identical to its display name. A file named .roorules-Code or .roo/rules-architect-mode/ against a mode whose actual slug is code or architect matches nothing, and falls back to loading no mode-specific rules at all rather than erroring.

The Fix

1. Confirm the rules live at the workspace root Roo Code actually has open

my-project/              <- this must be the open workspace folder
├── .roorules            <- single-file form, OR:
├── .roo/
│   └── rules/
│       └── general.md   <- directory form
└── packages/
    └── app/              <- NOT here, even if this is where edits happen

Check the folder actually open in the editor's explorer (not just the folder containing the file being edited) and move or duplicate the rules file to that root. In a multi-root workspace, Roo Code reads rules relative to each workspace folder independently, so a monorepo with several roots needs the file repeated per root if the instructions should apply everywhere.

2. Use .md files directly inside .roo/rules/, with no nested subfolders

.roo/
└── rules/
    ├── 01-commit-style.md
    ├── 02-forbidden-paths.md
    └── 03-testing.md

Files are loaded in alphabetical order and concatenated, which is why numeric prefixes are a common convention for keeping related instructions grouped and predictably ordered. Rename any file missing the .md extension and flatten any subdirectories — only files directly inside rules/ are read.

3. Get the exact mode slug for mode-specific rules from the mode's own configuration, not its display name

.roo/
└── rules-code/           <- "code" is the slug, not the mode's visible label
    └── instructions.md

For a built-in mode, the slug is the lowercase name shown in the mode selector (code, architect, ask, debug, orchestrator). For a custom mode, open its settings (via the mode selector's edit option) and copy the slug field exactly — it's frequently different from the title typed into the "Name" field, especially if the mode was renamed after creation.

4. Reload the window after adding or editing rules files, since they're read once per session

Command Palette -> "Developer: Reload Window"

Roo Code reads custom instruction files when a task starts, not continuously, so editing a rules file mid-task — or even starting a fresh task without reloading after a file was just created — can still pick up a stale, empty, or partially-written version. A full window reload guarantees the next task starts from a clean read of whatever is currently on disk.

Why This Works

None of these failures involve Roo Code misinterpreting valid instructions — in every case, the rules file is syntactically fine but never reaches the point where its content would be read at all, because it fails one of a few exact, silent location or naming checks first. Fixing the problem is a matter of satisfying those checks precisely — root-level placement, a flat set of .md files, an exact mode-slug match, and a fresh read after any change — rather than reformatting the instructions themselves, which were rarely the actual issue.

Conclusion

Custom instructions that appear to have zero effect are almost never a parsing failure; they're a file that Roo Code never found in the first place. Verifying the workspace-root location, using flat .md files under .roo/rules/, matching mode slugs exactly for mode-specific rules, and reloading after changes turns an instructions file from inert into something every task actually follows.