Qoder 使用指南：从配置到落地

一、Qoder 定位

Qoder 是一款嵌入 IDE 的 AI 编程 Agent，支持 JetBrains（IDEA、DataGrip 等）和 VSCode。与 GitHub Copilot 等补全工具的核心区别在于：Qoder 的 Agent 模式支持自主执行多文件任务------读取相关代码、按需修改多个文件、执行终端命令、调用外部工具，整个过程以 diff 形式呈现供开发者 Review 后接受或拒绝。

两种使用模式

模式	行为	适用场景
Ask 模式	对话问答，代码由用户手动粘贴	快速提问、代码解释、思路讨论
Agent 模式	自主读文件、改代码、执行命令，结果以 diff 展示	功能开发、重构、生成文档、调试

产品选型

• IDE 插件：面向开发人员，在现有 IDE 内使用，不改变工具链
• QoderWork 桌面端：面向非开发岗位（产品、运营、行政等），处理文档整理、数据分析、PPT 生成等日常任务，不需要安装 IDE

本文主要介绍 IDE 插件的使用方式。

DataGrip 插件的特殊说明

DataGrip 是数据开发同学的主力工具，但需要了解一个现实情况：DataGrip 插件与 QoderWork 由不同团队开发，且 DataGrip 不在 Qoder 的核心规划版图中，更新节奏相对较慢。具体体现在：

• 内置 MCP 和 Skill 数量偏少，部分通用场景没有开箱即用的支持
• 部分功能比 QoderWork 晚发布或尚未支持

这是产品优先级的问题，不是技术限制。数据开发同学目前的主要受益点在于：通过 MCP 让 AI 直连数据库，以及通过 Rules/Skills 规范 SQL 生成行为。

---

二、为什么需要配置

直接使用 AI 对话存在一个结构性问题：同一个需求，不同人给出不同提示词，AI 会给出不同风格的代码。对于团队协作的项目，这会导致：

• 接口返回格式不统一
• 组件异常状态处理方式各异
• 代码风格和命名规范难以收敛

这不是模型能力的问题，而是 AI 缺少"这个团队怎么做事"的上下文。

Qoder 的四项配置（Rules / Skills / MCP / Memory）解决的正是这个问题------不是让 AI 更聪明，而是让 AI 按团队约定的方式稳定工作。

参考数据：蔚来汽车智能座舱团队约 400 名研发成员，通义灵码（Qoder CN）在日常开发中生成的代码占比达 30% 以上；在「天探」项目的增量代码部分，AI 生成占比最高达 70-80%。这一数字的背后，是团队将编码规范、历史 Bug 模式通过 Prompt 和 Rules 体系统一沉淀后，AI 输出才具备了生产可用的稳定性。（来源：通义灵码官方博客，2025.05）

---

三、Rules：注入常驻上下文

是什么

Rules 是注入到每次对话的背景规则，存储在项目根目录的 .qoder/rules/ 下，随代码库通过 Git 共享给所有团队成员。大语言模型本身不了解你的项目约定，Rules 的作用就是把这些约定以自然语言的形式持续注入给 AI。

如果不想共享某条规则（个人偏好类），将 .qoder/rules/ 加入 .gitignore 即可。

容量上限：所有激活规则文件总字符数不超过 100,000，超出部分会被截断。

四种触发类型

类型	触发方式	适合内容
Always Apply	每次对话都生效	全项目统一规范（接口格式、错误处理底线）
Model Decision	AI 在 Agent 模式中判断是否触发	场景化任务（如"生成单元测试时触发测试规范"）
Specific Files	匹配通配符路径时触发（如 *.vue）	针对特定语言或目录的规范
Apply Manually	对话中手动 @rule 调用	低频但关键的规则（如部署前检查清单）

驾驶舱项目 Rules 示例

以建筑行业驾驶舱开发为例，推荐写入以下 Always Apply 规则：

接口层

- 接口返回统一结构：{ code: number, data: T, message: string }
- 列表字段统一命名为 list，总条数为 total
- 空列表返回 []，不返回 null

前端组件层

- 图表组件必须处理三种状态：loading / 空数据 / 错误，不能只处理正常渲染
- 空数据（data 为 []）和数值为 0 要区分显示，不使用 !data 判断
- 组件 Props 必须定义 TypeScript 类型

数据查询层

- 写 SQL 前先确认字段存在，不要基于记忆假设字段名
- Doris 查询统一加 WHERE is_delete = 0 过滤
- 不确定的枚举字段值先 GROUP BY 探查分布再写 WHERE 条件

配置方式

Settings → Rules → Add，输入规则名称，选择触发类型，关闭窗口即保存。

注意事项

Rules 的质量直接影响 AI 的输出稳定性，但写好 Rules 需要积累------需要先知道 AI 在哪些地方会偏差，才能针对性地写规则。建议团队维护一套经过验证的基础包（参见附录A），个人在此基础上追加业务特定规则，不建议从零自行撰写。

---

四、Skills：按需加载的工作流模板

是什么

Skills 是封装了特定工作流的可复用模块。与 Rules 的区别在于：Rules 是每次对话都常驻注入，而 Skills 是按需加载------只有当当前任务匹配某个 Skill 的描述时，该 Skill 的完整内容才会进入上下文。

一个 Skill 的标准文件结构：

my-skill/
├── SKILL.md       # 必须：YAML frontmatter（name/description）+ 执行指令
├── references/    # 可选：参考文档、规范说明
├── scripts/       # 可选：配套可执行脚本
└── assets/        # 可选：模板、示例文件

SKILL.md 的 frontmatter 包含两个关键字段：

• name：Skill 的唯一标识
• description：触发条件描述，AI 根据这段描述判断当前任务是否需要加载该 Skill

为什么比把工作流写进 Rules 更好

把所有工作流都塞进 Rules 是一个常见误区，会带来两个问题：

1. 积分浪费：Rules 每次对话都加载，但大多数 Skill 对应的工作流场景并不是每次都用到
2. 信号稀释：重要的底线规则被大量工作流细节淹没，AI 处理时权重难以分配

实测数据：一个真实前端项目将工作流从 Rules 迁移到 Skills 后，每次对话启动消耗的 token 从 7,121 降至 2,213，减少 69% ，而工作流指令在需要时依然完整加载。

对于 Qoder 按量计费的场景，这个差距在长期使用中会明显体现。

自己写 Skills 的有效性

需要说明的一点：有研究对大量真实 Skills 做过评测（SkillsBench，Anthropic）：

• 人工精心设计的 Skills：平均提升任务通过率 16.2 个百分点
• 随手自动生成的 Skills：平均收益为零，部分场景甚至不如不用

差距来自于：description 触发词是否覆盖真实用户话术、执行步骤是否清晰完整、输出格式是否经过验证。

因此推荐的做法是：团队提供经过验证的基础 Skills 包，个人直接使用或在此基础上微调，而不是人人自己从零写。

驾驶舱项目推荐 Skills 清单

Skill	适用角色	触发场景示例
需求转接口设计	后端	"把这个驾驶舱模块的需求拆成接口，给出字段定义"
图表组件生成	前端	"按这个接口格式生成 ECharts 折线图组件"
API 文档生成	后端	"给这批接口补齐 Swagger / OpenAPI 注释"
单元测试生成	前后端	"给这个方法生成测试用例"
代码 Review	前后端	"Review 这段代码"、"PR 提交前检查"
表模型开发	数据	"新建 DWS 层宽表，生成建表语句和字段说明"
数据导出	数据	"从 Doris 查询数据，导出多 sheet Excel"
案例沉淀	全部	"把这次排查过程记录下来"

团队共享方式

Skills 文件结构是独立的文件夹，可以直接通过 Git 仓库分发：

• 项目级 ：放在 .qoder/skills/，随 repo 提交，所有成员自动获取
• 个人级 ：放在 ~/.qoder/skills/，本人跨项目可用
• 团队级：维护一个独立的 Skills 仓库，通过 Git submodule 引入项目

---

五、MCP：连接外部系统

是什么

MCP（Model Context Protocol）是让 AI 在 Agent 模式下直接调用外部工具的标准协议------查数据库、读文档、调接口，而不是等你手动把结果复制粘贴到对话框。

驾驶舱场景下的实际价值

后端开发：AI 直接连接 Swagger 或接口文档，理解现有接口的字段结构和命名风格，写新接口时自动保持一致，而不是按自己的风格生成。

前端开发：AI 直接读接口返回结构，生成图表组件时字段绑定准确，不需要反复核对字段名。

数据开发：AI 直接查 Doris，验证字段是否存在、字段值分布是什么，写 SQL 前不会凭记忆假设字段名或枚举值。

团队当前 MCP 配置

MCP	连接目标	主要用途
mysql-doris	10.0.251.22:9030 / db_pidata	中台数仓查询和字段验证（主力）
mysql-13-11	10.0.13.11:3306	业务同步库，对照 ETL 上游原始数据
mysql-yw	10.0.13.92:3306	中台运维库，调度任务相关
mcp-doc	本地文档目录	读取项目文档、数据字典、领域本体

MCP 配置只需做一次，且可以共享。配置文件放在内部仓库，按说明填写连接参数即可。详见附录B。

已知问题

在 Agent 模式下，如果对话中途中断，数据库侧可能残留未结束的查询进程，需要手动 KILL。

---

六、Memory：跨会话上下文记忆

是什么

Qoder 具备基于 LLM 的持久记忆功能，可以记住开发者的项目上下文、技术栈偏好和沟通习惯，在后续对话中无需重新介绍。

当前限制

IDE 插件的 Memory 与 QoderWork 桌面端的 Memory 目前不互通。 在 IDEA 中建立的项目记忆，切换到 QoderWork 后无法读取，反之亦然。

推荐做法

不过度依赖自动记忆，而是将关键上下文结构化沉淀为文档（数据字典、领域本体、接口规范），在 Rules 中告知 AI 这些文档的位置，让 AI 每次主动读取。这样的上下文比依赖记忆更稳定，也更便于团队共享。

具体做法：用自定义 Command 封装"将本次会话的关键结论保存到文档"的操作，在每次重要排查或设计完成后触发。

---

七、Hooks：不信任AI时的最后一道门

前四项配置（Rules / Memory / Skills / MCP）都是在告诉 AI "应该怎么做"------通过规则、记忆、工作流、工具来引导它。但引导终究是建议，AI 有理解偏差的可能。Hooks 的逻辑不同：它不信任 AI 的理解，直接用代码强制执行。

是什么

Hooks 是在 AI 工具调用生命周期的特定节点自动触发的脚本，无论 AI 是否"理解"了规则，脚本都会运行。

两个最常用的触发时机：

事件	触发时机	典型用途
PreToolUse	AI 调用工具之前	检查、拦截、修改参数
PostToolUse	AI 调用工具成功之后	自动格式化、同步文档、发送通知

配置位置

Hooks 写在 .claude/settings.json 中，随项目 Git 共享：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__mysql-doris__",
        "hooks": [
          {
            "type": "command",
            "command": "python "/path/to/sql_guard.py""
          }
        ]
      }
    ]
  }
}

matcher 用于过滤具体工具，支持精确匹配和正则。退出码约定：0 = 通过，2 = 阻断（把原因反馈给 AI）。

落地场景：驾驶舱项目中的两个实际 Hook

场景一：SQL 安全拦截（PreToolUse）

AI 在 Agent 模式下通过 MCP 查 Doris 时，先经过 sql_guard.py 检查：

• 检查 SQL 是否包含危险操作（如未带 WHERE 的全表 DELETE/UPDATE）
• 检查是否绕过了 is_delete = 0 过滤
• 不合规则返回退出码 2，AI 收到拦截原因后会修正 SQL 再重试

效果：Rules 里写"查询必须加 is_delete = 0"，AI 偶尔会漏；Hook 里写死检查逻辑，漏不了。

场景二：文档自动同步（PostToolUse）

AI 写入或修改文件后，自动触发 sync_docs.py，将变更同步到对应的文档索引：

"PostToolUse": [
  {
    "matcher": "Write|Edit",
    "hooks": [
      {
        "type": "command",
        "command": "python "/path/to/sync_docs.py""
      }
    ]
  }
]

Rules 与 Hooks 的分工

	Rules	Hooks
本质	自然语言约束，注入提示词	代码脚本，强制执行
适合内容	编码风格、命名规范、行为引导	安全检查、格式化、自动化操作
执行保证	AI 理解后遵守，有偏差可能	一定执行，不依赖 AI 理解
维护成本	低，自然语言即可	高，需要写和维护脚本

建议：先用 Rules 快速建立规范，遇到 AI 反复不遵守的高风险操作（如危险 SQL、敏感数据访问）才上 Hooks 做强制拦截。

---

八、人机边界

明确 AI 能做什么、不能做什么，避免过度依赖或过度保守两种极端。

可以交给 AI 独立执行的：

• 代码草稿生成（接口、组件、SQL）
• 根据需求文档拆解技术方案
• 注释和 API 文档补充
• 报错分析和排查建议
• 测试用例生成

需要人工确认后再执行的：

• 多文件修改（Review diff 再接受）
• 数据库 DDL 变更
• 涉及业务口径的最终判断

必须由人操作的：

• 接口上线、数据库发布
• 任何生产环境操作

简单来说：AI 负责准备，人来确认和执行。AI 生成的代码在 Merge 前必须经过 Review，这一环节不能因为"是 AI 写的"而省略。

---

八、提效度量与模型选型

8-1 提效量化指标

使用 AI 工具后的效果需要量化才有说服力，建议按角色分别跟踪：

开发人员

指标	说明
代码合并量	每人每周提交的有效代码行数
合并通过率	PR 一次性通过 Review 的比例，反映 AI 生成代码质量
需求交付周期	从需求评审到上线的天数

业务人员（使用 QoderWork）

提效方向因岗位而异，建议结合实际工作内容定义，常见参考：文档处理时长、报告生成频次、重复操作减少比例。

---

8-2 模型选型：Benchmark 方法

Qoder 支持切换不同底层模型。不建议默认使用最贵的模型------不同场景对模型的要求不同，选型应基于实测，而非预设。

基本评估方法

针对实际业务场景整理测试题目：

• 技术场景（20-30题）：涵盖接口设计、图表组件生成、SQL 调试、代码 Review、单测生成等日常开发任务
• 业务场景（若有）：针对项目特有的业务理解类问题
• 通用基线（可选，100题）：覆盖基础编程能力，用于不同模型间横向对比

评估指标

类型	指标
客观指标	准确率、首次正确率、任务完成时长、交互轮次、Rules 遵循度
主观指标	输出可用性（能否直接使用，还是需要大幅修改）

其中「首次正确率」和「Rules 遵循度」最能反映模型在团队规范约束下的实际表现。

模型分级参考

场景	建议模型档位
复杂需求拆解、架构设计、长上下文 ETL 分析	强推理模型（高参数量）
日常功能开发、代码补全、图表组件生成	中等模型（日常开发主力）
批量任务：字典生成、注释补充、格式化	轻量快速模型（控制成本）

具体模型名称建议实测后再定，不同版本迭代较快，以当前可用模型的实际评测结果为准。高成本模型不一定在所有场景优于中等模型，「用对场景」比「用最贵的」更重要。

---

8-3 减少 AI 幻觉：输入质量决定输出质量

模型幻觉（生成不存在的字段名、捏造接口格式）的根本原因通常不是模型能力不足，而是输入上下文不够精确。

核心原则：输入越精确，输出越可控。

具体做法：

• 给 AI 准确完整的上下文：字段含义、业务规则、数据样例
• 先写明需求规格，再让 AI 基于规格执行------AI 的角色是「按规格实现」，而不是「猜你想要什么」
• 利用 Rules 和项目文档（数据字典、领域本体）提供持久上下文，而不是每次对话重新描述背景

---

九、Agent 模式进阶功能

以下功能偏向前后端开发场景，数据开发同学可按需了解。

9-1 多文件编辑与变更管理

Agent 模式修改文件时经过三个阶段：Generating （生成建议）→ Applying （与原文件合并）→ Applied（等待审查）。

点击 View Changes 查看 diff，支持：

• 逐条接受或拒绝单个变更
• 文件级整体接受或拒绝
• 部分修改变更内容后接受

Checkpoints：Agent 模式自动保存操作前的项目快照，随时可一键回滚。

History：每次会话的完整操作审计日志（执行了哪些命令、修改了哪些文件），可通过 Chat 面板图标访问。

9-2 To-dos：复杂任务的执行计划

对于复杂任务，Agent 会自动生成分步 To-do 列表供审查，确认后按步骤执行。进行中可随时追加需求，Agent 会在当前变更基础上更新计划。

进度状态：空圆圈 = 未开始，加载圈 = 进行中，勾选框 = 已完成。

9-3 Codebase Indexing：自动项目理解

Qoder 会自动为项目建立语义索引，实时随文件保存更新。这是 Agent 模式能准确理解现有代码风格、变量命名、架构约定的基础。

注意 ：编辑文件后先按 Ctrl+S 保存再切换到其他文件，避免索引未更新导致 AI 基于旧代码结构生成内容。

9-4 Web Search：实时联网搜索

Agent 模式内置联网搜索能力，处理以下场景时无需手动查文档：

• 第三方库 API 用法和版本变更
• 错误信息的最新解决方案
• 技术方案对比调研

9-5 Terminal 控制

Agent 可直接在终端执行命令（安装依赖、运行测试、构建等），默认每次执行前需要用户确认。可在 Settings 中配置命令白名单 自动通过，例如将 npm test、npm run lint 加入白名单，减少频繁确认中断节奏。

9-6 Code with Spec（SDD 模式）

中大型功能开发建议使用 Quest 工作区的 Code with Spec 模式：先生成结构化 Spec 文档（功能描述、接口约定、边界条件），对齐后再让 AI 基于 Spec 生成代码。

这解决了"AI 猜你想要什么"的问题------Spec 是双方对齐的契约，AI 的角色是按 Spec 实现，而不是自由发挥。

---

十、提示词技巧

10-1 引用代码的正确方式

在编辑器中选中代码再发送消息时，选中内容会自动附加到提问中。但提问时应写 "following code" 而非 "selected code" ------AI 看到的是文本，不知道什么是"选中"。

10-2 用示例代替文字描述

需要 AI 按特定格式输出时，直接提供一个示例比用文字描述格式要求更有效：

效果差 ：把这个测试结果整理成 JSON，包含 name、duration、coverage、success 四个字段......

效果好：把这个测试结果整理成 JSON，格式参考：

{ "name": "测试用例名", "duration": 3434, "coverage": 80, "success": true }

10-3 多轮迭代优于一次超长提示词

一次给 AI 很长的上下文和要求，不如拆成多轮逐步收敛：第一轮建立基础结构，后续轮针对具体问题细化。尤其是业务逻辑复杂的功能，分步让 AI 理解比一次性塞满更稳定。

10-4 清除无关上下文

同一个会话中历史对话会作为上下文持续注入。当新问题与之前的内容无关时，用 /clear context 清除历史，避免旧对话干扰当前任务。

10-5 附加相关文件

Agent 模式中可通过 @ 符号手动指定文件作为上下文------当 AI 对某个功能的理解偏差较大时，直接 @ 相关文件（如现有同类组件、接口定义文件）比在提示词里描述更准确。

---

后续两篇预告

第二篇：提交前的 AI 终审

阿里开源的 Open Code Review（OCR）提供了一套混合架构的代码审查方案：确定性规则管道（NPE 检测、线程安全、SQL 注入等）+ LLM Agent，可集成进 CI/CD 流程，实现 AI 代码的批量终审。内部已在实验，下一篇分享具体使用情况。

第三篇：口径一致性与知识沉淀（管理层视角）

核心问题：为什么不同人用同样的数据，让 AI 分析出的结论有时候不一样？这背后是团队缺少共享的"知识底座"------我们正在探索用 OpenViking 建立结构化的领域知识库，作为 AI 的上下文基础，同时这套结构化知识也与公司当前参与的语料库建设项目有所结合（背景是国家数据局今年发布的《推进行业高质量数据集建设行动方案》）。

---

结语

AI 并不是在取代工程师，而是在重新定义工程师的不可替代点。

过去，开发工作的核心是为了完成需求而写代码 ------代码写得好不好、写得快不快，决定了一个工程师的价值上限。现在这个逻辑正在改变：AI 可以生成代码，但它不知道业务目标是什么、不知道哪个方案更合适、不知道输出的结果对不对。工程师的角色正在从操作者变成指挥者------为了完成目标而指挥 AI，代码只是工具，业务理解和判断能力才是核心。

这也意味着，真正的不可替代点在于：对需求的准确理解、对规范的主动设计、对 AI 输出的批判性校验。会配置 Rules 的人比会写代码的人更能发挥 AI 的价值；能判断 AI 写得对不对的人，才是真正不可替代的质量守门人。

为什么现在就要开始？

从行业数据看，2026 年仍处于企业 AI 编程工具的快速跟随期。先行团队的优势正在通过经验积累、规范沉淀、工具熟练度逐步锁定，但后来者还有窗口追赶。等到一年后回头，那些从今天开始积累使用经验的团队，会和什么都没做的团队拉开真实的差距------不是因为工具更贵，而是因为沉淀了别人没有的上下文资产。

最低成本的起点：配置一套 Rules。把团队最重要的三条约定写进去，从今天的下一次对话开始生效。