Roo Code 提示词工程实战指南：写出高效 AI 编码指令的完整方法论
【免费下载链接】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 在编辑器内为你提供了一支由多个 AI Agent 组成的开发团队，而提示词（Prompt）就是你与这支团队沟通的"指挥语言"。本文以 Roo Code 官方提示词工程指南为主体，系统讲解如何写出清晰、具体、可执行的高效指令，并深入仓库源码揭示自定义指令的注入机制、@上下文引用（Context Mentions）的底层实现，以及 Roo Code 在遇到歧义时的真实行为。读完本文，你将掌握从"基本提问原则"到"全局/模式级自定义指令体系"的完整提示词工程技能。
提示词工程的核心原则
提示词工程（Prompt Engineering）是为 Roo Code 这类 AI 模型编写有效指令的艺术。一份精心编写的提示词，能带来更好的结果、更少的错误和更高效的工作流。官方指南在 prompt-engineering.md 中给出了五条基础原则：
- 清晰且具体（Be Clear and Specific）：明确说明你希望 Roo Code 做什么，避免歧义。
- ❌ 反例：
Fix the code.（修复代码） - ✅ 正例：
Fix the bug in the calculateTotal function that causes it to return incorrect results.（修复calculateTotal函数中导致返回错误结果的 bug）
- ❌ 反例：
- 提供上下文（Provide Context）：使用 Context Mentions 引用特定文件、文件夹或问题。例如：
@/src/utils.ts Refactor the calculateTotal function to use async/await. - 拆分任务（Break Down Tasks）：将复杂任务分解为更小、定义清晰的步骤。
- 给出示例（Give Examples）：如果你有特定的编码风格或模式，请在提示词中提供示例。
- 指定输出格式（Specify Output Format）：如果需要特定格式（如 JSON、Markdown）的输出，在提示词中明确说明。
- 迭代（Iterate）：如果初始结果不符合预期，不要害怕反复打磨你的提示词。
为什么"具体"如此重要？从源码结构看，Roo Code 的系统提示词（由 system.ts 组装）会同时注入当前模式定义、工具使用规范（TOOL USE guidelines）、可用工具清单 以及你的自定义指令。模型在每个回合会依据这些约束决定调用哪个工具（如
read_file、edit、execute_command）。一个含糊的指令会让模型基于"最佳猜测"行动——而最佳猜测往往不是你想要的。
"先思考、后执行"（Thinking vs. Doing）的四步流程
在许多场景下，引导 Roo Code 走完一个"先思考、后执行"的流程会显著提升结果质量：
- 分析（Analyze）：让 Roo Code 先分析当前代码、识别问题或制定方法。
- 计划（Plan）：让 Roo Code 列出完成任务的步骤大纲。
- 执行（Execute）：指示 Roo Code 一步一步实现计划。
- 审查（Review）：在继续之前仔细审查每一步的结果。
这套流程与 Roo Code 的架构天然契合：在任务执行过程中，Roo Code 会在每一步工具调用之间穿插推理，而你可以随时批准（Approve）或拒绝（Reject）它的动作提案。将"分析+计划"显式写入提示词，等于强制模型在动手改代码前先把思路暴露给你，从而减少"边想边改"带来的不可控变更。
用 Context Mentions 注入精确上下文
提示词工程中"提供上下文"最强大的载体就是 Context Mentions。所有 mention 都以@符号开头，你可以用它引用文件、文件夹、VS Code 问题面板（Problems）、终端输出和 Git 提交。下表汇总了官方文档定义的完整 mention 类型：
| Mention 类型 | 格式 | 说明 | 示例用法 |
|---|---|---|---|
| 文件（File） | @/path/to/file.ts | 将文件内容包含进请求上下文 | Explain the function in @/src/utils.ts |
| 图片（Image） | @/path/to/image.png | 将图片作为内联视觉内容（需模型支持视觉） | What's wrong with this UI? @/screenshots/bug.png |
| 文件夹（Folder） | @/path/to/folder/ | 包含文件夹内所有文件的直接内容（非递归） | Analyze the code in @/src/components/ |
| 问题（Problems） | @problems | 包含 VS Code 问题面板的诊断信息 | @problems Fix all errors in my code |
| 终端（Terminal） | @terminal | 包含最近的终端命令及输出 | Fix the errors shown in @terminal |
| Git 提交（Commit） | @a1b2c3d | 按哈希引用特定提交 | What changed in commit @a1b2c3d? |
| Git 变更（Changes） | @git-changes | 展示未提交的变更 | Suggest a message for @git-changes |
| URL | @https://example.com | 导入网页内容 | Summarize @https://docusaurus.io/ |
| 斜杠命令（Slash Command） | /<command-name> | 执行预定义的斜杠命令（用/而非@） | /test Run all tests |
各类 Mention 的实战细节
- 文件 Mention：格式为
@/path/to/file.ts（始终以工作区根目录的/开头）。它提供带行号的完整文件内容；支持文本文件、PDF 和 DOCX（通过文本提取）；可用于初次请求、反馈回复和后续消息；超大文件可能被截断，二进制文件不被支持。 - 图片 Mention：是文件 mention 的一种特殊子类型。当模型支持视觉时，图片会以内联视觉内容而非文本发送。支持 PNG、JPG、JPEG、GIF、BMP、SVG、WEBP、ICO、AVIF，最适合 UI 评审、截图调试、图表分析。
- 文件夹 Mention：格式为
@/path/to/folder/（末尾斜杠用于与文件 mention 区分）。提供目录内所有文本文件的完整内容（非递归），适合一次提供多个文件的上下文；但要注意上下文窗口限制，谨慎引用大目录。 - Problems Mention：
@problems直接导入 VS Code 问题面板中全部错误和警告，包含文件路径、行号和诊断信息，按文件分组，最适合"修复错误"类任务，免去手动复制。 - 终端 Mention：
@terminal捕获最后一条命令及其完整输出，保留终端状态（不会清空终端），但仅限于可见的终端缓冲内容，最适合调试构建错误或分析命令输出。 - Git Mention：
@a1b2c3d提供提交消息、作者、日期和完整 diff；@git-changes提供git status输出和未提交变更的 diff。两者都仅在 Git 仓库中有效。 - URL Mention：
@https://example.com通过无头浏览器抓取网页内容，清理脚本、样式和导航元素后转换为易读的 Markdown；复杂页面可能无法完美转换。 - 斜杠命令 Mention：
/<command-name>由 mentions 系统处理，执行预定义命令并包含相关上下文，内容块类型为command。示例包括/test、/init、/deploy等，详见 Slash Commands。
使用方式与下拉建议
在聊天输入框中输入@即可触发建议下拉菜单：
- 输入
@触发下拉建议； - 继续输入过滤建议，或用方向键导航；
- 按 Enter 或鼠标点击选择；
- 组合多个 mention：
Fix @problems in @/src/component.ts。
下拉菜单会自动建议：最近打开的文件、可见文件夹、最近的 Git 提交、特殊关键词（problems、terminal、git-changes），以及所有当前打开的文件（不受 ignore 设置或目录过滤器影响）。下拉菜单默认遵循.rooignore，隐藏被忽略文件；可通过showRooIgnoredFiles设置显示（以 🔒 标记）。node_modules、.git、dist、out等常见目录也会被过滤以降低噪音。
底层实现：mentions 是如何被解析的
从源码看，所有 mention 的解析集中在 src/core/mentions/index.ts 的parseMentions函数中。该函数采用"两遍扫描"策略：
- 第一遍：先通过
commandRegexGlobal匹配所有斜杠命令，并缓存其存在性检查结果（L116-L135），确保只有真正存在的命令才会被替换为命令内容块； - 第二遍：通过
mentionRegexGlobal处理普通 mention（L163-L181），将文本中的 mention 替换为干净的引用，再把文件/文件夹内容、诊断信息、Git 工作区状态、提交信息和终端输出分别追加为独立的内容块。
几个值得注意的实现细节：
- 文件内容格式化：文件内容被格式化为类似
read_file工具结果的样式（带[read_file for '...']头），若被截断还会给出提示（"Status: Showing lines X-Y of N total lines"）并建议使用read_file工具继续读取（formatFileReadResult）； - 二进制与 ignore 处理：二进制文件会以"Binary file omitted from context"跳过；被
.rooignore忽略的文件若被直接 mention，会返回"File is ignored by .rooignore"提示——但需要说明的是，官方文档指出：文件/文件夹@mention在抓取内容时会绕过.rooignore和.gitignore检查，被忽略文件的内容在直接引用时仍会被包含；而@git-changes、@commit-hash这类依赖 Git 命令的 mention 则会尊重.gitignore。 - 终端输出捕获：
getLatestTerminalOutput的实现很巧妙——它通过 VS Code 命令选中终端全部内容、复制到剪贴板再读取，最后恢复原剪贴板内容（L416-L457）。
使用自定义指令（Custom Instructions）塑造 Roo 行为
自定义指令是提示词工程在 Roo Code 中的"持久化"形态。它们被注入系统提示词，为 AI 模型提供持续性的指导。官方定义了两种类型：
- 全局自定义指令（Global Custom Instructions）：适用于所有模式。
- 模式特定自定义指令（Mode-Specific Custom Instructions）：仅适用于特定模式（如 Code、Architect、Ask、Debug 或自定义模式）。
你可以用它们来：强制执行编码风格规范、指定偏好的库或框架、定义项目特定约定、调整 Roo Code 的语气或个性。详见 Custom Instructions。
自定义指令的配置位置
Roo Code 支持多种配置来源，可组合使用：
全局规则目录（Global Rules Directory）——跨项目自动生效：
- Linux/macOS：
~/.roo/rules/和~/.roo/rules-{modeSlug}/ - Windows：
%USERPROFILE%\.roo\rules\和%USERPROFILE%\.roo\rules-{modeSlug}\
工作区规则（Workspace Rules）——仅对当前项目生效，与全局规则冲突时优先生效：
- 首选方法（目录）：
.roo/rules/，例如：. ├── .roo/ │ └── rules/ # 工作区通用规则 │ ├── 01-general.md │ └── 02-coding-style.txt └── ... (其他项目文件) - 回退方法（单文件）：
.roorules
模式特定指令（Mode-Specific Instructions）——仅对特定模式生效：
- 首选方法（目录）：
.roo/rules-{modeSlug}/，例如.roo/rules-code/存放01-js-style.md、02-ts-style.md； - 回退方法（单文件）：
.roorules-{modeSlug}（如.roorules-code）。
也可以在 Roo Code 顶栏点击笔记本图标打开Prompts Tab，在"Custom Instructions for All Modes"或"Mode-specific Custom Instructions (optional)"输入框中填写并点击 Done 保存。
源码级原理：指令是如何拼进系统提示词的
所有上述指令最终由 src/core/prompts/sections/custom-instructions.ts 的addCustomInstructions函数统一组装，并由 src/core/prompts/system.ts 在生成系统提示词时调用注入。组装后的格式如下：
==== USER'S CUSTOM INSTRUCTIONS The following additional instructions are provided by the user, and should be followed to the best of your ability. Language Preference: [语言偏好（若设置）] Global Instructions: [来自 Prompts Tab 的全局指令] Mode-specific Instructions: [来自 Prompts Tab 的当前模式特定指令] Rules: # Rules from rules-{modeSlug} directories: [~/.roo/rules-{modeSlug}/ 与 .roo/rules-{modeSlug}/ 全部文件内容] # Rules from .roorules-{modeSlug}: [当模式特定目录无文件时的 .roorules-{modeSlug} 内容] # Rules from .rooignore: [.rooignore 相关指令（如适用）] # Agent Rules Standard (AGENTS.md): [工作区根目录 AGENTS.md 或 AGENT.md 内容（若存在且启用）] # Rules from rules directories: [~/.roo/rules/ 与 .roo/rules/ 全部文件内容] # Rules from .roorules: [当通用规则目录无文件时的 .roorules 内容] ====源码实现中的关键行为（均有明确代码证据）：
- 加载顺序：规则按"全局优先、项目本地其次"的顺序加载；模式特定规则先于通用规则；目录式规则优先生效，空目录时回退到
.roorules/.roorules-{modeSlug}单文件（addCustomInstructions）； - 递归读取与字母序排序：
readTextFilesFromDirectory递归读取规则目录（含子目录），并按文件名不区分大小写地排序（L122-L180）； - 文件过滤：
shouldIncludeRuleFile自动排除缓存与临时文件——.DS_Store、*.bak、*.cache、*.log、*.tmp、Thumbs.db等（L513-L547）； - 符号链接：对规则文件和目录完全支持符号链接，最大解析深度为 5 层以防止无限循环（
MAX_DEPTH = 5）； - AGENTS.md 支持：仓库根目录的
AGENTS.md（回退AGENT.md）会被自动加载（默认开启，可通过 VSCode 设置"roo-cline.useAgentRules": false关闭），若同时存在则AGENTS.md优先；空文件被忽略；也支持AGENTS.local.md作为不入库的个人覆盖（loadAgentRulesFileFromDirectory）。这正是团队可以把 AI 行为标准纳入版本控制的原因——当前仓库根目录的 AGENTS.md 即是该机制的实际范例。
团队标准化建议
- 项目标准：把工作区
.roo/rules/目录纳入版本控制，为具体项目标准化 Roo 的行为； - 组织标准：使用全局规则
~/.roo/rules/建立适用于所有项目的组织级编码标准； - 混合方案：全局规则负责组织标准，工作区规则负责项目特定需求；规则冲突时工作区规则优先生效。
处理歧义：假设与澄清
如果请求含糊不清或缺乏足够细节，Roo Code 可能：
- 做出假设（Make Assumptions）：基于最佳猜测继续执行，这可能并非你的本意；
- 提出澄清问题（Ask Follow-Up Questions）：使用
ask_followup_question工具澄清你的请求。
因此，从一开始就提供清晰具体的指令通常能避免不必要的来回沟通。从源码看，ask_followup_question是 Roo Code 工具集中的一等公民：AskFollowupQuestionTool 接收question和follow_up建议列表，将建议转换为{ answer, mode }格式后通过task.ask("followup", ...)暂停任务等待你的回答（L20-L55）。也就是说，当模型判断信息不足时，它会显式地把控制权交还给你，而不是盲目动手。
提供反馈：让 Roo Code 从错误中学习
如果 Roo Code 没有产出理想结果，可以通过以下方式反馈：
- 拒绝动作（Rejecting Actions）：当 Roo Code 提出你不想要的动作时，点击"Reject"按钮；
- 解释原因（Providing Explanations）：拒绝时解释为什么拒绝——这能帮助 Roo Code 从错误中学习；
- 改写请求（Rewording Your Request）：尝试重新措辞初始任务，或提供更具体的指令；
- 手动修正（Manually Correcting）：如果只有少量小问题，也可以在接受变更前直接手动修改代码。
实例对比：好提示词 vs 坏提示词
官方文档给出了三组经典对照，直观展示"具体化"的力量：
| 场景 | 好提示词 | 坏提示词 |
|---|---|---|
| 重构 | @/src/components/Button.tsxRefactor theButtoncomponent to use theuseStatehook instead of theuseReducerhook. | Fix the button. |
| 新建文件 | Create a new file namedutils.pyand add a function calledcalculate_averagethat takes a list of numbers and returns their average. | Write some Python code. |
| 修复问题 | @problemsAddress all errors and warnings in the current file. | Fix everything. |
不难发现，三组"好提示词"都同时应用了本文的多条原则：指明具体对象（文件路径或@problems）、规定动作细节（改用哪个 hook、函数签名是什么）、限定范围（errors and warnings in the current file）。这比笼统的"修一下"要可靠得多。
总结
有效的提示词工程 =明确的目标+精确的上下文（@mention）+合理的任务分解+持久化的自定义指令+及时的反馈迭代。把本文的原则内化为你的日常习惯，并将团队约定沉淀到.roo/rules/与 AGENTS.md 中，你就能持续稳定地榨取 Roo Code 这支"AI 开发团队"的最大能力。若想进一步深入，可继续阅读 Custom Modes 了解如何将自定义指令与专用工具权限相结合，构建面向特定场景的专属 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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
