CodeBuddy 上下文管理四大机制详解ignore / permissions / rules / CODEBUDDY.mdAI 编程助手的回答质量80% 取决于你喂给它的上下文质量。CodeBuddy 提供了四套上下文管理机制各司其职。本文从原理到实战一次讲透。目录总览四层机制一张图.codebuddy/ignore— 上下文过滤器permissions— 权限守门员CODEBUDDY.mdrules/*.md— 上下文注入器.gitignore— 版本控制边界四者协同完整配置实战一、总览四层机制一张图┌─────────────────────────────────────────────────┐ │ 用户提问 │ └──────────────────┬──────────────────────────────┘ ▼ ┌──────────────────────────────┐ │ ① .codebuddy/ignore │ ← 先过滤排除 index/搜索 │ 上下文过滤器 │ └──────────────┬───────────────┘ ▼ ┌──────────────────────────────┐ │ ② CODEBUDDY.md → rules/* │ ← 再注入补项目规范/约定 │ 上下文注入器 │ └──────────────┬───────────────┘ ▼ ┌──────────────────────────────┐ │ ③ AI 拿到干净精准的上下文 │ ← 开始分析和工具调用 │ 理解项目 → 选择工具 │ └──────────────┬───────────────┘ ▼ ┌──────────────────────────────┐ │ ④ permissions 权限校验 │ ← 执行前允许/拒绝/询问 │ 权限守门员 │ └──────────────┬───────────────┘ ▼ 工具实际执行机制作用阶段核心职责类比.codebuddy/ignore上下文收集前排除无关文件门禁 — 不让不相关的人进来permissions工具执行前控制工具访问保镖 — 进来了也不能乱动CODEBUDDY.mdrules/*.md上下文构建中注入项目知识说明书 — 告诉 AI 项目怎么运转.gitignore版本控制时排除提交文件仓库管理员 — 与 AI 无关二、.codebuddy/ignore— 上下文过滤器2.1 它是干什么的让 CodeBuddy 在自动收集项目上下文时把指定文件当作不存在。# .codebuddy/ignore node_modules/ dist/ *.log .env2.2 工作原理CodeBuddy 每次接收用户请求后会先做一个项目快照你看到的project_layout然后 AI 通过search_file、search_content、list_dir等工具进一步了解项目。.codebuddy/ignore在这两个阶段都会介入项目快照采集 ──→ ignore 过滤 ──→ 干净快照给 AI 工具调用返回 ──→ ignore 过滤 ──→ 干净结果给 AI 显式 read_file ──→ **不拦截** ──→ 直接返回内容2.3 生效范围场景是否被过滤search_file(*.js)✅ 忽略匹配的 js 不出现在结果中search_content(function)✅ 忽略目录/文件中的匹配不返回list_dir(./)✅ 忽略的目录/文件不显示read_file(./dist/bundle.js)❌ 指定全路径仍可读取AI 主动 grep 搜索✅ 不匹配忽略的路径write_to_file(./dist/x.js)❌ 不阻止写入2.4 典型配置模板# .codebuddy/ignore — 通用推荐配置 # ── 依赖体量最大的噪音源── node_modules/ vendor/ .venv/ venv/ __pycache__/ *.pyc # ── 构建产物 ── dist/ build/ target/ out/ .next/ .nuxt/ # ── 编译中间文件 ── *.o *.obj *.class *.exe *.dll *.so *.a *.lib # ── 固件/嵌入式产物 ── *.hex *.bin *.elf *.map # ── 日志与缓存 ── *.log .cache/ *.tsbuildinfo # ── 锁文件 ── package-lock.json yarn.lock pnpm-lock.yaml # ── 密钥与本地配置 ── .env .env.* *.pem *.key *.secret # ── IDE 配置 ── .idea/ .vscode/ *.swp *.swo .DS_Store Thumbs.db2.5 关键认知ignore 是好意提醒不是强制禁令。它让 AI “自动看不见”但你说打开那个文件AI 照样能读到。三、permissions— 权限守门员3.1 它是干什么的控制 AI 能执行哪些工具操作。可以精细到允许执行npm run test但禁止修改.env 这种粒度。配置文件位置.codebuddy/settings.json3.2 核心结构{permissions:{allow:[Bash(npm run lint),Bash(npm run test:*),Read(~/.zshrc)],ask:[Bash(git push:*),Write(**/*.env)],deny:[Bash(rm:*),Bash(sudo:*),Read(**/*.pem),Write(**/*.secret)]}}3.3 三种权限等级等级含义使用场景allow自动放行无需询问高频安全操作lint、test、读公共配置ask每次执行前弹窗询问有风险但合理的操作git push、修改敏感文件deny直接拒绝无法执行高危操作rm 删除、sudo、读写密钥文件3.4 权限规则语法操作类型(匹配模式)操作类型含义Bash(...)shell 命令Read(...)读取文件Write(...)写入/修改文件Edit(...)编辑文件匹配模式支持通配符{Bash(npm run test:*):匹配 npm run test:unit、npm run test:e2e 等,Read(**/*.config.js):匹配任意目录下的 *.config.js,Write(**/*.env):匹配任意目录下的 .env 系列文件}3.5 实战配置安全优先型{permissions:{allow:[Bash(npm run lint),Bash(npm run test),Bash(npm run build),Bash(git status),Bash(git diff),Bash(git log:*)],ask:[Bash(git commit:*),Bash(git push:*),Bash(npm install:*),Write(**/*.env),Write(**/*.config.*)],deny:[Bash(rm -rf:*),Bash(sudo:*),Bash(curl:*),Bash(wget:*),Read(**/*.pem),Read(**/*.key),Write(**/*.secret)]}}3.6 实战配置高效协作型{permissions:{allow:[Bash(npm:*),Bash(git:*),Bash(python:*),Bash(ls),Bash(cat:*),Read(**/*),Write(**/*)],ask:[Bash(git push:*),Bash(docker:*),Write(**/*.env)],deny:[Bash(rm -rf /:*),Bash(sudo:*),Bash(shutdown:*),Bash(reboot:*)]}}3.7 permissions vs ignore 对比维度permissions.deny.codebuddy/ignore作用层面工具执行控制上下文发现控制阻止read_file✅ 可以❌ 不能阻止search_file❌只控制读写✅ 可以阻止write_file✅ 可以❌ 不能阻止 shell 命令✅ 可以❌ 不能适用场景安全控制噪音过滤一句话ignore 管AI 看到什么permissions 管AI 能做什么。四、CODEBUDDY.mdrules/*.md— 上下文注入器4.1 它是干什么的主动告诉 AI 你的项目是怎么运转的— 用什么技术栈、遵循什么代码规范、有哪些约定俗成的做法。4.2 两种文件类型文件位置作用范围用途CODEBUDDY.md项目根目录可多层当前目录及子目录项目核心约定、技术栈说明rules/*.md.codebuddy/rules/全局项目级分模块规则每个文件一个主题~/.codebuddy/CODEBUDDY.md用户主目录所有项目个人偏好、跨项目的全局约定4.3 加载顺序会话启动 │ ├── ① 加载 ~/.codebuddy/CODEBUDDY.md 用户级全局偏好 ├── ② 加载 ~/.codebuddy/rules/*.md 用户级规则 ├── ③ 从工作目录向上递归加载 CODEBUDDY.md 项目级主约定 └── ④ 加载 .codebuddy/rules/*.md 项目级规则4.4 CODEBUDDY.md 怎么写# 项目概述 这是一个基于 React 18 TypeScript Vite 的中后台管理系统。 ## 技术栈 - 框架React 18 TypeScript 5 - 构建Vite 5 - 状态管理Zustand - UI 库Ant Design 5 - 路由React Router 6 - 请求Axios React Query ## 目录结构约定 - src/pages/ — 页面组件每个页面一个文件夹 - src/components/ — 通用组件 - src/hooks/ — 自定义 Hooks - src/services/ — API 请求函数 - src/types/ — TypeScript 类型定义 - src/utils/ — 工具函数 ## 代码规范 - 组件使用函数式组件 Hooks不使用 Class 组件 - 文件命名组件用 PascalCase工具函数用 camelCase - 每个组件文件对应一个 .module.less 样式文件 - 不允许使用 any 类型除非有明确理由并加注释 - API 请求统一通过 src/services/request.ts 封装 ## 命名约定 - useState 变量[xxx, setXxx] - 事件处理函数handleXxx - 布尔变量isXxx / hasXxx / canXxx ## 测试 - 单元测试Vitest React Testing Library - 要求核心工具函数覆盖率 ≥ 90%4.5 rules/*.md 怎么写分模块.codebuddy/rules/api-conventions.md# API 调用规范 - 所有 API 调用必须通过 src/services/ 下的模块进行 - 使用 React Query 的 useQuery / useMutation 管理服务端状态 - 错误处理统一在 src/services/request.ts 的拦截器中处理 - 请求参数和响应类型必须定义在 src/types/api.ts 中 - 禁止在组件中直接调用 axios.codebuddy/rules/git-commit.md# Git 提交规范 - 使用 Conventional Commits 格式type(scope): description - 允许的 typefeat, fix, docs, style, refactor, test, chore - scope 使用小写英文多词用短横线连接 - 禁止提交 console.log调试完成后必须删除 - 禁止提交包含 TODO 且无对应 Issue 号的代码.codebuddy/rules/styling.md# 样式规范 - 使用 CSS Modules.module.less - 颜色使用设计系统变量不写硬编码色值 - 响应式断点768px平板/ 1024px桌面/ 1440px宽屏 - 禁止使用 !important除非覆盖第三方库样式 - 禁止内联样式style prop4.6 实际效果对比没用 CODEBUDDY.md 时你创建一个用户列表页面 AI生成一个用了 Vue 写法的组件... AI用了 axios 直接调用而不是项目的 request 封装... AI用了 CSS-in-JS 但项目用的是 CSS Modules...用了 CODEBUDDY.md 后你创建一个用户列表页面 AI看了约定好用 React 18 TypeScript AI看了规范用 Ant Design 的 Table 组件 AI看了规范API 调用走 services/ 模块 AI看了规范样式用 .module.less → 一次生成直接就能用4.7 rules 的控制字段每个 rules 文件可以用 YAML frontmatter 控制加载行为--- enabled: true # 是否启用 alwaysApply: true # 是否始终加载到上下文false 时需手动 引用 priority: high # 优先级 description: API 调用规范 # 描述 --- # API 调用规范 ...alwaysApply: true→ 每次会话自动注入alwaysApply: false→ 只在用户手动rules/api-conventions引用时才加载五、.gitignore— 版本控制边界5.1 它跟 AI 有什么关系直接关系基本没有。.gitignore是给 Git 看的不是给 CodeBuddy 看的。但它有间接影响间接影响说明语义参考.gitignore中忽略的内容node_modules/、dist/通常也应该在.codebuddy/ignore中忽略上下文提示如果你没配.codebuddy/ignoreAI 看到的项目树可能会非常臃肿工程惯例.gitignore反映了你的非源码边界这个边界通常也适用于 AI 分析5.2 典型配置# .gitignore # 依赖 node_modules/ .python-version # 构建产物 dist/ build/ *.tsbuildinfo # 环境变量 .env .env.local # IDE .idea/ .vscode/ *.swp # 系统 .DS_Store Thumbs.db5.3 .gitignore vs .codebuddy/ignore.gitignore.codebuddy/ignore谁读取GitCodeBuddy作用排除文件不提交排除文件不索引语法glob 模式相同语法影响范围版本控制操作AI 上下文发现典型重叠node_modules、dist、.env通常应该保持一致实践建议.codebuddy/ignore至少覆盖.gitignore的所有规则再额外加入编译中间产物.o、.class等不在 gitignore 但会污染上下文的内容。六、四者协同完整配置实战6.1 项目根目录文件结构my-project/ ├── .codebuddy/ │ ├── ignore # ← 上下文过滤器 │ ├── settings.json # ← 权限守卫含 permissions │ └── rules/ │ ├── api.md # ← 规则API 调用约定 │ ├── git.md # ← 规则Git 提交规范 │ └── style.md # ← 规则样式规范 ├── CODEBUDDY.md # ← 项目级主约定 ├── .gitignore # ← 版本控制边界 ├── src/ ├── package.json └── ...6.2 各文件内容.codebuddy/ignorenode_modules/ dist/ build/ .next/ *.log .env .env.* .idea/ .vscode/ *.tsbuildinfo package-lock.json yarn.lock .cache/ coverage/.codebuddy/settings.json{permissions:{allow:[Bash(npm run lint),Bash(npm run test:*),Bash(npm run build),Bash(git status),Bash(git diff),Read(**/*)],ask:[Bash(git push:*),Bash(npm install:*),Write(**/*.env)],deny:[Bash(rm -rf:*),Bash(sudo:*),Bash(curl:*),Read(**/*.pem),Read(**/*.key)]}}CODEBUDDY.md# 项目Admin Dashboard ## 技术栈 React 18 TypeScript 5 Vite 5 Ant Design 5 ## 目录约定 - src/pages/ 页面 | src/components/ 通用组件 - src/services/ API | src/hooks/ 自定义 Hook - src/types/ 类型定义 | src/utils/ 工具函数 ## 规范 - 函数式组件 Hooks禁止 Class 组件 - 禁止 any 类型 - CSS Modules Less - API 统一走 src/services/request.ts.codebuddy/rules/api.md# API 规范 - 使用 React Query 管理服务端状态 - 请求类型定义在 src/types/api.ts - 禁止组件内直接 axios 调用.gitignorenode_modules/ dist/ .env .env.local .idea/ .vscode/ .DS_Store6.3 一次完整请求的运转过程你帮我加一个订单列表页面 Step 1 ── .codebuddy/ignore 过滤 → AI 看到的项目快照中没有 node_modules/、dist/、 日志文件等噪音 Step 2 ── CODEBUDDY.md rules 注入 → AI 知道React 18 TS Ant Design CSS Modules → AI 知道API 走 services/类型定义在 types/ → AI 知道样式用 .module.less Step 3 ── AI 规划代码结构 → 创建 src/pages/Orders/index.tsx → 创建 src/pages/Orders/index.module.less → 创建 src/services/orders.ts → 创建 src/types/api.ts追加订单类型 Step 4 ── permissions 校验每个操作 → read_file(src/services/request.ts) → allow ✅ → write_file(src/pages/Orders/index.tsx) → allow ✅ → bash(npm run test) → allow ✅ → 全程无违规操作一次搞定七、速查表问题用哪个机制AI 总被 node_modules 里代码干扰.codebuddy/ignore不想让 AI 执行rm命令permissions.denyAI 不知道我项目用什么框架CODEBUDDY.mdAI 总写出不符合团队规范的代码.codebuddy/rules/*.mdAI 访问了我的.env密钥文件permissions.deny.codebuddy/ignore项目用了特殊目录结构AI 找不到文件CODEBUDDY.md中写清楚AI 每次 git push 都问我很烦permissions.allow中加Bash(git push)想让不同模块有不同规则.codebuddy/rules/分文件管理个人偏好在所有项目中生效~/.codebuddy/CODEBUDDY.mdAI 读取了大体积固件镜像导致卡顿.codebuddy/ignore加*.hex*.bin八、总结机制一句话配置位置ignore“这些文件你别看”.codebuddy/ignorepermissions“这些操作你不能做”.codebuddy/settings.jsonCODEBUDDY.md“我们项目是这样跑的”项目根目录rules“这个模块你得这样写”.codebuddy/rules/*.md.gitignore“这些文件别提交到 Git”项目根目录核心原则ignore 做减法减少噪音CODEBUDDY.md/rules 做加法注入知识permissions 做守卫控制行为。三层配合AI 才能既高效又安全地为你工作。
CodeBuddy 上下文管理四大机制详解ignore / permissions / rules / CODEBUDDY.mdAI 编程助手的回答质量80% 取决于你喂给它的上下文质量。CodeBuddy 提供了四套上下文管理机制各司其职。本文从原理到实战一次讲透。目录总览四层机制一张图.codebuddy/ignore— 上下文过滤器permissions— 权限守门员CODEBUDDY.mdrules/*.md— 上下文注入器.gitignore— 版本控制边界四者协同完整配置实战一、总览四层机制一张图┌─────────────────────────────────────────────────┐ │ 用户提问 │ └──────────────────┬──────────────────────────────┘ ▼ ┌──────────────────────────────┐ │ ① .codebuddy/ignore │ ← 先过滤排除 index/搜索 │ 上下文过滤器 │ └──────────────┬───────────────┘ ▼ ┌──────────────────────────────┐ │ ② CODEBUDDY.md → rules/* │ ← 再注入补项目规范/约定 │ 上下文注入器 │ └──────────────┬───────────────┘ ▼ ┌──────────────────────────────┐ │ ③ AI 拿到干净精准的上下文 │ ← 开始分析和工具调用 │ 理解项目 → 选择工具 │ └──────────────┬───────────────┘ ▼ ┌──────────────────────────────┐ │ ④ permissions 权限校验 │ ← 执行前允许/拒绝/询问 │ 权限守门员 │ └──────────────┬───────────────┘ ▼ 工具实际执行机制作用阶段核心职责类比.codebuddy/ignore上下文收集前排除无关文件门禁 — 不让不相关的人进来permissions工具执行前控制工具访问保镖 — 进来了也不能乱动CODEBUDDY.mdrules/*.md上下文构建中注入项目知识说明书 — 告诉 AI 项目怎么运转.gitignore版本控制时排除提交文件仓库管理员 — 与 AI 无关二、.codebuddy/ignore— 上下文过滤器2.1 它是干什么的让 CodeBuddy 在自动收集项目上下文时把指定文件当作不存在。# .codebuddy/ignore node_modules/ dist/ *.log .env2.2 工作原理CodeBuddy 每次接收用户请求后会先做一个项目快照你看到的project_layout然后 AI 通过search_file、search_content、list_dir等工具进一步了解项目。.codebuddy/ignore在这两个阶段都会介入项目快照采集 ──→ ignore 过滤 ──→ 干净快照给 AI 工具调用返回 ──→ ignore 过滤 ──→ 干净结果给 AI 显式 read_file ──→ **不拦截** ──→ 直接返回内容2.3 生效范围场景是否被过滤search_file(*.js)✅ 忽略匹配的 js 不出现在结果中search_content(function)✅ 忽略目录/文件中的匹配不返回list_dir(./)✅ 忽略的目录/文件不显示read_file(./dist/bundle.js)❌ 指定全路径仍可读取AI 主动 grep 搜索✅ 不匹配忽略的路径write_to_file(./dist/x.js)❌ 不阻止写入2.4 典型配置模板# .codebuddy/ignore — 通用推荐配置 # ── 依赖体量最大的噪音源── node_modules/ vendor/ .venv/ venv/ __pycache__/ *.pyc # ── 构建产物 ── dist/ build/ target/ out/ .next/ .nuxt/ # ── 编译中间文件 ── *.o *.obj *.class *.exe *.dll *.so *.a *.lib # ── 固件/嵌入式产物 ── *.hex *.bin *.elf *.map # ── 日志与缓存 ── *.log .cache/ *.tsbuildinfo # ── 锁文件 ── package-lock.json yarn.lock pnpm-lock.yaml # ── 密钥与本地配置 ── .env .env.* *.pem *.key *.secret # ── IDE 配置 ── .idea/ .vscode/ *.swp *.swo .DS_Store Thumbs.db2.5 关键认知ignore 是好意提醒不是强制禁令。它让 AI “自动看不见”但你说打开那个文件AI 照样能读到。三、permissions— 权限守门员3.1 它是干什么的控制 AI 能执行哪些工具操作。可以精细到允许执行npm run test但禁止修改.env 这种粒度。配置文件位置.codebuddy/settings.json3.2 核心结构{permissions:{allow:[Bash(npm run lint),Bash(npm run test:*),Read(~/.zshrc)],ask:[Bash(git push:*),Write(**/*.env)],deny:[Bash(rm:*),Bash(sudo:*),Read(**/*.pem),Write(**/*.secret)]}}3.3 三种权限等级等级含义使用场景allow自动放行无需询问高频安全操作lint、test、读公共配置ask每次执行前弹窗询问有风险但合理的操作git push、修改敏感文件deny直接拒绝无法执行高危操作rm 删除、sudo、读写密钥文件3.4 权限规则语法操作类型(匹配模式)操作类型含义Bash(...)shell 命令Read(...)读取文件Write(...)写入/修改文件Edit(...)编辑文件匹配模式支持通配符{Bash(npm run test:*):匹配 npm run test:unit、npm run test:e2e 等,Read(**/*.config.js):匹配任意目录下的 *.config.js,Write(**/*.env):匹配任意目录下的 .env 系列文件}3.5 实战配置安全优先型{permissions:{allow:[Bash(npm run lint),Bash(npm run test),Bash(npm run build),Bash(git status),Bash(git diff),Bash(git log:*)],ask:[Bash(git commit:*),Bash(git push:*),Bash(npm install:*),Write(**/*.env),Write(**/*.config.*)],deny:[Bash(rm -rf:*),Bash(sudo:*),Bash(curl:*),Bash(wget:*),Read(**/*.pem),Read(**/*.key),Write(**/*.secret)]}}3.6 实战配置高效协作型{permissions:{allow:[Bash(npm:*),Bash(git:*),Bash(python:*),Bash(ls),Bash(cat:*),Read(**/*),Write(**/*)],ask:[Bash(git push:*),Bash(docker:*),Write(**/*.env)],deny:[Bash(rm -rf /:*),Bash(sudo:*),Bash(shutdown:*),Bash(reboot:*)]}}3.7 permissions vs ignore 对比维度permissions.deny.codebuddy/ignore作用层面工具执行控制上下文发现控制阻止read_file✅ 可以❌ 不能阻止search_file❌只控制读写✅ 可以阻止write_file✅ 可以❌ 不能阻止 shell 命令✅ 可以❌ 不能适用场景安全控制噪音过滤一句话ignore 管AI 看到什么permissions 管AI 能做什么。四、CODEBUDDY.mdrules/*.md— 上下文注入器4.1 它是干什么的主动告诉 AI 你的项目是怎么运转的— 用什么技术栈、遵循什么代码规范、有哪些约定俗成的做法。4.2 两种文件类型文件位置作用范围用途CODEBUDDY.md项目根目录可多层当前目录及子目录项目核心约定、技术栈说明rules/*.md.codebuddy/rules/全局项目级分模块规则每个文件一个主题~/.codebuddy/CODEBUDDY.md用户主目录所有项目个人偏好、跨项目的全局约定4.3 加载顺序会话启动 │ ├── ① 加载 ~/.codebuddy/CODEBUDDY.md 用户级全局偏好 ├── ② 加载 ~/.codebuddy/rules/*.md 用户级规则 ├── ③ 从工作目录向上递归加载 CODEBUDDY.md 项目级主约定 └── ④ 加载 .codebuddy/rules/*.md 项目级规则4.4 CODEBUDDY.md 怎么写# 项目概述 这是一个基于 React 18 TypeScript Vite 的中后台管理系统。 ## 技术栈 - 框架React 18 TypeScript 5 - 构建Vite 5 - 状态管理Zustand - UI 库Ant Design 5 - 路由React Router 6 - 请求Axios React Query ## 目录结构约定 - src/pages/ — 页面组件每个页面一个文件夹 - src/components/ — 通用组件 - src/hooks/ — 自定义 Hooks - src/services/ — API 请求函数 - src/types/ — TypeScript 类型定义 - src/utils/ — 工具函数 ## 代码规范 - 组件使用函数式组件 Hooks不使用 Class 组件 - 文件命名组件用 PascalCase工具函数用 camelCase - 每个组件文件对应一个 .module.less 样式文件 - 不允许使用 any 类型除非有明确理由并加注释 - API 请求统一通过 src/services/request.ts 封装 ## 命名约定 - useState 变量[xxx, setXxx] - 事件处理函数handleXxx - 布尔变量isXxx / hasXxx / canXxx ## 测试 - 单元测试Vitest React Testing Library - 要求核心工具函数覆盖率 ≥ 90%4.5 rules/*.md 怎么写分模块.codebuddy/rules/api-conventions.md# API 调用规范 - 所有 API 调用必须通过 src/services/ 下的模块进行 - 使用 React Query 的 useQuery / useMutation 管理服务端状态 - 错误处理统一在 src/services/request.ts 的拦截器中处理 - 请求参数和响应类型必须定义在 src/types/api.ts 中 - 禁止在组件中直接调用 axios.codebuddy/rules/git-commit.md# Git 提交规范 - 使用 Conventional Commits 格式type(scope): description - 允许的 typefeat, fix, docs, style, refactor, test, chore - scope 使用小写英文多词用短横线连接 - 禁止提交 console.log调试完成后必须删除 - 禁止提交包含 TODO 且无对应 Issue 号的代码.codebuddy/rules/styling.md# 样式规范 - 使用 CSS Modules.module.less - 颜色使用设计系统变量不写硬编码色值 - 响应式断点768px平板/ 1024px桌面/ 1440px宽屏 - 禁止使用 !important除非覆盖第三方库样式 - 禁止内联样式style prop4.6 实际效果对比没用 CODEBUDDY.md 时你创建一个用户列表页面 AI生成一个用了 Vue 写法的组件... AI用了 axios 直接调用而不是项目的 request 封装... AI用了 CSS-in-JS 但项目用的是 CSS Modules...用了 CODEBUDDY.md 后你创建一个用户列表页面 AI看了约定好用 React 18 TypeScript AI看了规范用 Ant Design 的 Table 组件 AI看了规范API 调用走 services/ 模块 AI看了规范样式用 .module.less → 一次生成直接就能用4.7 rules 的控制字段每个 rules 文件可以用 YAML frontmatter 控制加载行为--- enabled: true # 是否启用 alwaysApply: true # 是否始终加载到上下文false 时需手动 引用 priority: high # 优先级 description: API 调用规范 # 描述 --- # API 调用规范 ...alwaysApply: true→ 每次会话自动注入alwaysApply: false→ 只在用户手动rules/api-conventions引用时才加载五、.gitignore— 版本控制边界5.1 它跟 AI 有什么关系直接关系基本没有。.gitignore是给 Git 看的不是给 CodeBuddy 看的。但它有间接影响间接影响说明语义参考.gitignore中忽略的内容node_modules/、dist/通常也应该在.codebuddy/ignore中忽略上下文提示如果你没配.codebuddy/ignoreAI 看到的项目树可能会非常臃肿工程惯例.gitignore反映了你的非源码边界这个边界通常也适用于 AI 分析5.2 典型配置# .gitignore # 依赖 node_modules/ .python-version # 构建产物 dist/ build/ *.tsbuildinfo # 环境变量 .env .env.local # IDE .idea/ .vscode/ *.swp # 系统 .DS_Store Thumbs.db5.3 .gitignore vs .codebuddy/ignore.gitignore.codebuddy/ignore谁读取GitCodeBuddy作用排除文件不提交排除文件不索引语法glob 模式相同语法影响范围版本控制操作AI 上下文发现典型重叠node_modules、dist、.env通常应该保持一致实践建议.codebuddy/ignore至少覆盖.gitignore的所有规则再额外加入编译中间产物.o、.class等不在 gitignore 但会污染上下文的内容。六、四者协同完整配置实战6.1 项目根目录文件结构my-project/ ├── .codebuddy/ │ ├── ignore # ← 上下文过滤器 │ ├── settings.json # ← 权限守卫含 permissions │ └── rules/ │ ├── api.md # ← 规则API 调用约定 │ ├── git.md # ← 规则Git 提交规范 │ └── style.md # ← 规则样式规范 ├── CODEBUDDY.md # ← 项目级主约定 ├── .gitignore # ← 版本控制边界 ├── src/ ├── package.json └── ...6.2 各文件内容.codebuddy/ignorenode_modules/ dist/ build/ .next/ *.log .env .env.* .idea/ .vscode/ *.tsbuildinfo package-lock.json yarn.lock .cache/ coverage/.codebuddy/settings.json{permissions:{allow:[Bash(npm run lint),Bash(npm run test:*),Bash(npm run build),Bash(git status),Bash(git diff),Read(**/*)],ask:[Bash(git push:*),Bash(npm install:*),Write(**/*.env)],deny:[Bash(rm -rf:*),Bash(sudo:*),Bash(curl:*),Read(**/*.pem),Read(**/*.key)]}}CODEBUDDY.md# 项目Admin Dashboard ## 技术栈 React 18 TypeScript 5 Vite 5 Ant Design 5 ## 目录约定 - src/pages/ 页面 | src/components/ 通用组件 - src/services/ API | src/hooks/ 自定义 Hook - src/types/ 类型定义 | src/utils/ 工具函数 ## 规范 - 函数式组件 Hooks禁止 Class 组件 - 禁止 any 类型 - CSS Modules Less - API 统一走 src/services/request.ts.codebuddy/rules/api.md# API 规范 - 使用 React Query 管理服务端状态 - 请求类型定义在 src/types/api.ts - 禁止组件内直接 axios 调用.gitignorenode_modules/ dist/ .env .env.local .idea/ .vscode/ .DS_Store6.3 一次完整请求的运转过程你帮我加一个订单列表页面 Step 1 ── .codebuddy/ignore 过滤 → AI 看到的项目快照中没有 node_modules/、dist/、 日志文件等噪音 Step 2 ── CODEBUDDY.md rules 注入 → AI 知道React 18 TS Ant Design CSS Modules → AI 知道API 走 services/类型定义在 types/ → AI 知道样式用 .module.less Step 3 ── AI 规划代码结构 → 创建 src/pages/Orders/index.tsx → 创建 src/pages/Orders/index.module.less → 创建 src/services/orders.ts → 创建 src/types/api.ts追加订单类型 Step 4 ── permissions 校验每个操作 → read_file(src/services/request.ts) → allow ✅ → write_file(src/pages/Orders/index.tsx) → allow ✅ → bash(npm run test) → allow ✅ → 全程无违规操作一次搞定七、速查表问题用哪个机制AI 总被 node_modules 里代码干扰.codebuddy/ignore不想让 AI 执行rm命令permissions.denyAI 不知道我项目用什么框架CODEBUDDY.mdAI 总写出不符合团队规范的代码.codebuddy/rules/*.mdAI 访问了我的.env密钥文件permissions.deny.codebuddy/ignore项目用了特殊目录结构AI 找不到文件CODEBUDDY.md中写清楚AI 每次 git push 都问我很烦permissions.allow中加Bash(git push)想让不同模块有不同规则.codebuddy/rules/分文件管理个人偏好在所有项目中生效~/.codebuddy/CODEBUDDY.mdAI 读取了大体积固件镜像导致卡顿.codebuddy/ignore加*.hex*.bin八、总结机制一句话配置位置ignore“这些文件你别看”.codebuddy/ignorepermissions“这些操作你不能做”.codebuddy/settings.jsonCODEBUDDY.md“我们项目是这样跑的”项目根目录rules“这个模块你得这样写”.codebuddy/rules/*.md.gitignore“这些文件别提交到 Git”项目根目录核心原则ignore 做减法减少噪音CODEBUDDY.md/rules 做加法注入知识permissions 做守卫控制行为。三层配合AI 才能既高效又安全地为你工作。
