CodeBuddy .codebuddy 目录结构说明

·全局目录 ~/.codebuddy/：存储用户级配置、历史数据、运行时数据等，影响所有项目

·项目目录 .codebuddy/（位于项目根目录）：存储项目级配置、规则、技能、命令等，随项目版本控制共享给团队

一、全局目录 ~/.codebuddy/

~/.codebuddy/├── settings.json # 用户级全局配置├── settings.local.json # 本地个人偏好（不共享）├── CODEBUDDY.md # 用户级记忆文件├── mcp.json # 全局 MCP 服务器配置├── statusline-command.sh # 自定义状态行脚本（可选）│├── agents/ # 用户级自定义子代理（所有项目可用）├── rules/ # 用户级规则文件（所有项目可用）├── skills/ # 用户级技能（所有项目可用）│├── projects/ # 各项目的会话与子代理运行时数据├── sessions/ # 会话数据├── plans/ # 计划模式生成的计划文件│├── logs/ # 运行日志├── traces/ # 执行追踪数据（OpenTelemetry）├── file-history/ # 文件变更历史├── history.jsonl # 对话历史├── blobs/ # 二进制资源（图片、截图等）├── tasks/ # 任务追踪数据├── teams/ # Agent 团队运行时数据├── shell-snapshots/ # Bash 沙箱快照│├── plugins/ # 已安装的插件├── local_storage/ # CLI 键值持久化存储├── channels/ # 频道配置（WeChat 等）│├── computer-use/ # Computer Use 功能记录├── debug/ # 调试信息└── usage-data/ # 使用量统计

三、settings.json

用户级全局配置，适用于所有项目。可通过 /config 命令或直接编辑管理。

{ "language": "简体中文", "model": "gpt-5", "reasoningEffort": "high", "permissions": { "defaultMode": "default", "allow": ["Bash(git:*)"], "deny": ["Read(./.env)", "Read(./secrets/**)"] }, "env": { "NODE_ENV": "development" }, "memory": { "autoMemoryEnabled": true, "typedMemory": true }, "trustedDirectories": ["~/workspace/myproject"]}

完整配置字段参见 设置配置。

四、settings.local.json

本地个人配置，不会被 CodeBuddy Code 自动同步或共享，适合存储仅对本机有效的覆盖项（如 API 密钥、调试开关等）。

五、CODEBUDDY.md

用户级记忆文件，在所有项目中生效，适合保存个人编码偏好、常用工作流说明等。

## 工具偏好- 使用 pnpm 而非 npm- 倾向函数式编程风格## 代码风格- 使用 2 空格缩进

详见 记忆管理。

六、mcp.json

全局 MCP 服务器配置，格式与项目级 .mcp.json 相同：

{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] } }}

详见 MCP 文档。

八、agents/

存放对所有项目生效的用户级自定义子代理。每个代理为一个 .md 文件：

~/.codebuddy/agents/├── code-reviewer.md # 代码审查代理└── translator.md # 翻译代理

文件格式（YAML frontmatter + 系统提示）：

—name: code-reviewerdescription: 代码审查专家，在编写代码后主动使用tools: Read, Grep, Glob, Bashmodel: inherit—你是一位高级代码审查员，专注于代码质量、安全性和实践教程…

详见 子代理文档。

九、rules/

存放对所有项目生效的用户级规则文件。所有 .md 文件自动加载，支持子目录：

~/.codebuddy/rules/├── preferences.md # 个人编码偏好└── workflows.md # 常用工作流规范

规则文件支持 frontmatter 控制加载行为：

—alwaysApply: falsepaths: src/**/*.ts—# TypeScript 规范- 优先使用 `interface` 而非 `type`- 禁止使用 `any`

详见 记忆管理 – 规则系统。

十、skills/

存放对所有项目生效的用户级技能。每个技能为独立目录，包含 SKILL.md：

~/.codebuddy/skills/└── pdf/ └── SKILL.md

详见 Skills 文档。

十一、运行时数据目录

这些目录由 CodeBuddy Code 自动维护，通常无需手动操作：

十二、项目目录 .codebuddy/

放置于项目根目录，可以提交到版本控制以供团队共享：

.codebuddy/├── settings.json # 项目共享配置├── settings.local.json # 本地个人配置（.gitignore 自动忽略）├── CODEBUDDY.md # 项目级记忆文件│├── agents/ # 项目级自定义子代理├── rules/ # 项目级规则文件├── skills/ # 项目级技能├── commands/ # 自定义斜杠命令

十四、settings.json

项目共享配置，通过版本控制与团队同步。适合配置项目统一的模型、权限规则、插件等：

{ "permissions": { "allow": ["Read", "Edit", "Bash(git:*)", "Bash(npm:*)"], "deny": ["Read(./.env)", "Read(./secrets/**)"] }, "enabledPlugins": { "pr-review-toolkit@company-tools": true }, "extraKnownMarketplaces": { "company-tools": { "source": { "source": "github", "repo": "myorg/codebuddy-plugins" } } }}

十五、settings.local.json

本地个人配置，CodeBuddy Code 会自动将其加入 .gitignore。适合存储个人覆盖项（如本地调试端口、个人密钥等），不会影响团队其他成员。

十六、CODEBUDDY.md

项目级记忆文件，随版本控制共享。存储项目架构、约定、常用命令等团队知识：

# 项目说明本项目是 TypeScript monorepo（Yarn workspaces）。## 常用命令- `yarn build` — 构建所有包- `yarn test` — 运行所有测试## 架构约定- 使用 CellJS 依赖注入框架- 协议定义放在 `*-protocol.ts` 文件

注意：说明：

注意：也可将记忆文件放在根目录的 CODEBUDDY.md（不在 .codebuddy/ 内），两种位置等效。

十八、agents/

存放项目专属子代理，优先级高于用户级代理。同名代理时项目级覆盖用户级。

.codebuddy/agents/├── blog-translator.md # 博客翻译代理└── docs-reviewer.md # 文档审查代理

十九、rules/

存放项目级规则，随版本控制共享。适合团队统一的代码规范、工作流约定等。支持子目录组织：

.codebuddy/rules/├── code-style.md # 代码风格规范├── testing.md # 测试规范├── security.md # 安全要求└── frontend/ ├── react.md # React 组件规范 └── styles.md # 样式规范

所有 .md 文件自动递归加载。

20、skills/

存放项目级技能，每个技能一个目录，包含 SKILL.md 和可选的辅助文件：

.codebuddy/skills/├── case-executor/│ ├── SKILL.md # 技能定义│ ├── scripts/ # 辅助脚本│ └── references/ # 参考资料└── cnb-api/ └── SKILL.md

SKILL.md 格式：

—name: case-executordescription: 执行 JSON 测试用例并生成报告allowed-tools: Read, Write, Bash—你是测试执行专家，负责运行 JSON 格式的 UI 测试用例…

详见 Skills 文档。

21、commands/

存放自定义斜杠命令，通过 /command-name 触发。支持目录嵌套（使用 /group:command 调用）：

.codebuddy/commands/├── deploy.md # /deploy 命令├── team/│ ├── issue-start.md # /team:issue-start 命令│ └── create-issue.md # /team:create-issue 命令└── openspec/ └── propose.md # /openspec:propose 命令

命令文件格式：

—description: 创建一个新的 Issueargument-hint: "<描述> ; <类型> ; <产品>"allowed-tools: Bash —根据以下描述创建 Issue：$ARGUMENTS

详见 斜杠命令文档。

22、配置优先级

多层配置按以下优先级应用（高优先级覆盖低优先级）：

命令行参数 （最高优先级） ↓.codebuddy/settings.local.json （项目本地，不提交版本控制） ↓.codebuddy/settings.json （项目共享，团队统一） ↓~/.codebuddy/settings.json （用户全局，个人偏好） ↓产品内置默认配置 （最低优先级）

代理/技能/规则的优先级：项目级 > 用户级 > 插件级，同名时项目级优先。

23、记忆加载顺序

1. 用户级记忆：~/.codebuddy/CODEBUDDY.md2. 用户级规则：~/.codebuddy/rules/*.md（递归）3. 项目级记忆：CODEBUDDY.md（从 cwd 向上递归查找）4. 项目级规则：.codebuddy/rules/*.md（仅 cwd，不向上）5. 项目本地记忆：CODEBUDDY.local.md6. 子目录记忆：工具操作文件时动态加载该子目录的 CODEBUDDY.md

24、版本控制建议