规则
规则为 AI Agent 提供系统级指令和上下文信息。它们将提示词、工作流程、编码规范等内容打包在一起，便于在团队内管理和共享最佳实践。
CodeBuddy IDE 支持多层级的规则系统，让你能够在不同范围内定义 AI Agent 的行为：
- 项目规则：存储在代码库的
.codebuddy/rules目录中，受版本控制管理，可以与团队成员共享 - 用户规则：全局生效，跨所有项目使用
规则的工作原理
大型语言模型在不同对话轮次之间不会自动保留记忆。规则系统通过在提示级别提供持久、可重用的上下文来弥补这一局限。
当规则被应用时，其内容会被自动加入到发送给模型的上下文信息的开头位置。这确保了 AI Agent 在生成代码、理解编辑意图或协助处理工作流时，能够获得一致的指导原则和行为规范。
提示: 由于规则只会添加到每个会话的开始部分，因此在创建或修改规则后，需要新建对话会话才能让规则生效。当前会话不会自动加载新增或更新的规则。
规则类型
项目规则和用户规则都支持三种应用类型：
| 规则类型 | 描述 | 上下文加载方式 |
|---|---|---|
| 总是 | 应用于每个聊天会话，适合核心编码规范、架构约束和安全要求 | 总是加载规则的原文 |
| 智能体请求 | 当 Agent 根据描述判断其相关时自动应用，适合文档、使用指南和参考资料 | 只加载规则的名称和描述，当模型判断需要时再读取原文 |
| 手动 | 在对话中被 @ 提及时应用（例如：@my-rule），适合特定功能的开发指南、可选的最佳实践 | 不自动加载 |
项目规则
项目规则位于 .codebuddy/rules 中。每条规则对应一个包含 RULE.mdc 文件的文件夹，并纳入版本控制。规则可以通过路径模式限定作用范围，可手动触发，或根据相关性自动引入。
使用项目规则可以：
- 沉淀与你代码库相关的领域知识
- 自动化项目特定的工作流或模板
- 统一风格或架构决策
创建项目规则
打开 CodeBuddy IDE 设置页
在对话框顶部找到「规则」按钮
点击「创建规则」
选择「项目规则」
填写规则名称、类型和内容
规则文件格式
规则文件使用 Markdown 格式，示例如下：
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 设置页
在对话框顶部找到「规则」按钮
点击「创建规则」
选择「用户规则」
填写规则名称、类型和内容
用户规则存储在用户目录中，不会被版本控制系统跟踪。
示例：个人代码风格规则
markdown
---
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 会根据需要读取这些文件：
markdown
## 架构设计
请参考项目的架构文档：`docs/architecture.md`Q: 如何调试规则是否生效？
A: 在对话中询问 AI："当前应用了哪些规则？" AI 会列出当前会话中加载的所有规则。
Q: 可以用规则定义自定义命令吗？
A: 规则主要用于指导 AI 行为。如需自定义命令，建议使用 CodeBuddy 的自定义命令功能。