企业官网建设流程全解析

CodeBuddy 上下文管理四大机制详解：ignore / permissions / rules / CODEBUDDY.md

AI 编程助手的回答质量，80% 取决于你喂给它的上下文质量。CodeBuddy 提供了四套上下文管理机制，各司其职。本文从原理到实战，一次讲透。

目录

1. 总览：四层机制一张图
2. .codebuddy/ignore— 上下文过滤器
3. permissions— 权限守门员
4. CODEBUDDY.md+rules/*.md— 上下文注入器
5. .gitignore— 版本控制边界
6. 四者协同：完整配置实战

一、总览：四层机制一张图

┌─────────────────────────────────────────────────┐ │ 用户提问 │ └──────────────────┬──────────────────────────────┘ ▼ ┌──────────────────────────────┐ │ ① .codebuddy/ignore │ ← 先过滤：排除 index/搜索 │ 上下文过滤器 │ └──────────────┬───────────────┘ ▼ ┌──────────────────────────────┐ │ ② CODEBUDDY.md → rules/* │ ← 再注入：补项目规范/约定 │ 上下文注入器 │ └──────────────┬───────────────┘ ▼ ┌──────────────────────────────┐ │ ③ AI 拿到干净+精准的上下文 │ ← 开始分析和工具调用 │ 理解项目 → 选择工具 │ └──────────────┬───────────────┘ ▼ ┌──────────────────────────────┐ │ ④ permissions 权限校验 │ ← 执行前：允许/拒绝/询问 │ 权限守门员 │ └──────────────┬───────────────┘ ▼ 工具实际执行

二、.codebuddy/ignore— 上下文过滤器

2.1 它是干什么的

让 CodeBuddy 在自动收集项目上下文时，把指定文件当作不存在。

# .codebuddy/ignore node_modules/ dist/ *.log .env

2.2 工作原理

CodeBuddy 每次接收用户请求后，会先做一个项目快照（你看到的project_layout），然后 AI 通过search_file、search_content、list_dir等工具进一步了解项目。

.codebuddy/ignore在这两个阶段都会介入：

项目快照采集 ──→ ignore 过滤 ──→ 干净快照给 AI 工具调用返回 ──→ ignore 过滤 ──→ 干净结果给 AI 显式 read_file ──→ **不拦截** ──→ 直接返回内容

2.3 生效范围

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.db

2.5 关键认知

ignore 是好意提醒，不是强制禁令。它让 AI “自动看不见”，但你说"打开那个文件"，AI 照样能读到。

三、permissions— 权限守门员

3.1 它是干什么的

控制 AI 能执行哪些工具操作。可以精细到"允许执行npm run test，但禁止修改.env" 这种粒度。

配置文件位置：.codebuddy/settings.json

3.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 三种权限等级

3.4 权限规则语法

操作类型(匹配模式)

匹配模式支持通配符：

{"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 对比

一句话：ignore 管"AI 看到什么"，permissions 管"AI 能做什么"。

四、CODEBUDDY.md+rules/*.md— 上下文注入器

4.1 它是干什么的

主动告诉 AI 你的项目是怎么运转的— 用什么技术栈、遵循什么代码规范、有哪些约定俗成的做法。

4.2 两种文件类型

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 - 允许的 type：feat, fix, docs, style, refactor, test, chore - scope 使用小写英文，多词用短横线连接 - 禁止提交 `console.log`（调试完成后必须删除） - 禁止提交包含 TODO 且无对应 Issue 号的代码

.codebuddy/rules/styling.md

# 样式规范 - 使用 CSS Modules（`.module.less`） - 颜色使用设计系统变量，不写硬编码色值 - 响应式断点：768px（平板）/ 1024px（桌面）/ 1440px（宽屏） - 禁止使用 `!important`（除非覆盖第三方库样式） - 禁止内联样式（style prop）

4.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 看的。

但它有间接影响：

5.2 典型配置

# .gitignore # 依赖 node_modules/ .python-version # 构建产物 dist/ build/ *.tsbuildinfo # 环境变量 .env .env.local # IDE .idea/ .vscode/ *.swp # 系统 .DS_Store Thumbs.db

5.3 .gitignore vs .codebuddy/ignore

实践建议：.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/ignore

node_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 调用

.gitignore

node_modules/ dist/ .env .env.local .idea/ .vscode/ .DS_Store

6.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 ✅ → 全程无违规操作，一次搞定

七、速查表

八、总结

核心原则：ignore 做减法（减少噪音），CODEBUDDY.md/rules 做加法（注入知识），permissions 做守卫（控制行为）。三层配合，AI 才能既高效又安全地为你工作。