Claude Code 配置指南：先把这 7 件事配好

先确认安装方式和版本

Claude Code 配置的第一步不是写规则，而是确认你启动的是哪一个 `claude`。同一台机器上如果同时存在 native installer、npm 全局包、旧本地安装或 WSL 里的另一份安装，后面排查会很混乱。

先在准备工作的终端里检查版本和安装状态。Windows 上尤其要区分 PowerShell、CMD、Git Bash 和 WSL。

claude --version
claude doctor
where claude

Windows 先选原生还是 WSL

如果项目、Node、pnpm、Git 都在 Windows 侧，就用原生 Windows。Claude Code 没有 Git Bash 时会回落到 PowerShell；如果你希望它更像 Linux shell，先装 Git for Windows。

如果项目长期在 WSL、Docker、Linux 工具链里运行，就在 WSL 里安装并启动 Claude Code。不要一边从 Windows PowerShell 启动，一边让它操作 WSL 里的项目路径。

第一次进入项目只读代码

第一次打开 Claude Code，不要直接让它“优化项目”。它还不知道项目边界、启动命令、测试命令和哪些文件不能碰。

先让它只读项目，不改文件。目标是建立地图，而不是马上动刀。

先阅读项目结构，不要改文件。
请输出：
1. 主要模块边界
2. 启动命令、构建命令和测试命令
3. 你认为最容易出问题的配置文件
4. 真正动手修改前需要我确认的问题

写一个最小 CLAUDE.md

`CLAUDE.md` 是 Claude Code 的项目记忆。它适合放项目约定、构建命令、测试命令、代码风格和不能破坏的边界。

第一版不要写成长文档。Claude Code 的上下文不是无限的。先写能改变行为的几条规则。

# Claude Code Project Notes

Commands:
- pnpm run lint
- pnpm run typecheck
- pnpm run build

Rules:
- Use pnpm only.
- Keep edits scoped to the requested task.
- Do not change package versions unless the task requires it.
- Do not edit generated files manually.

Review:
- Report changed files.
- Report commands run and their results.
- Mention commands that were not run.

把规则拆进 .claude/rules

项目变大以后，不要把所有内容塞进一个 `CLAUDE.md`。官方文档支持用 `.claude/rules/` 组织规则，并且可以让规则按路径生效。

这适合前端、后端、文档、部署脚本各有约束的项目。越靠近具体目录，规则越应该具体。

CLAUDE.md
.claude/rules/frontend.md
.claude/rules/backend.md
.claude/rules/docs.md
.claude/rules/security.md

settings.json 只放团队可共享配置

`.claude/settings.json` 适合提交到仓库，放团队都应该遵守的配置。比如允许哪些安全命令、拒绝读哪些敏感文件、启用哪些项目插件。

不要把个人 API Key、个人模型偏好、只适合你机器的路径写进去。团队配置一旦提交，就会影响每个开发者。

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)"
    ]
  }
}

settings.local.json 放个人和机器差异

`.claude/settings.local.json` 适合放个人实验、当前机器路径和本地环境变量。Claude Code 创建这个文件时通常会把它加入忽略列表，避免误提交。

这个文件可以帮你区分“项目规则”和“我的机器怎么跑”。排查问题时也更清楚。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.example.com/anthropic",
    "ANTHROPIC_MODEL": "your-model-name"
  }
}

先 deny 敏感文件

Claude Code 能读项目文件，也能通过搜索发现文件。真实项目里，先保护 `.env`、密钥、凭证、构建产物和大目录。

这不是情绪问题，而是把不需要进入上下文的东西挡在外面。越少敏感信息进入上下文，后面越容易排查。

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./**/*.pem)",
      "Read(./**/*secret*)",
      "Read(./dist/**)",
      "Read(./node_modules/**)"
    ]
  }
}

用 permissions 收敛常用权限

Claude Code 每次问权限并不一定是坏事。问题是同一个安全命令反复问，会打断工作流。

先跑几轮真实任务，再把高频、低风险的命令加进允许列表。不要一开始就全开。

/permissions

不要长期跳过权限

`--dangerously-skip-permissions` 适合非常受控的临时场景，不适合当默认启动方式。它会让 Claude Code 少问你，但也会让错误命令更容易直接执行。

更好的路径是：默认保留权限提示，只把团队确认安全的命令加入 allowlist。这样方便，也可审计。

claude --dangerously-skip-permissions

环境变量只解决接入问题

`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、模型变量这些配置，只解决 Claude Code 请求发到哪里、用哪个身份、调用哪个模型。

不要用环境变量替代项目规则。接 DeepSeek、Bedrock、Vertex 或内部网关时，先确认入口格式是 Claude Code 支持的 Anthropic-compatible 链路，再谈模型名。

$env:ANTHROPIC_BASE_URL="https://api.example.com/anthropic"
$env:ANTHROPIC_AUTH_TOKEN="your-api-key"
$env:ANTHROPIC_MODEL="your-model-name"
claude

用 doctor 和 context 查配置

配置写完以后，不要靠感觉判断是否生效。先用 `claude doctor` 检查安装和设置，再在会话里用 `/context` 看当前上下文。

如果 Claude Code 没读到你期待的 `CLAUDE.md`、rules、settings 或 MCP，先查配置加载路径，不要继续改 prompt。

claude doctor
/context
/memory

重复动作做成 Skill 或 slash command

如果你每天都让 Claude Code 做同一套事，比如代码审查、CI 失败排查、前端验收、文档整理，就把它做成 Skill 或自定义命令。

好处不是少打几个字，而是让触发条件、步骤和验收标准固定下来。Agent 工作流最怕的是每次临场发挥。

.claude/skills/code-review/SKILL.md
.claude/skills/fix-ci/SKILL.md
.claude/commands/review.md

Hook 只放确定性动作

Hook 是 Claude Code 生命周期里的确定性插槽。适合记录命令、格式化代码、阻止危险 prompt、在停止前跑检查。

不要把复杂判断全部塞进 Hook。Hook 越像脚本和规则，越可靠；越像另一个智能体，越难排查。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm run lint || true"
          }
        ]
      }
    ]
  }
}

MCP 先接最常用系统

MCP 的价值是减少复制粘贴。Claude Code 能直接查 issue、PR、日志、Sentry、数据库或内部文档时，你才真正省上下文。

不要一口气接十几个 MCP。每接一个，就扩大一层可见范围和操作面。先接最常用、最可信、最容易验证的系统。

claude mcp --help
/mcp

配置完成后的验证清单

配完 Claude Code 后，用一个小任务验证，而不是马上交给它做大改。成功标准不是“能启动”，而是能读规则、按权限工作、跑验证命令并报告结果。

先用低风险任务试一轮。比如改一个文案、补一个测试、修一个 lint，再看它是否按你的配置行动。

请做一个最小验证任务：
1. 阅读 CLAUDE.md 和 .claude/settings.json
2. 只修改一个低风险文件
3. 运行项目指定的验证命令
4. 报告读取到的规则、修改文件和命令结果

记录当前可用配置

Claude Code 版本、安装方式、权限模式、Shell、网关入口和模型名都会变。修好一次后，把可用配置记录下来。

下次升级、换机器或接第三方模型时，先对比这份记录。不要从搜索结果里随机复制另一套配置。

日期：2026-06-05
系统：Windows / macOS / Linux / WSL
Shell：PowerShell / Git Bash / Zsh / Bash
Claude Code：填当前版本
安装方式：native / winget / homebrew / npm
项目记忆：CLAUDE.md + .claude/rules
权限文件：.claude/settings.json
个人配置：.claude/settings.local.json
最后验证任务：填任务名和结果

参考来源

相关文章