我想要 | 使用 |
仅加载您接触的代码的约定，而不是一个根文件覆盖每个子系统 | 按目录的 CODEBUDDY.md 文件 |
阻止 CodeBuddy 打开构建输出、生成的代码和供应商依赖 | permissions.deny 中的 Read 拒绝规则 |
通过语言服务器而不是扫描文件来查找符号的定义或调用者 | 代码智能插件 |
当 CodeBuddy 创建 worktree 时仅检出任务需要的目录 | worktree.sparsePaths |
从同一会话中读取和编辑同级包或另一个存储库 | --add-dir 或 additionalDirectories |
给 CodeBuddy 特定于一个区域的程序，仅在相关时加载 | |
用一套每个人都安装的约定替换许多按目录的 CODEBUDDY.md 文件 | 内部市场中的 plugin |
packages/api/，替换为您自己的子系统目录，例如 src/backend/ 或 lib/core/。monorepo/CODEBUDDY.md # 根指令packages/api/CODEBUDDY.md # API 特定指令.codebuddy/skills/src/web/CODEBUDDY.md # 前端特定指令.codebuddy/skills/src/shared/CODEBUDDY.md # 共享库指令src/
codebuddy 的位置决定了 CodeBuddy 可以读取和编辑哪些文件而无需额外权限授予、在启动时加载哪些 CODEBUDDY.md 文件，以及哪些项目设置适用。从以下位置启动 | 文件访问 | 启动时加载的 CODEBUDDY.md | 使用场景 |
存储库根目录 | 每个文件 | 仅根目录；当 CodeBuddy 在那里读取时，子目录文件按需加载 | 任务跨越多个包或子系统 |
子目录 | 仅该子树，直到您授予更多权限 | 该目录的加上每个祖先的 | 工作范围限于一个包或子系统 |
.codebuddy/settings.json 中的项目设置仅从您的启动目录加载，不像 CODEBUDDY.md 文件那样从父目录继承：存储库根目录的 .codebuddy/settings.json 仅在您从根目录启动时适用。CODEBUDDY.md：适用于任何地方的指令，例如编码标准、提交约定和存储库布局CODEBUDDY.md：特定于该区域堆栈的约定。在 monorepo 中，这是每个包一个。在大型单树中，它是每个子系统一个，例如 src/db/ 或 src/api/CODEBUDDY.md 将 CodeBuddy 定向到存储库结构：# CODEBUDDY.md这是一个 monorepo，在 packages/ 下有三个包：- packages/api：使用 Express、TypeScript 和 PostgreSQL 的 Node.js REST API- packages/web：使用 Vite、TypeScript 和 TailwindCSS 的 React 前端- packages/shared：由 api 和 web 都使用的共享 TypeScript 实用程序从包目录运行命令，而不是从 monorepo 根目录。每个包都有自己的 tsconfig.json、package.json 和测试套件。
CODEBUDDY.md，这里是 packages/api/CODEBUDDY.md，添加特定于该区域堆栈的上下文：# packages/api/CODEBUDDY.md这个包是 REST API 服务器。- 运行测试：`npm test`（使用 Vitest）- 运行开发服务器：`npm run dev`（端口 3001）- 数据库迁移：`npm run migrate`- 环境变量：将 `.env.example` 复制到 `.env`API 路由在 src/routes/ 中。每个路由文件导出一个 Express 路由器。数据库查询在 src/db/ 中使用 Knex。永远不要在路由处理程序中写原始 SQL 字符串。
packages/api/ 启动 CodeBuddy 时，它加载 packages/api/CODEBUDDY.md 和根 CODEBUDDY.md。CodeBuddy 看到本地指令与存储库范围的规则一起，上下文中没有来自 packages/web/ 的指令。对于非 monorepo 树中的任何子目录也是如此。Stop hook 在 CodeBuddy 完成响应时接收会话记录的路径，所以脚本可以审查会话并在暴露的差距仍然新鲜时提议 CODEBUDDY.md 更新CODEBUDDY.md 文件和 .codebuddy/rules/ 下的路径范围规则都允许您将指令定向到树的一部分。它们在文件位置和加载时间上有所不同。方法 | 文件位置 | 加载时间 | 使用场景 |
按目录 CODEBUDDY.md | 在目录内，与其代码一起 | 从该目录启动时在启动时，或当 CodeBuddy 在那里读取文件时按需 | 目录所有者维护自己的约定；指令与代码一起版本化 |
.codebuddy/rules/ 中的路径范围规则 | 存储库根目录的中央 .codebuddy/ | 当 CodeBuddy 处理与规则的 paths: glob 匹配的文件时 | 您想要一个地方的所有约定，或相同的规则适用于许多分散的路径 |
.gitignore，所以已列在其中的路径，例如 node_modules/、dist/ 和 build/，无需额外配置就会保持在搜索结果之外。permissions.deny 中添加 Read 拒绝规则以阻止 CodeBuddy 打开这些文件，即使搜索列出了它们。.codebuddy/settings.json。要保持个人，改用 .codebuddy/settings.local.json。与本页面的其他项目设置一样，这些文件仅从您的启动目录加载。如果您从那里启动 CodeBuddy，将它们放在存储库根目录，或如果您从子目录启动，放在每个包的 .codebuddy/ 中。// .codebuddy/settings.json{"permissions": {"deny": ["Read(./**/dist/**)","Read(./**/build/**)","Read(./**/*.generated.*)","Read(./vendor/**)"]}}
cat、head、grep 和 find，当拒绝的路径作为参数传递时。它们不会从递归搜索的输出中过滤拒绝的路径，也不涵盖自己打开文件的任意子进程。有关完整的模式语法，请参阅 Read 和 Edit 权限规则。/plugin install typescript-lsp@claude-plugins-official
enabledPlugins 项目设置。Read 拒绝规则配对良好。拒绝规则保持不相关的内容不进入上下文，代码智能保持 CodeBuddy 不读取剩余的内容来定位定义。--worktree 标志在新的 git worktree 中启动会话，以便更改与主检出隔离。默认情况下，它检出整个存储库。在大型存储库中，worktree.sparsePaths 设置使用 git sparse-checkout 仅将列出的目录加上根级文件写入磁盘，以便 worktrees 启动更快并使用更少空间。.codebuddy/settings.json。要为自己添加路径，使用 .codebuddy/settings.local.json：列表在范围内合并，所以本地文件可以向提交的列表添加路径但不能删除它们。下面的示例显示提交的文件：// .codebuddy/settings.json{"worktree": {"sparsePaths": [".codebuddy","packages/api","packages/shared"]}}
.codebuddy/、packages/api/ 和 packages/shared/ 而不是完整树。sparsePaths 中的路径相对于存储库根目录，无论您从哪个子目录启动 CodeBuddy。任何目录路径都可以在这里工作，不仅仅是包根。sparsePaths，所以如果一个子代理需要 packages/api/ 而另一个需要 packages/web/，列出两者。sparsePaths 中列出目录，而不是单个文件。根级文件如 package.json、tsconfig.base.json 和锁文件始终与您列出的目录一起检出。根级目录不是，所以如果您想要存储库根目录的 .codebuddy/settings.json、.codebuddy/rules/ 或 .codebuddy/skills/ 在 worktree 内可用，请在列表中包含 .codebuddy。node_modules，将 sparsePaths 与同一 .codebuddy/settings.json 中的 symlinkDirectories 配对：// .codebuddy/settings.json{"worktree": {"sparsePaths": [".codebuddy","packages/api","packages/shared"],"symlinkDirectories": ["node_modules"]}}
node_modules/ 回到主存储库副本的符号链接，而不是在磁盘上复制它。sparsePaths 和 symlinkDirectories 设置在创建 worktree 之前从您的启动目录读取。创建后，会话的工作目录是 worktree 根，而不是您启动的子目录。因此，worktree 内的项目设置从 worktree 根的 .codebuddy/settings.json（存储库根文件的检出副本）加载。将您在 worktrees 内需要的任何其他设置（例如权限规则或 hooks）放在存储库根的 .codebuddy/settings.json 中。packages/api/ 启动 CodeBuddy 时，它可以读取和写入该目录内的文件。如果任务需要跨包更改，例如更新 api 和 web 都导入的共享类型，您需要授予对同级目录的访问权限。相同的机制授予对单独检出的存储库的访问权限。.codebuddy/settings.json 中的 additionalDirectories 设置给 CodeBuddy 访问工作目录外的目录。下面的示例授予对两个同级包的访问权限：// .codebuddy/settings.json{"permissions": {"additionalDirectories": ["../shared","../web"]}}
packages/api/ 工作时读取和编辑 packages/shared/ 和 packages/web/ 中的文件。--add-dir：codebuddy --add-dir ../shared
.codebuddy/rules/ 文件和 skills 是否也加载取决于您如何添加它：添加方式 | 加载 CODEBUDDY.md 和规则 | 加载 skills |
additionalDirectories 设置 | 从不 | 从不 |
--add-dir 标志或 /add-dir 命令 | 仅使用下面的环境变量 | 是 |
--add-dir 或 /add-dir 添加的目录加载 CODEBUDDY.md 和规则文件，设置 CODEBUDDY_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 环境变量：CODEBUDDY_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 codebuddy --add-dir ../shared
additionalDirectories 提交到 .codebuddy/settings.json。对于个人选择或一次性访问，使用 .codebuddy/settings.local.json 或在启动时传递 --add-dir。.codebuddy/skills/ 下。将它们与该区域的代码一起提交，以便克隆存储库的任何人都能获得它们。在 monorepo 中，这可以是每个包一套 skills。在大型单树代码库中，它是每个子系统一套，例如 src/db/.codebuddy/skills/。mkdir -p packages/api/.codebuddy/skills/api-testing
SKILL.md，这里是 packages/api/.codebuddy/skills/api-testing/SKILL.md。此示例教 CodeBuddy API 包的测试模式：---name: api-testingdescription: API 包的测试模式。在 packages/api/ 中编写或修改测试时使用。---## 测试结构测试在 `src/__tests__/` 中，镜像 `src/` 目录结构。每个路由文件都有一个对应的 `.test.ts` 文件。## 运行测试- 所有测试：`npm test`- 单个文件：`npm test -- src/__tests__/routes/users.test.ts`- 监视模式：`npm test -- --watch`## 测试实用程序- `src/__tests__/helpers/db.ts`：提供 `setupTestDb()` 和 `teardownTestDb()` 用于数据库测试- `src/__tests__/helpers/auth.ts`：提供 `createTestUser()` 和 `getAuthToken()` 用于认证端点## 模式- 使用 `supertest` 进行 HTTP 断言，而不是原始 fetch- 始终在回滚的事务中包装数据库测试- 在 `src/__tests__/mocks/` 中模拟外部服务
packages/web/.codebuddy/skills/component-patterns/ 描述前端的组件约定而不是测试。当 CodeBuddy 处理 packages/api/ 中的文件时，它加载 api-testing skill。当它在 packages/web/ 中工作时，它加载 component-patterns 代替。在另一个的任务期间，两个目录的 skills 都不加载。paths frontmatter 字段采用 glob 模式，CodeBuddy 仅在处理匹配文件时自动加载 skill。对于位于存储库根目录的 .codebuddy/skills/ 中但仅适用于某些文件（无论它们出现在哪里）的 skill，使用此功能，例如范围限于 /migrations/ 的数据库迁移 skill。packages/api/：来自该目录、每个父目录直到存储库根目录以及用户级别的 skillsadditionalDirectories 设置仅授予文件访问权限，不加载 skillspackages/api/ 中编写或修改测试"。.codebuddy/skills/ 中，以便从任何启动目录加载。当共享 skills 需要自己的版本历史或必须跨存储库工作时，改为将它们打包为插件。插件 skills 使用 plugin-name:skill-name 命名空间，所以它们永远不会与按目录的 skills 冲突。平台团队可以在一个地方对它们进行版本化和更新。.codebuddy/settings.json 必须是自包含的而不是分层在根文件上。.codebuddy/settings.json 中提交 worktree、additionalDirectories 和 Read 拒绝规则，以便 packages/api/ 中的每个开发者获得相同的同级访问、稀疏路径和排除。下面的文件是 packages/api/ 的提交的按区域设置：// packages/api/.codebuddy/settings.json{"worktree": {"sparsePaths": [".codebuddy","packages/api","packages/shared"],"symlinkDirectories": ["node_modules"]},"permissions": {"additionalDirectories": ["../shared"],"deny": ["Read(./**/dist/**)","Read(./**/build/**)"]}}
packages/api/ 启动，同级包的 CODEBUDDY.md 文件已经超出范围。如果您也从根目录启动会话，可以将排除规则添加到存储库根目录的 .codebuddy/settings.local.json。additionalDirectories 条目在您直接从 packages/api/ 启动 CodeBuddy 时适用。在从此会话创建的 worktree 内，工作目录是 worktree 根，所以此设置文件不加载。同级包已经在 worktree 内可达而无需它，但拒绝规则需要在存储库根目录的 .codebuddy/settings.json 中的第二个副本，以便 worktree 会话获取它们，如 worktree 设置注释 所述：// .codebuddy/settings.json{"permissions": {"deny": ["Read(./**/dist/**)","Read(./**/build/**)"]}}
monorepo/CODEBUDDY.md.codebuddy/settings.json # worktree 会话的拒绝规则packages/api/CODEBUDDY.md.codebuddy/settings.json # worktree、additionalDirectories、拒绝规则.codebuddy/skills/api-testing/SKILL.mdweb/CODEBUDDY.md.codebuddy/skills/component-patterns/SKILL.mdshared/CODEBUDDY.md
packages/api/ 启动 CodeBuddy：packages/api/CODEBUDDY.md，跳过 packages/web/CODEBUDDY.mdpackages/api/ 和 packages/shared/ 中的文件packages/api/ 中 dist/ 和 build/ 下的构建输出读取.codebuddy/、packages/api/、packages/shared/ 和根级文件的 worktrees，拒绝规则从根设置文件应用于整个 worktree文档反馈