规则为 AI Agent 提供系统级指令和上下文信息。它们将提示词、工作流程、编码规范等内容打包在一起，便于在团队内管理和共享最佳实践。

CodeBuddy IDE 支持多层级的规则系统，让你能够在不同范围内定义 AI Agent 的行为：

项目规则：存储在代码库的 .codebuddy/rules 目录中，受版本控制管理，可以与团队成员共享

用户规则：全局生效，跨所有项目使用

规则的工作原理

大型语言模型在不同对话轮次之间不会自动保留记忆。规则系统通过在提示级别提供持久、可重用的上下文来弥补这一局限。

当规则被应用时，其内容会被自动加入到发送给模型的上下文信息的开头位置。这确保了 AI Agent 在生成代码、理解编辑意图或协助处理工作流时，能够获得一致的指导原则和行为规范。

提示: 由于规则只会添加到每个会话的开始部分，因此在创建或修改规则后，需要新建对话会话才能让规则生效。当前会话不会自动加载新增或更新的规则。

规则类型

项目规则和用户规则都支持三种应用类型：

规则类型描述上下文加载方式

总是应用于每个聊天会话，适合核心编码规范、架构约束和安全要求总是加载规则的原文

智能体请求当 Agent 根据描述判断其相关时自动应用，适合文档、使用指南和参考资料只加载规则的名称和描述，当模型判断需要时再读取原文

手动在对话中被 @ 提及时应用（例如：@my-rule），适合特定功能的开发指南、可选的最佳实践不自动加载

项目规则

项目规则位于 .codebuddy/rules 中。每条规则对应一个包含 RULE.mdc 文件的文件夹，并纳入版本控制。规则可以通过路径模式限定作用范围，可手动触发，或根据相关性自动引入。

使用项目规则可以：

沉淀与你代码库相关的领域知识

自动化项目特定的工作流或模板

统一风格或架构决策

创建项目规则

打开 CodeBuddy IDE 设置页

在对话框顶部找到「规则」按钮

点击「创建规则」

选择「项目规则」

填写规则名称、类型和内容

规则文件格式

规则文件使用 Markdown 格式，示例如下：

--- description: project description alwaysApply: false enabled: true updatedAt: 2026-01-13T12:03:50.791Z provider: --- ...rest of the rule content

用户规则

用户规则在本机 CodeBuddy IDE 中全局生效，跨所有项目使用。适合定义个人编码偏好和工作习惯。

创建用户规则

打开 CodeBuddy IDE 设置页

在对话框顶部找到「规则」按钮

点击「创建规则」

选择「用户规则」

填写规则名称、类型和内容

用户规则存储在用户目录中，不会被版本控制系统跟踪。

示例：个人代码风格规则

--- description: 我的个人编码偏好 alwaysApply: true --- # 个人编码风格 ## 通用偏好 - 使用 4 空格缩进（不使用 Tab） - 每行最大长度 100 字符 - 使用单引号而不是双引号（除非必要） - 在语句末尾添加分号 ## 注释风格 - 函数上方必须有 JSDoc 注释 - 复杂逻辑添加行内注释解释 - 注释使用中文 ## 错误处理 - 始终使用 try-catch 包裹可能出错的代码 - 记录详细的错误日志 - 向用户显示友好的错误信息

CODEBUDDY.md

CODEBUDDY.md 是一个帮助 AI 快速了解当前项目的 Markdown 文件。

与项目规则不同，CODEBUDDY.md 是一个没有元数据或复杂配置的纯 Markdown 文件。对于只需要简单、易读指令，而不想引入结构化规则额外负担的项目来说，它是理想选择。

CodeBuddy 支持位于项目根目录中的 CODEBUDDY.md，默认会将原文全文放入上下文。

兼容 AGENTS.md：为保持向后兼容，当项目根目录存在 AGENTS.md 而不存在 CODEBUDDY.md 时，CodeBuddy 将自动加载 AGENTS.md 的完整内容到对话上下文中。

最佳实践

好的规则应当聚焦、可操作且范围明确。

将规则控制在 500 行以内

将较大的规则拆分为多个可组合的规则

提供具体示例或参考文件

避免模糊的指导，像写清晰的内部文档那样写规则

在聊天中重复使用提示时，复用已有规则

常见问题

Q: 规则太多会影响性能吗？

A: CodeBuddy IDE 会智能加载规则。只有 alwaysApply: true 的规则会始终加载，其他规则按需加载。建议：

核心规范设置为 always（3-5 个）

其他规则设置为 manual 或 requested

Q: 规则内容可以引用外部文件吗？

A: 可以在规则中提及文件路径，AI 会根据需要读取这些文件：

## 架构设计 请参考项目的架构文档：`docs/architecture.md`

Q: 如何调试规则是否生效？

A: 在对话中询问 AI："当前应用了哪些规则？" AI 会列出当前会话中加载的所有规则。

Q: 可以用规则定义自定义命令吗？

A: 规则主要用于指导 AI 行为。如需自定义命令，建议使用 CodeBuddy 的自定义命令功能。