让 Claude Code 参考后端而不误改代码

Full translation

完整中文译文

书籍：RAG Pocket Guide

我的其他作品：Thinking in Go（两本系列）——Go 编程完整指南 + Go 六边形架构

我的项目：Hermes IDE | GitHub——面向使用 Claude Code 和其他 AI 编程工具交付软件的开发者的 IDE

关于我：xgabriel.com | GitHub

你让 Claude Code 开发一个新的订单页面。它需要真实的 GET /orders 路由和真实的 OrderDto，于是你把旁边的后端仓库也交给它访问。页面做对了，可一看后端的 git status，却发现 DTO 被“整理”过，一个字段也被改了名。这些改动没人要求，却随时可能让移动端应用出问题。

这种访问权限正是文档规定的默认行为。Claude Code 的权限文档指出，添加目录中的文件“遵循与原始工作目录相同的权限规则”：读取无需提示确认，而“文件编辑权限遵循当前的权限模式”。文档还说明，在 acceptEdits 模式下，对工作目录或添加目录中的文件进行编辑，都会自动获准。添加后端仓库后，它就和前端仓库一样可以被编辑。

你真正想要的是：把后端作为参考资料，同时禁止写入。下面一步步配置，假设前端位于 ~/code/web，后端位于 ~/code/api。

第 1 步：用 --add-dir 把后端交给 Claude

在前端目录中启动 Claude Code，把后端添加为额外的工作目录。CLI 参考文档中介绍了这个参数：

cd ~/code/web
claude --add-dir ~/code/api

已经在会话中了？改为运行 /add-dir ~/code/api。要让这个目录在不同会话之间持续生效，可以在设置文件的 permissions.additionalDirectories 中列出它，具体见文档。

这两种方式加载的内容并不相同。通过 --add-dir 或 /add-dir 添加目录时，还会引入后端的 .claude/skills/、.claude/commands/ 和 .claude/agents/。而在 additionalDirectories 中列出目录，只会授予文件访问权限。只有设置 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1，才会加载后端的 CLAUDE.md，具体见文档。如果后端有自己的 /deploy 命令，通过参数添加目录后，这条命令也会出现在前端会话的命令列表里。

第 2 步：用一条 deny 规则阻止 Claude 编辑后端

在前端仓库中创建 .claude/settings.local.json：

{
  "permissions": {
    "deny": [
      "Edit(~/code/api/**)"
    ]
  }
}

这条规则覆盖 Claude 的编辑工具，以及 Claude Code 能识别的 shell 文件操作命令。脚本和其他子进程则需要 sandbox 来限制，后面的“缺口”一节会介绍如何配置。

这里用的是 Edit，不是 Write。文档说明，Edit 规则“适用于所有编辑文件的内置工具”，其中也包括 Write。为 Write 编写的路径规则虽然会被接受，但“永远不会被检查”，Claude Code 也会在启动时发出警告，具体见文档。deny 列表里如果只有 Write(~/code/api/**)，看起来很安全，实际上毫无作用。

路径前缀很重要。在 Edit 和 Read 规则中，~/path 从用户主目录开始，//path 表示绝对路径。单个前导斜杠并不表示文件系统根目录：/path 以设置来源为基准，对于项目设置和本地设置，这意味着会话的主工作目录。像 Edit(/code/api/**) 这样的规则，指向的会是前端目录内部。

deny 优先。规则按 deny、ask、allow 的顺序求值，而且“allow 规则无法在 deny 规则中划出例外”。你上周批准的一条宽泛 allow 规则，也无法重新开放后端的编辑权限。

隔着玻璃可以读取，写入则被挡在玻璃外。

为什么使用本地设置文件？因为这条路径取决于你机器上的目录布局。设置文档说明，Claude Code 创建 settings.local.json 时，会把它加入全局 Git 忽略规则。如果你手动创建，就需要自己把它加入 .gitignore。如果整个团队都采用相同的布局，把两个仓库并排放置，那么可以把规则写进纳入版本控制的 .claude/settings.json。根据文档，其中的 deny 规则会立即生效，甚至在同事信任该文件夹之前就已生效。

如果只是一次性会话，完全不想创建文件，也可以通过命令行传入同一条规则。--disallowedTools 接受 deny 规则：

claude --add-dir ~/code/api \
  --disallowedTools "Edit(~/code/api/**)"

在会话中运行 /permissions，可以查看每条规则，以及它来自哪个设置文件。claude doctor 则可以在不启动会话的情况下，输出设置文件的校验错误。

第 3 步：验证 deny 确实拦截，再检查两个仓库

没有亲眼看过规则拦截操作，就别轻信它。先记录后端当前的状态：

git -C ~/code/api branch --show-current
git -C ~/code/api status --short

git status --short 会为每个已修改或未跟踪的路径输出一行。工作区干净时，它不会输出任何路径行，这个空结果就是你的基线。如果输出不为空，先提交或 stash 后端的改动，否则之后就分不清哪些是你的改动，哪些是 Agent 的改动。

现在交给 Claude 一个这条规则必须拦住的任务：

Open the OrderDto file in ~/code/api and add the
comment "// read-only test" as its first line.

Claude 可以找到并读取这个文件，因为读取添加目录中的文件不需要提示确认。编辑操作应当由 Claude Code 自身拒绝，不应出现需要你回应的权限确认提示，Claude 也应报告操作未获允许。具体措辞会随版本变化，所以要关注是否真正拒绝了操作。如果出现权限确认提示，或者编辑成功了，就说明规则没有匹配：先在 /permissions 中检查路径前缀，再撤销那条注释。

Build src/pages/orders.tsx from the GET /orders route
and OrderDto in ~/code/api. Read the API, don't
change it. If the DTO looks wrong, tell me.

完成后，检查两边：

git -C ~/code/api status --short
git -C ~/code/web status --short

后端应该仍然没有任何输出。前端应该列出 src/pages/orders.tsx，如果它是新文件，状态就是 ??，以及任务涉及的其他文件。prompt 的最后一句也很重要：Claude 无法修复 DTO，所以你需要它说明哪里看起来有问题，再把这条说明交给后端团队。

缺口：会写入文件的 shell 命令

针对 Edit 的 deny 规则，覆盖范围不止编辑工具。根据权限文档，它还适用于 Claude Code 能识别的 Bash 文件操作命令，例如 sed 和 tee，以及 > file 这样的重定向目标。但它不适用于“间接读写文件的任意子进程”。如果 Claude 在后端目录中运行 npm run codegen，或者运行一个会写文件的 Node 脚本，这条规则根本看不到相关路径。

这时就需要操作系统级别的 sandbox，它会包住 Bash 命令及其启动的所有进程。先了解它的默认行为：在 sandbox 中运行的命令，可以写入工作目录，也可以写入通过 --add-dir、/add-dir 或 additionalDirectories 添加的任何目录。因此，要为后端添加写入禁止规则，并关闭脱离 sandbox 的重试：

{
  "permissions": {
    "deny": [
      "Edit(~/code/api/**)"
    ]
  },
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false,
    "filesystem": {
      "denyWrite": ["~/code/api"]
    }
  }
}

sandbox 文档说明，权限规则和 sandbox 设置中的路径会合并到同一份 sandbox 配置中，所以 Edit deny 理应已经覆盖这种情况。显式写出 denyWrite，是为了让下一个阅读文件的人一眼看懂意图。sandbox 路径使用常见的 ~/code/api 形式；// 和 / 前缀属于权限规则的语法。allowUnsandboxedCommands 这一行关闭了 sandbox 的逃生通道：当命令在 sandbox 内执行失败时，Claude 可能会尝试在外部重新运行，文档建议拒绝这次重试。如果某条 allow 规则匹配该命令，重试就会直接获准，无需提示，因此设置为 false 更稳妥，具体见 sandbox 文档。你也可以在会话中通过 /sandbox 启用 sandbox。它支持 macOS、Linux 和 WSL2。在原生 Windows 上，文档说明 Claude Code 会在没有 sandbox 的情况下运行命令。

在 Hermes IDE 2.3 中采用同样的配置

Hermes IDE 是我开发的，阅读这一节时请把这一点考虑在内。2026 年 10 月 13 日发布的 Hermes 2.3.0，允许一个 Claude Code 任务跨多个文件夹工作。按下 ⌘N（Windows 和 Linux 上是 Ctrl+Shift+N），用 ⌘P（Ctrl+P）打开项目菜单，在主项目之外最多勾选 5 个额外文件夹，也可以在某个文件夹上按 Shift+Enter。项目标签会显示你添加了多少个文件夹。标签下方的一行会列出各个额外文件夹，以及它们当前的分支和未提交改动。下面的截图以 API 仓库作为主项目；对于本文的配置，应选择前端作为主项目，再把后端勾选为额外文件夹。

Hermes 2.3：项目选择器中有一个主项目和两个勾选的额外文件夹，每个文件夹都显示了分支和未提交改动。

只有主项目会获得该任务新建的 hermes/ 分支和 worktree。额外文件夹会直接在原位置、原分支上参与工作，因此需要审查和合入的任务分支只有一个。如果某个文件夹无法添加，Hermes 也会告诉你原因，例如它与已选文件夹属于同一个仓库，或者它位于主项目内部。

Hermes 不会把额外文件夹变成只读。启动器会在标签下方提示：额外文件夹会在原位置被编辑，改动不会落在任务分支上。真正让后端保持只读的，是第 2 步的 deny 规则，加上限制 shell 命令写入的 sandbox denyWrite。默认情况下，Hermes 会在终端中运行真正的 claude 命令，所以你的 Claude Code 设置会照常生效。任务的 worktree 也应该仍能读取本地规则：设置文档说明，在 worktree 中，Claude Code 使用的是主检出目录根目录下的 .claude/settings.local.json。

启动器中的 Claude Code 处于 Accept edits 模式，并添加了两个额外文件夹。让这些文件夹保持不变的，是 deny 规则，以及限制 shell 写入的 sandbox。

标签下方显示分支和未提交改动的那一行，能让你在启动前发现后端工作区不干净，便于先清理。从 2.3.1 开始，会话下方的“Agent replies”栏还会注明，它只跟踪主项目中的改动。那里的回复标签不会显示后端的编辑，因此仍然需要执行 git -C ~/code/api status --short 检查。

Hermes 免费，采用 BSL 1.1 许可证开放源码，可在 macOS、Windows 和 Linux 上运行。它与 Anthropic 或任何其他 Agent 厂商均无关联。你可以下载使用，也可以在 GitHub 上阅读源码。

这里采用的模式是 grounding：让模型读取真实、权威的源码，避免它凭空猜测你的 API。当资料太多、无法一次全部交给模型时，RAG Pocket Guide 介绍的也是同样的思路，并涵盖面向生产环境的 retrieval、chunking 和 reranking 模式。如果你在 Hermes 中尝试这条 deny 规则，发现实际行为与本文描述不同，请提交 issue。

如需采取进一步措施，你可以考虑屏蔽此人和／或举报滥用行为。