Claude Code 安全配置：.env、Git 与危险命令权限分层

当在生产仓库上配置 Claude Code 时，开发者经常遇到一个令人沮丧的权衡：要么不断确认琐碎的读取命令，要么启用完全绕过模式（--dangerously-skip-permissions），从而面临 .env 意外泄露、git push --force 误执行或项目依赖被破坏的风险。

两种极端都不可取。为了排查权限错误并建立安全的 AI 编码实践，应基于最小权限原则构建配置：明确划分读取访问、写入权限、shell 执行边界和版本控制操作。

1. 四层权限模型

将工具和命令组织成四个独立的访问层级，以修复安全漏洞：

2. 隔离 .env 文件和项目密钥

传输层安全（TLS）加密了网络上的 API 流量，但它无法防止机密凭证进入模型上下文窗口、错误日志或交接摘要。

要排查并确保 Claude Code 不会摄入私有凭证，请应用以下修复：

将所有包含密钥的环境文件添加到 .gitignore。

提供一个干净的 .env.example 模板，其中包含虚假值，使 agent 能够理解变量名而不必查看运行时密钥。

在 CLAUDE.md 或 AGENTS.md 中添加严格的边界规则：

## Secret Protection Rule

- Never inspect, echo, or output contents from `.env`, `.env.local`, or private key files.
- To check required configuration keys, inspect `.env.example`.

[!IMPORTANT] API 密钥管理：你的 Claude Code API 密钥配置在本地环境中，绝不能提交到仓库文件。请遵循 BetterToken Claude Code Docs 中的集成工作流程。

3. 排查和控制命令的优先级清单

在使用 Claude Code 执行任务时，首先检查并执行明确的评估层级，以防止根本原因错误：

Agent Proposes Command
  │
  ├─> Contains destructive patterns (rm -rf, drop, force push)?
  │     └─> YES: Reject or run manually under developer supervision
  │
  └─> Touches .git internals, .env files, or external networks?
        │
        ├─> YES: Require explicit rationale and constrain command scope
        │
        └─> NO: Approve execution within the target branch

逐步护栏：

步骤 1：限制 Git 变更。永远不要允许自动化直接推送 main 分支，必须先进行手动 git diff --check 和测试运行。

步骤 2：隔离包安装。像 npm install <package> 或远程 curl 脚本之类的命令必须手动验证，以防止供应链漏洞并修复不受信任的依赖。

步骤 3：约束目录范围。将 agent 工作空间限制在特定的功能文件夹或专用 Git worktree 中。

4. 在测试工作空间中验证权限

在授予 Claude Code 访问关键仓库的权限之前，执行沙盒验证以排查并验证安全边界：

创建一个可处置的测试分支：git checkout -b test/permission-check。

添加一个包含假测试密钥的虚拟 .env 文件。

提示 agent 重构身份验证模块。

验证以下条件：

• agent 在发现阶段不会读取虚拟 .env 文件
• 没有密钥令牌泄露到错误日志、注释或 git diff 中
• 单元测试运行时不访问未授权的文件

验证通过后，清理测试分支。

这种结构化的权限边界可以在保持快速、自动化的 agent 执行的同时防止凭证泄露。