.codebuddy 目录结构说明

~/.codebuddy 和项目级 .codebuddy 的文件与子目录。

CodeBuddy Code 使用两种配置目录：

全局目录 ~/.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-reviewer
description: 代码审查专家，在编写代码后主动使用
tools: Read, Grep, Glob, Bash
model: inherit
---

您是一位高级代码审查员，专注于代码质量、安全性和实践教程...

详见 子代理文档。

rules/

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

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

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

---
alwaysApply: false
paths: 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 文件自动递归加载。

skills/

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

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

SKILL.md 格式：

---
name: case-executor
description: 执行 JSON 测试用例并生成报告
allowed-tools: Read, Write, Bash
---

您是测试执行专家，负责运行 JSON 格式的 UI 测试用例...

详见 Skills 文档。

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: 创建一个新的 Issue
argument-hint: "<描述> ; <类型> ; <产品>"
allowed-tools: Bash 
---

根据以下描述创建 Issue：$ARGUMENTS

详见 斜杠命令文档。

配置优先级

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

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

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

记忆加载顺序

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

版本控制建议