1.4 基础配置

.claude 目录结构

Claude Code 在项目中创建一个 .claude/ 目录，用于存放配置文件、规则、技能定义等。这些文件可以提交到 Git 共享给团队成员。

.claude/
├── CLAUDE.md              # 项目级指令，每次会话自动加载
├── settings.json         # 项目配置（权限、钩子、环境变量）
├── settings.local.json   # 本地覆盖配置（不提交到 Git）
├── .mcp.json             # MCP 服务器配置（团队共享）
├── rules/                 # 路径级规则目录
│   └── *.md              # 针对特定路径的指令文件
├── skills/                # 技能定义目录
│   └── <name>/
│       └── SKILL.md       # 技能定义，可通过 /<name> 调用
├── agents/                # 子代理定义目录
│   └── *.md               # 子代理定义文件
└── output-styles/         # 自定义输出格式目录
    └── *.md               # 输出格式定义

配置作用域优先级

Claude Code 的配置按优先级从高到低分为四个作用域，高优先级会覆盖低优先级：

settings.json 详解

核心配置文件，支持以下主要字段：

权限配置（permissions）

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm test)",
      "Bash(git *)"
    ],
    "deny": [
      "Bash(curl *)",
      "Bash(wget *)",
      "Bash(rm -rf / *)"
    ]
  }
}

权限规则使用 Bash(command) 格式，Claude Code 的 Bash 工具默认阻止 curl 和 wget 等可能用于下载任意内容的命令。

钩子配置（hooks）

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/filter.sh"
          }
        ]
      }
    ]
  }
}

钩子可以在工具执行后触发自动化操作，比如格式化输出、运行测试、检查代码风格。

环境变量（env）

{
  "env": {
    "NODE_ENV": "development",
    "LOG_LEVEL": "debug"
  }
}

模型选择（model）

{
  "model": "sonnet"
}

可选值：sonnet（默认）、opus（更高智能）、haiku（更快速）。

CLAUDE.md 项目指令

CLAUDE.md 是 Claude Code 最重要的配置文件，它在每次会话开始时被自动加载，用于向 Claude 传达项目的规范、约定和工作流程。

CLAUDE.md 放置位置（按优先级）

CLAUDE.md 编写建议

• 目标控制在 200 行以内；文件过长会降低 Claude 的遵从度
• 使用 Markdown 标题和列表结构，Claude 会扫描文件结构
• 包含：构建/测试命令、代码风格规范、命名约定、"always do X" 规则
• 当 Claude 犯同一个错误两次时，主动将纠正规则写入 CLAUDE.md

CLAUDE.md 示例

# 项目规范

## 构建与测试
- 使用 pnpm（不是 npm）。运行 `pnpm build` 构建。
- 提交前必须运行 `pnpm test`。

## 代码风格
- 2 空格缩进
- 所有新文件使用 TypeScript

## 项目结构
- API 路由放在 `src/api/`
- 组件放在 `src/components/`
- 禁止直接修改 `vendor/` 目录中的文件

## 特别指令
- 压缩上下文时，优先保留测试输出和代码变更记录。

路径级规则（.claude/rules/）

当项目包含多种不同技术栈时，可以按路径设置不同的规则：

.claude/rules/
├── python.md     # 仅在 Python 代码目录激活
├── frontend.md   # 仅在 React/前端目录激活
└── api.md        # 仅在 API 目录激活

Claude 会根据当前工作路径自动加载对应的规则文件。

技能定义（.claude/skills/）

技能是可复用的工作流定义，通过 /skill-name 命令调用：

.claude/skills/
└── code-review/
    └── SKILL.md

编写好 SKILL.md 后，在对话中输入 /code-review 即可触发该技能定义的工作流程。

环境变量配置

除 settings.json 外，还可以通过系统环境变量配置 Claude Code：

凭据管理

Claude Code 的认证凭据存储位置：

• macOS：加密存储在 macOS Keychain 中
• Linux：~/.claude/.credentials.json（权限 0600）
• Windows：受用户配置文件访问控制
• API Key Helper：通过 apiKeyHelper 设置项运行自定义脚本动态返回 API Key

运行诊断

配置完成后，可以通过以下命令验证：

claude doctor        # 在终端直接运行，检查安装和配置状态
claude --debug        # 启用调试模式，输出详细日志
claude --debug "api,hooks"   # 仅过滤特定类别的调试信息

在 Claude Code 会话中，也可以输入 /doctor 运行自动化诊断。