让终端读懂整个代码库

验收清单

• claude --version 打印出了版本号，不是 command not found
• claude doctor 没有报设置文件校验错误
• /status 里能看到当前登录方式
• hello.py 能在你自己的终端里直接跑出结果，不依赖会话
• 你能说出这次会话里它一共请求了几次权限、分别要做什么
• git diff 的改动范围和你的预期一致，没有出现你没要求的文件

常见错误

装完了但 claude: command not found

原生安装器把启动器放在 ~/.local/bin/claude，这个目录不在你的 PATH 里。把它加进 shell 配置后重开终端；仍不行就跑 claude doctor，它会列出安装诊断和建议的修法。

用 npm 装时冒出 EBADENGINE 警告

v2.1.198 起 npm 包要求 Node.js 22 及以上。这个警告不阻断安装——npm 包装的是原生二进制，运行时并不调用 Node——但要消掉就得升级 Node，或者干脆改用原生安装器。

登录后浏览器一直转，终端没反应

本地回调服务器不通，在 WSL2、SSH 会话和容器里很常见。按提示把浏览器上显示的登录码粘回终端即可。

第一次就让它改了一堆你没让它改的文件

多半是在没读懂权限提示的情况下点了「不再询问」。先 git checkout . 回滚，再重开会话，用 Shift+Tab 切到 Plan 模式让它先说方案、你确认后再动手。

免费 Claude 账号登不上

免费版不包含 Claude Code。需要 Pro、Max、Team、Enterprise 或 Console 账号，也可以走 Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundry 这类第三方供应商。

验收清单

• CLAUDE.md 在 200 行以内，且 /context 的 Memory files 一栏里能看到它
• .claude/rules/ 里至少有一条带 paths: 的规则，只在匹配文件被读到时才载入
• allow 名单里的命令执行时不再弹窗
• deny 名单里的 .env 确实读不到（反例验过，不是看配置文件推的）
• 你能一句话说清 default / acceptEdits / plan 三种模式各自放开了什么
• PR 里每一处改动你都能解释为什么这么改

常见错误

规则写了但完全不生效

两种原因：一是工作区未被信任——克隆来的仓库要先在里面跑一次 claude 并接受信任对话框，项目 .claude/settings.json 才会被采用；二是 JSON 写错了，claude doctor 会把设置文件的校验错误列出来。

deny 了 Read(./.env)，父目录的 .env 还是能被读到

路径规则是有锚点的。Read(.env) 或 Read(**/.env) 只覆盖当前目录及其子目录；要覆盖整个文件系统得写 Read(//**/.env)。

CLAUDE.md 写得很详细，它还是不照做

CLAUDE.md 是上下文，不是强制配置——官方明说它「不是硬性执行层」。必须在某个时点发生的事（提交前跑 lint、改完文件跑格式化）要写成 Hook；必须拦住的动作要写成 permissions.deny。

会话越到后面越糊涂，开始重复问已经答过的事

上下文被文件内容挤满了。/context 看构成，把大范围调研交给子 Agent（它的文件读取不占你的窗口），或者 /compact 一次；也可以用 /autocompact 500k 把自动压缩的触发点提前。

monorepo 里被别的团队的 CLAUDE.md 干扰

Claude 会沿目录树向上把每一层的 CLAUDE.md 都读进来。用 claudeMdExcludes 按 glob 排除掉不相关的那些，写进 .claude/settings.local.json 保持只对你生效。

验收清单

• 改完文件后格式化确实自动跑了，而不是你手动跑的
• 反例测过：一条 rm -rf 真的被 PreToolUse 钩子挡下，并显示了你写的理由
• 子 Agent 读的文件没有出现在主会话的 /context 里
• claude mcp list 里目标服务器显示 ✔ Connected
• 沙箱开启时，读 ~/.ssh 被拒、读项目目录正常、访问未放行域名不通
• 在 issue 里 @claude 能收到回复
• managed settings 草案里至少包含 permissions.deny 与 sandbox.enabled 两项，且你能说清它们各自拦住了什么

常见错误

Hook 看着配好了，什么都没发生

hooks 是三层嵌套：事件名 → matcher 组 → handler 数组，少写一层就不触发。另外 PostToolUse 的 exit code 2 只能把 stderr 报给 Claude，拦不住已经执行完的工具——要拦必须放在 PreToolUse。

写了 deny 逻辑就以为安全了

没跑过反例的护栏只提供虚假安全感。每写一条拦截逻辑，必须构造一个应该被拦的输入真跑一遍，看到它被拦下才算数。

Linux 上沙箱似乎没起作用，也没有报错

依赖缺失时默认行为是「警告 + 不沙箱继续跑」。/sandbox 的 Dependencies 页会列出缺的是 ripgrep、bubblewrap、socat 还是可选的 seccomp 过滤器。要让缺依赖直接变成硬失败，把 sandbox.failIfUnavailable 设为 true——托管部署应当这么配。

项目 .mcp.json 里的服务器一直显示 Pending approval

项目级 MCP 服务器要在交互式会话里人工批准一次。在该目录跑 claude 批准即可；要重置这些选择用 claude mcp reset-project-choices。

把 managed settings 当成万能开关

managed settings 管的是技术强制——deny 规则、沙箱、环境变量、登录组织限制；行为层面的约束（代码风格、数据处理提醒）要走 managed CLAUDE.md。官方把这两张表分开列，就是因为经常有人拿错工具。

以为关掉文件系统隔离只是「少一层保险」

sandbox.filesystem.disabled 设为 true 之后，沙箱里的命令可以写 shell 启动文件、$PATH 上的可执行文件甚至 ~/.claude/settings.json，下一轮运行时就能给自己扩权。这是提权路径，不是降级保护。