Claude Code 开发配置

简介

Claude Code 的开发配置用于控制本地开发时 Agent 的行为、权限、工具、上下文规则。开发配置区别于生产部署，目标是方便调试、快速迭代，同时避免误操作修改业务代码。

配置生效优先级：命令行参数 > 环境变量 > 项目目录下配置文件 > 全局用户配置。

前置准备

已安装 Claude Code CLI / VS Code / JetBrains 插件
项目根目录可读写权限
理解 .claude/ 目录结构（前面章节《Claude Code 项目目录结构》）

一、配置文件说明

1. 项目本地配置（推荐，仅当前项目生效）

路径：./.claude/config.json
项目专属配置，提交到代码仓库，团队成员共享一套开发规则。

示例 config.json

{
  "model": "claude-3-5-sonnet-latest",
  "maxToolTurns": 10,
  "autoMemory": false,
  "permissions": {
    "read": true,
    "write": true,
    "bash": false
  },
  "contextWindow": "auto",
  "outputStyle": "markdown"
}

2. 全局用户配置（本机所有项目生效）

Linux/macOS：~/.config/claude-code/config.json
Windows：%APPDATA%/claude-code/config.json

全局配置优先级低于项目配置，适合个人偏好设置，不要提交到代码仓库。

3. CLAUDE.md（项目行为规则）

路径：./CLAUDE.md
不属于 config.json，但属于开发最重要配置文件。用来定义项目编码规范、项目介绍、文件阅读优先级、Agent 行为约束。开发阶段必写。

示例片段：

# 项目说明
这是一个前端Nuxt项目，使用 TailwindCSS v4。## 编码规则
1. 优先使用TypeScript，类型严格
2. 组件使用shadcn/ui
3. 修改代码前先阅读相关文件
4. 禁止直接修改.env文件

二、核心配置项详解

配置项	说明	开发环境推荐值
model	使用模型名称	`claude-3-5-sonnet-latest`
maxToolTurns	单次会话最大工具调用轮次，防止死循环	10
autoMemory	是否开启自动记忆	false（开发调试建议关闭）
permissions.read	文件读取权限	true
permissions.write	文件写入权限	true
permissions.bash	Shell命令执行权限	false（开发高危，按需开启）
ignore	额外忽略文件列表，补充.gitignore	`["*.log", ".env"]`
skillsDir	自定义技能目录路径	`./.claude/skills`
hooksDir	钩子脚本目录	`./.claude/hooks`

三、开发环境变量配置

开发环境放在项目根目录 .env 文件，不要提交到Git，加入 .gitignore。

# API配置
ANTHROPIC_API_KEY=sk-xxx
# 调试日志
CLAUDE_CODE_LOG_LEVEL=debug
# 关闭自动记忆
CLAUDE_CODE_NO_MEMORY=true
# 禁用MCP（开发需要MCP时再打开）
CLAUDE_CODE_NO_MCP=true
# 默认权限模式：read / edit / bash
CLAUDE_DEFAULT_MODE=edit

环境变量会覆盖 config.json 里面同名配置。

四、IDE 插件开发配置

VS Code

打开设置，搜索 Claude Code
常用设置：
- Enable Debug Log：开启调试日志
- Default Mode：edit
- Auto start session：false
- Load project CLAUDE.md：true
可以在工作区 .vscode/settings.json 单独配置，仅当前项目生效。

JetBrains IDE（IDEA/WebStorm等）

打开插件设置 Claude Code
支持指定项目 .claude 目录位置
勾选 Show debug logs，调试时查看Agent工具调用详情
会话权限默认设置为 edit，避免误执行bash

五、忽略文件配置

.claude/ignore，语法和 .gitignore 一致，Claude Code不会读取匹配文件。
开发推荐写入：

.env
*.env
node_modules/
dist/
build/
*.log

.gitignore 不会自动被Claude Code读取，需要单独在 .claude/ignore 配置。

六、开发常用斜杠命令（调试配置）

/config          查看当前生效全部配置
/reset           重置当前会话，清空上下文
/checkpoint      创建会话检查点，方便回滚调试
/skills          查看加载的所有技能
/clear-memory    清空记忆（autoMemory开启时）

七、开发环境最佳实践

项目配置提交Git，.env不要提交
config.json、CLAUDE.md、.claude/ignore 团队共享；密钥放本地 .env。
开发默认关闭 bash 权限，需要执行命令时手动临时开启。
关闭 autoMemory：避免跨会话记忆污染，调试更可控。
调试时开启 debug 日志，定位工具调用、上下文问题。
每次切换分支，执行 /reset 重置会话，防止旧上下文干扰。
限制 maxToolTurns，防止无限循环调用工具，浪费额度。

八、常见配置问题

配置修改不生效

检查优先级：环境变量覆盖配置文件；修改后重启会话/重启IDE。

Claude Code读取了.env密钥文件

在 .claude/ignore 添加 .env，阻止读取。

团队成员本地权限不一致

在项目 config.json 统一权限，统一默认模式。

记忆内容干扰新会话

开发环境强制设置 autoMemory:false。

小结

Claude Code开发配置核心：项目config.json定义团队共享规则，CLAUDE.md定义项目编码规范，.env存放本地密钥，.claude/ignore控制文件访问范围。开发环境优先关闭bash、自动记忆，打开调试日志，方便本地调试，同时降低误操作风险。

简介