Roo Code 2.1.9 特性解读：从设置界面直达 `.clinerules` 自定义指令配置

Roo Code 2.1.9 特性解读：从设置界面直达.clinerules自定义指令配置

【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code

在 Roo Code 2.1.9 版本中，.clinerules自定义指令从"需要查文档才知道的隐藏能力"变成了"在设置界面即可直接获取指引"的常规配置项。本文以该版本的发布说明为主线，结合 Roo Code 当前仓库的源码实现与官方文档，系统讲解.clinerules文件的作用、加载机制、与全局/工作区规则目录的关系，以及它在后续版本中的演进（被.roo/rules/与.roorules取代并标记弃用），帮助你彻底掌握这套自定义指令体系。

版本背景：2.1.9 做了什么

Roo Code 2.1.9 的发布说明（见 v2.1.9.md）非常聚焦，只有一条核心变更：

This release adds instructions for.clinerulesto the settings screen.

• 本次发布为设置界面新增了关于.clinerules文件用法的说明文字，开发者不再需要翻阅外部资料，直接在设置界面就能看到"如何通过.clinerules文件提供自定义指令"。
• 官方将其归类为General and QOL Improvements（通用与质量改进），属于体验优化型变更，而非引入全新能力。

把这条变更放回版本时间线会看得更清楚：CHANGELOG.md中记录，2.1.2首次加入.clinerules自定义指令支持（"Support for .clinerules custom instructions"），而2.1.9则是补上使用说明（"Add instructions for using .clinerules on the settings screen"）。也就是说，从 2.1.2 到 2.1.9，.clinerules经历了"能力落地"到"引导使用"两个阶段，整体背景可参考 v2.1.2.md 与 v2.1.md。

.clinerules是什么：基于文件的自定义指令

.clinerules是 Roo Code 早期版本提供的文件式自定义指令方案：在项目根目录放置一个名为.clinerules的文本文件（.md/.txt均可），Roo Code 会在构建系统提示词时读取其内容，把它作为对 Agent 行为、编码风格、决策方式的额外约束。

在 custom-instructions.md 中，官方对自定义指令（Custom Instructions）的定义是：

Custom Instructions allow you to personalize how Roo behaves, providing specific guidance that shapes responses, coding style, and decision-making processes.

典型的使用示例包括：

• Always use spaces for indentation, with a width of 4 spaces（统一缩进风格）
• Use camelCase for variable names（统一命名规范）
• Write unit tests for all new functions（强制测试要求）
• Explain your reasoning before providing code（要求先解释后编码）
• When adding new features to websites, ensure they are responsive and accessible（约束前端质量）

与通过 Prompts 标签页手动输入指令相比，.clinerules文件方案的优势在于可版本化：规则文件随项目代码一起提交到 Git，团队所有成员共享同一套约定，且不依赖个人 IDE 设置。

底层实现：.clinerules是如何被加载的

.clinerules的读取逻辑位于 custom-instructions.ts 中。核心函数是loadRuleFiles(cwd, enableSubfolderRules)，它的加载策略非常明确：

// Fall back to existing behavior for legacy .roorules/.clinerules files const ruleFiles = [".roorules", ".clinerules"] for (const file of ruleFiles) { const content = await safeReadFile(path.join(cwd, file)) if (content) { return `\n# Rules from ${file}:\n${content}\n` } }

从这段实现可以看出几个关键事实：

1. .clinerules是回退（fallback）方案：只有当工作区根目录不存在.roo/rules/规则目录（或目录为空）时，才会去读取.roorules与.clinerules文件。
2. 优先级为.roorules优先于.clinerules：代码按[".roorules", ".clinerules"]的顺序依次尝试，找到第一个非空文件即返回。
3. 读取失败静默处理：safeReadFile会捕获ENOENT（文件不存在）与EISDIR（路径是目录）错误并返回空字符串，不会中断提示词构建流程。

模式级指令的对应回退

.clinerules体系还支持模式级文件.clinerules-{modeSlug}（例如.clinerules-code）。在addCustomInstructions函数中（custom-instructions.ts），当rules-{mode}目录不存在时，会依次回退到.roorules-{mode}、再回退到.clinerules-{mode}：

const rooModeRuleFile = `.roorules-${mode}` modeRuleContent = await safeReadFile(path.join(cwd, rooModeRuleFile)) if (modeRuleContent) { usedRuleFile = rooModeRuleFile } else { const clineModeRuleFile = `.clinerules-${mode}` modeRuleContent = await safeReadFile(path.join(cwd, clineModeRuleFile)) ... }

规则内容的注入格式

无论是文件还是目录方式，规则内容都会以带来源标注的格式注入系统提示词。目录方式使用# Rules from {相对路径}:作为文件头；文件方式使用# Rules from {文件名}:。最终由addCustomInstructions组装进USER'S CUSTOM INSTRUCTIONS区块，并通过系统提示词告知模型"在不干扰工具使用准则的前提下，尽力遵循这些额外指令"。

设置界面说明：从文档到 UI 的引导

2.1.9 的核心变更是把.clinerules的用法说明直接放进了设置界面。在当前的国际化文案中仍能看到这段引导文字的踪迹，例如 webview-ui/src/i18n/locales/en/prompts.json 中的loadFromFile条目：

Custom instructions specific to {{mode}} mode can also be loaded from the.roo/rules-{{slug}}/folder in your workspace or from the global.roo/rules-{{slug}}/（.roorules-{{slug}}and.clinerules-{{slug}}are deprecated and will stop working soon）.

也就是说，2.1.9 时代设置界面上的说明文字会引导用户：除了在界面上直接输入，还可以通过文件方式配置自定义指令。这种"界面 + 文件"双通道的设计，让偏好配置既可以保存在 IDE 设置中，也可以跟随项目/团队共享。

完整配置体系：.clinerules在规则体系中的位置

要正确理解.clinerules，必须看清它所在的整个自定义指令体系（详见 custom-instructions.md）。规则按作用范围分为三类：

注意：.clinerules系列只存在于"单文件回退"这一层，且始终位于优先级末位——它排在.roo/rules/目录、.roorules文件之后。

规则加载顺序

从源码addCustomInstructions（custom-instructions.ts）可以梳理出完整的注入顺序：

1. 语言偏好（如设置则最先注入）；
2. 全局指令（Prompts 标签页中面向所有模式的输入）；
3. 模式专属指令（Prompts 标签页中当前模式的输入）；
4. Rules 区块，依次为：模式级规则（rules-{mode}目录 →.roorules-{mode}→.clinerules-{mode}）→.rooignore相关指令 →AGENTS.md（默认启用，可用roo-cline.useAgentRules: false关闭）→ 通用规则（rules/目录 →.roorules→.clinerules）。

目录方式与文件回退方式遵循"目录优先，文件兜底"原则：.roo/rules/与~/.roo/rules/会被聚合（同时加载，而非二选一）；只有规则目录完全缺失或为空时，才读取.roorules/.clinerules单文件。

目录方式的关键行为

当前版本的规则目录实现（readTextFilesFromDirectory，custom-instructions.ts）具备以下特性：

• 递归读取：目录下所有子目录中的规则文件都会被读取；
• 按文件名排序：以文件名（不含路径）做大小写不敏感排序后按序注入，保证多次运行结果一致；
• 自动过滤缓存/临时文件：shouldIncludeRuleFile（custom-instructions.ts）会排除.DS_Store、*.bak、*.cache、*.log、*.tmp、Thumbs.db等 20 余种文件；
• 符号链接支持：文件与目录的符号链接均可解析，但递归解析深度上限为 5 层（MAX_DEPTH = 5），以防止符号链接循环导致死循环。

后续演进：从.clinerules到.roo/rules/目录体系

值得注意的是，.clinerules是 Roo Code 早期继承自 Cline 生态的遗留（legacy）方案。当前仓库的官方文档与源码已经明确将其标记为弃用状态：

• CHANGELOG.md 记录了后续版本"Add support for .roorules and give deprecation warning for .clinerules"，即新增.roorules支持并给出弃用警告；
• 设置界面/i18n 文案中明确提示.clinerules与.clinerules-{slug}已被弃用，将很快停止工作；
• custom-instructions.md 将.roo/rules/目录列为首选方法，.roorules单文件列为回退方法，.clinerules仅在"[Generic only] Legacy Files"注释中被提及，且只在没有任何通用规则目录内容时才使用。

因此，如果你在今天使用 Roo Code，建议遵循以下迁移路径：

1. 新项目：直接使用.roo/rules/目录组织规则文件，文件名按01-*.md、02-*.md编号以控制注入顺序；
2. 已有.clinerules项目：将内容迁移到.roo/rules/目录（或至少重命名为.roorules），避免未来版本移除兼容层后规则失效；
3. 团队协作：将.roo/rules/目录纳入版本控制，配合AGENTS.md实现项目级 Agent 行为标准。

小结

Roo Code 2.1.9 虽然在功能层面只做了一件事——在设置界面补充.clinerules的使用说明——但它标志着基于文件的自定义指令方案正式成为文档化的常规配置入口。从 2.1.2 的能力引入，到 2.1.9 的界面引导，再到后续版本演进为.roo/rules/目录体系，loadRuleFiles/addCustomInstructions这两条核心函数（见 custom-instructions.ts）始终承担着规则加载与提示词组装的重任。

理解这套机制后，你可以：

• 用.clinerules/.roorules快速为项目注入编码规范（了解其作为回退方案的位置与优先级）；
• 用.roo/rules/目录实现可版本化、可排序、可递归组织的团队级规则；
• 结合 Prompts 标签页、AGENTS.md与自定义模式（custom-modes.mdx）构建完整的 Agent 行为约束体系。

【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code