给项目配 CodeBuddy 规则，踩了几个文档没写清楚的坑。把最后能用的做法记下来，免得以后忘了。

先说为什么写规则

AI 写代码最麻烦的就是它不知道项目的来龙去脉。每个项目总有些代码之外的事——构建方式、目录约定、部署流程——每次新对话都得重新解释一遍，说多了自己也烦。规则就是把这些背景固化下来，让 AI 开工前自己读。

放哪：项目级和用户级分工

规则放三个地方，分工不一样：

  • 项目规则：仓库里 .codebuddy/rules/，跟着 git 走，适合团队共享
  • 用户规则：系统用户目录下，本机所有项目通用，不提交
  • 项目根目录的 CODEBUDDY.md：不用元数据，适合约定特别简单的项目

我现在的用法是：跟具体项目绑定的知识（构建方式、目录约定这类）放项目级；“怎么创建规则"这类任何项目都通用的放用户级，新建项目不用重新写一遍。

文件格式：踩的第一个坑

CodeBuddy 官方有两份文档，说的不一样。IDE 里点"新建规则"生成的是 规则名/RULE.mdc 文件夹结构；命令行文档写的是 .codebuddy/rules/*.md 平铺，支持子目录。我一开始用 RULE.mdc，后来看别的项目发现人家用平铺。

实测两种都能识别。平铺的好处是 git 对比直观、批量处理方便，最后统一成平铺，格式长这样：

---
description: 一句话说明规则职责
alwaysApply: true          # true=总是加载；false=按 globs 按需加载
enabled: true
globs:                     # alwaysApply: false 时才需要
  - "**/*.md"
updatedAt: 2026-08-15T12:00:00.000Z
provider: user
---

# 规则标题
具体内容……

provider: user 表示手写的规则，CodeBuddy 靠这个区分自动生成的记忆文件。

always 别开太多

规则是每次会话开始加载的，全开的话上下文占用很可观。我的判断标准：

  • 每次都必须知道的（项目概述、部署方式、规则索引）设 alwaysApply: true
  • 具体语言、具体文件的规范设 false，再用 globs 限定范围，比如 ["**/*.java"]，只有改 Java 文件时才加载

全开的不超过 5 条，剩下的能按需就按需。

组织：一份索引，一个主题一个文件

规则多了就乱，我定了三条：

  1. 必须有 00-规则索引.md，用表格登记每条规则的编号、领域、管什么，AI 扫一眼就知道该看哪条
  2. 一个文件只写一个主题，塞了多个就拆
  3. 规则之间重合的部分不复制，写"详见 XX"就行，免得改一处忘一处

踩的坑

RULE.mdc 和 .md 两份文档打架。 上面说了，结论是都行，选一个用到头。

删除规则文件会留下 0 字节占位。 IDE 里删有时会被拦，看起来删了其实还在，git 里能看出来。用命令行：

del /f /q "路径\RULE.mdc"
rmdir /q "路径\文件夹"

规则要不要提交。 默认会提交。只自己用的话在 .gitignore 加一行 .codebuddy/ 就行。但注意：规则是会话开始时读的，改完要新开对话才生效。我第一次改完没反应，还以为写错了，其实只是没重开。

写完之后的感受

配规则本身不难，难的是想清楚哪些该写成规则、哪些不该写。我的经验就一条：只写 AI 无法从代码里自己看出来、但项目又特别重要的事——比如"这个仓库不提交构建产物"“部署只走某个 workflow"“配置文件里有个字段有特殊含义"这种。写太多反而占上下文，AI 该读代码的时间全拿去读规则了。

这套怎么建规则的流程我也做成了用户级规则，新建项目让 AI 照着生成就行。

写于 2026 年 8 月，CodeBuddy 界面和文档以后可能改版，以官方文档为准。