Zed Agent 的 Rules 机制演进：从 Rules 库到 Skills 与 Instructions 的迁移实践指南

本指南围绕 Zed（当前仓库为 ze/zed，即 Atom 与 Tree-sitter 作者打造的高性能多人协作者代码编辑器）的 AI Agent 配置体系展开，聚焦 "Rules" 功能的历史定位、被 Skills 与 Instructions 取代的完整脉络、.rules 等兼容指令文件的优先级语义，以及 Zed v1.4.0 起内置的一次性自动迁移机制的实现细节。读完本文，你将掌握如何区分“按需技能”与“常驻指令”，理解项目指令文件的匹配顺序，并知道升级后你的旧 Rules 去了哪里、如何找回。

Rules 是什么：Zed Agent 指令体系的“前身”

在 Zed 的 Agent 体系演进历史上，Rules（规则） 曾是用于约束 Zed Agent 行为的主要载体。它们被存储在用户的 PromptStore（本地 LMDB 数据库）中，分为两类：

• 默认（Default）Rules：自动包含在每一次对话上下文中，用于表达“总是要遵守”的偏好；
• 非默认（Non-Default）Rules：只有当你按名字显式调用时才会注入对话，属于“按需启用”的任务型指令。

从 Zed v1.4.0 起，官方文档明确宣布：按需调用的 Rules 与 Rules Library 已被 Skills 取代。这正是 rules.md 标题中 “Rules (Replaced by Skills)” 的含义——该文档当前的核心任务就是告诉用户如何完成这场迁移，以及哪些兼容文件仍然有效。

Skills 与 Instructions：取代 Rules 的两大新载体

Rules 被拆解为两个定位互补的新概念，理解它们的边界是掌握整个新体系的关键：

• Skills：可复用的任务指令包。每个 Skill 是一个包含 SKILL.md（YAML frontmatter + Markdown 正文）的文件夹，Agent 会在系统提示中看到已安装技能的名称与描述目录，可按需通过 skill 工具加载；用户也可以直接在消息编辑器中用 斜杠命令（/） 或 @ 提及 手动触发。它适合“特定任务时才需要”的指导，例如代码审查清单、发布流程、数据迁移助手。
• Instructions：常驻上下文。以 AGENTS.md 为核心文件，适用于“每次交互都应当生效”的持久指导，例如仓库约定、语气偏好、项目约束。

两者的选用边界在 instructions.md 中的对照表 有明确说明：Instructions 适合“总是开启的指导”，Skills 适合“可复用的任务工作流”。迁移前后的一一映射关系为：可复用、按需的 Rules → Skills；默认、常驻的 Rules → 个人 AGENTS.md；项目级 .rules 文件仍作为兼容指令文件保留支持。

.rules 文件与多 Agent 兼容文件名：第一匹配者生效

虽然 Rules Library 已被取代，但 项目根目录下的 .rules 文件依然受支持，作为兼容性项目指令文件继续工作（详见 instructions.md 的 Project Instructions 一节）。

同时，为了与其他 AI 编码工具兼容，Zed 支持多种常见的指令文件名。加载器按顺序检查，取第一个匹配到的文件，完整顺序为：

1. .rules
2. .cursorrules
3. .windsurfrules
4. .clinerules
5. .github/copilot-instructions.md
6. AGENT.md
7. AGENTS.md
8. CLAUDE.md
9. GEMINI.md

这一顺序并非仅存在于文档中，在源码里被定义为严格对应的常量 RULES_FILE_NAMES，见 crates/prompt_store/src/prompts.rs：

pub const RULES_FILE_NAMES: &[&str] = &[
    ".rules",
    ".cursorrules",
    ".windsurfrules",
    ".clinerules",
    ".github/copilot-instructions.md",
    "AGENT.md",
    "AGENTS.md",
    "CLAUDE.md",
    "GEMINI.md",
];

从源码结构看，扫描到某个文件后，其路径与全文会被封装为 RulesFileContext（包含 path_in_worktree、text 与用于在编辑器中打开的 project_entry_id），并随 WorktreeContext 一并进入 Prompt 渲染上下文（同样见 prompts.rs），最终注入系统提示，成为“项目指令”。这意味着：如果一个项目里同时存在 .rules 与 CLAUDE.md，只会使用 .rules，其余文件会被忽略。

一个值得注意的实例：当前 ze/zed 仓库根目录就同时存在 AGENTS.md、CLAUDE.md、GEMINI.md 三种兼容文件——CLAUDE.md、GEMINI.md 分别面向 Claude Code 与 Gemini CLI 生态，AGENTS.md 则是 Zed（及其他遵循 agents.md 约定的 Agent）的主指令文件。若在 Zed 中打开本仓库，按上述顺序会命中 AGENTS.md。这一点也印证了 instructions.md 中的提醒：外部 Agent 与终端线程（Terminal Threads）会原生读取各自支持的指令文件，不应假设 Zed 的加载器能约束它们。Zed Agent 是否把项目规则文件纳入上下文，还受 Agent 设置中 include project rules files 类开关控制（见 crates/settings_content/src/agent.rs）。

从 Rules 自动迁移：三条去向与一个全局开关

Zed v1.4.0 起，启动时会执行一次性的 “Rules → Skills/AGENTS.md” 迁移。官方文档 rules.md 列出的规则如下：

原内容	迁移去向	说明
非默认（按需）Rules	全局 Skills，位于 ~/.agents/skills/	每个 Rule 生成一个带 disable-model-invocation: true 的 Skill，即模型不会自主调用，仍可用斜杠命令或 @ 提及手动调用
默认（常驻）Rules	追加到全局 AGENTS.md	macOS/Linux 为 ~/.config/zed/AGENTS.md，Windows 为 %APPDATA%\Zed\AGENTS.md
Git 提交提示词等定制内容	同样追加到全局 AGENTS.md	保证每次对话仍自动生效
Rules Library 中的原数据	原样保留、不删除	降级到旧版 Zed 时 Rules 依然完好

源码视角的迁移设计

这场迁移的实际执行者位于 crates/prompt_store/src/rules_to_skills_migration.rs，其模块级注释把设计意图写得非常清楚：

• 非默认 Rules → 全局 Skills：非默认 Rules 原本就只在用户显式按名调用时进入对话，这正好对应 disable-model-invocation: true 的 Skill 语义（仅斜杠触发、绝不自动建议给模型），映射到 ~/.agents/skills/<slug>/SKILL.md。
• 默认 Rules → 全局 AGENTS.md：默认 Rules 原本自动包含于每次对话，而全局 AGENTS.md 会被加载进每一次对话的系统提示，两者行为等价。迁移时每条 Rule 以 “## H2” 标题追加到文件末尾。
• 被定制过的内置提示词（当前主要指 BuiltInPrompt::CommitMessage）：只要用户修改过其正文、偏离了内置 default_content()，迁移就会把定制正文追加在 AGENTS.md 中任何用户默认 Rules 之前；未定制的内置提示词则被跳过，避免用用户从未写过的文字污染 AGENTS.md。
• 迁移生成的 Skill 在 frontmatter 中写入占位描述 "(no description)"——由于迁移产物均为模型禁用（disable-model-invocation: true），模型永远不会读到这段占位文本，它只是为了让 SKILL.md 满足 schema 中 description 非空的要求而存在。

幂等性：进程内原子守卫 + 全局 KVP 标记

迁移必须只执行一次，实现上做了双保险：

1. 全局 GlobalKeyValueStore 中以 "rules_to_skills_migration_done"（常量 MIGRATION_DONE_KEY）记录“本机已考虑过迁移”，跨启动幂等，且同一共享主目录即便横跨多个发布通道也只会迁移一次；
2. 进程内 AtomicBool MIGRATION_TASK_SPAWNED 保证每次进程最多 spawn 一次迁移任务。注释中甚至详细记录了为何需要这层守卫：该函数被挂接在 feature flag 就绪回调上，启动早期该回调可能密集触发多次，若无进程内原子守卫，多个并发任务会竞态创建出成堆的 <rule>-2、<rule>-3 重复目录。

迁移结果（分别迁移到 Skills 与 AGENTS.md 的原始 Rule 标题列表）会以 JSON 形式持久化在 MIGRATION_RESULT_KEY 下，供启动时的 Skills 公告 toast 读取并据此定制文案（仅对真正迁移过 Rules 的用户提及迁移）。

迁移的入口接线在 crates/agent_ui/src/agent_ui.rs：每次启动经 migrate_rules_to_skills_if_needed 触发，并暴露了 rerun_rules_to_skills_migration 命令允许用户强制重跑。在 agent.rs 中也有配套测试覆盖 .rules 被识别为项目规则文件的场景（见 crates/agent/src/agent.rs 中“创建 /a/.rules 会更新项目上下文”的用例）。

迁移之后：手动调用与降级安全

迁移完成后，旧的按需 Rules 变成了一等公民的 Skill：

• 在消息编辑器输入 / 或 @ 并从补全菜单中按名字选中即可注入其指令；
• 被注入的 Skill 会以 crease（折叠条）按钮形式出现在会话线程中，点击可直接打开对应的 SKILL.md 源文件；
• 由于带 disable-model-invocation: true，Agent 不会在你不期望时擅自加载它——这对发布、部署类流程尤其重要。

如果想要让某个迁移来的或自建的 Skill 允许模型自主调用，只需编辑其 SKILL.md frontmatter，删除或改为 disable-model-invocation: false 即可；技能管理与新建入口位于设置中的 AI > Skills 页面（见 skills.md）。

降级安全：迁移刻意设计为非破坏性——PromptStore 中的 Rule 数据行原样保留。因此若你降级回不支持 Skills 的旧版 Zed，旧 UI 中依然能看到并编辑原 Rules，不会丢失任何内容。

给正在升级的用户的操作清单

综合 rules.md 与关联的 skills.md、instructions.md，从旧版 Rules 用户过渡到新体系的建议动作如下：

1. 确认迁移结果：升级到 v1.4.0+ 后正常启动，Zed 会自动完成一次迁移；可在 ~/.agents/skills/ 下看到由旧 Rule 生成、带 disable-model-invocation: true 的 Skill 文件夹。
2. 检查全局指令：打开 ~/.config/zed/AGENTS.md（Linux/macOS）或 %APPDATA%\Zed\AGENTS.md（Windows），确认原默认 Rules 与 Git 提交提示词定制内容已被以 “## ” 标题追加。
3. 改用手动调用：旧的“按名调用非默认 Rule”习惯，对应新的“斜杠命令或 @ 提及 Skill”交互。
4. 项目级 .rules 无需改动：继续留在仓库根目录即可，Zed 会按 RULES_FILE_NAMES 的优先级把它作为项目指令加载。
5. 若想调整归属：需要“总是生效”的内容应移入 Instructions（个人或项目 AGENTS.md），需要“按任务调用”的内容应整理为 Skill——二者取舍可参考 instructions.md 中的对照表。

简而言之，Zed 的 Agent 指令体系已完成从“Rules 单一模型”到“Instructions（常驻）+ Skills（按需）”双轨制的收敛：迁移机制既保证了旧用户的无感升级，又通过非破坏性设计为降级保留了退路。理解 RULES_FILE_NAMES 的匹配顺序与迁移的三条去向，是驾驭这一新体系、并在多 Agent 工具间保持指令一致性的关键。