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

正文

Claude Code 很强，但它不是“装好就万事大吉”的工具。它能读代码、改文件、运行命令、调用工具，甚至可以连续完成多步开发任务。也正因为它足够主动，如果配置没做好，就容易出现三个问题：它不知道项目规则、它频繁打断你、它可能碰到不该碰的文件。

所以，使用 Claude Code 前，建议先把这 7 件事配好。配完之后，你会明显感觉它更像一个懂项目边界、知道团队规范、能安全协作的结对程序员。

先搞清楚 Claude Code 的配置文件放在哪里

Claude Code 的配置主要围绕 settings.json 和 CLAUDE.md 展开。官方文档说明，Claude Code 可以通过交互式 REPL 里的 /config 命令打开设置界面，也可以使用配置文件管理行为。

常见配置位置可以这样理解：

一个简单的项目配置示例：

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(.env)",
      "Read(**/.env)"
    ]
  }
}

这份配置表达了一个清晰边界：Claude Code 可以运行测试、检查代码、查看 Git 状态，但不能执行危险删除命令，也不能读取 .env 文件。

建议：个人习惯放在 ~/.claude/settings.json，团队规则放在 .claude/settings.json，私有本地配置放在 .claude/settings.local.json。这样分层最清楚，也最不容易互相污染。

配好权限：先决定 Claude Code 能做什么，不能做什么

Claude Code 最大的价值之一，是它能直接操作项目。但这也是最需要控制的地方。官方权限文档说明，可以用 /permissions 查看和管理工具权限，并能看到规则来自哪个 settings.json 文件。

权限配置建议遵循一个原则：默认谨慎，逐步放开。

你不需要一开始就允许 Claude Code 做所有事。更好的做法是先开放安全命令，再根据项目需要逐步增加。

推荐基础权限：

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff)",
      "Bash(git log --oneline -10)",
      "Bash(npm test)",
      "Bash(npm run test)",
      "Bash(npm run lint)",
      "Bash(npm run typecheck)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(chmod -R 777 *)",
      "Bash(curl * | sh)",
      "Bash(wget * | sh)",
      "Read(.env)",
      "Read(**/.env)",
      "Read(**/id_rsa)",
      "Read(**/credentials*)"
    ]
  }
}

这份配置适合大多数 JavaScript、TypeScript、Node.js 项目。如果你的项目是 Python，可以把测试和检查命令换成 pytest、ruff check .、mypy .。

如果你是后端项目，还要特别小心数据库相关命令。不要让 Claude Code 默认拥有生产数据库权限，更不要让它自动执行迁移、删除、清库、重置等命令。

Claude Code 越像结对程序员，你越应该像对待真实同事一样给它边界。能看什么、能跑什么、能改什么，都应该提前说清楚。

后端项目要额外拒绝数据库危险命令

建议增加这些拒绝规则：

{
  "permissions": {
    "deny": [
      "Bash(*DROP DATABASE*)",
      "Bash(*TRUNCATE*)",
      "Bash(*DELETE FROM*)",
      "Bash(*prisma migrate deploy*)",
      "Bash(*sequelize db:migrate*)",
      "Bash(*rails db:drop*)",
      "Bash(*rails db:reset*)"
    ]
  }
}

数据库、生产配置、迁移命令、清理命令都不应该默认自动执行。需要执行时，先让 Claude Code 解释影响范围、回滚路径和验证方法，再由人确认。

配好 CLAUDE.md：让它真正理解你的项目

CLAUDE.md 是 Claude Code 非常重要的项目记忆文件。官方记忆文档说明，每个 Claude Code 会话都会从新的上下文窗口开始，而 CLAUDE.md 可以提供跨会话保留的持久指令和项目知识。

简单说，settings.json 管“权限和行为”，CLAUDE.md 管“项目知识和工作方式”。

推荐在项目根目录创建 CLAUDE.md，然后写入项目规则：

# Project Guide for Claude Code

## 项目简介
这是一个基于 Next.js + TypeScript 的后台管理系统，用于管理订单、用户和报表数据。

## 技术栈
- Next.js
- TypeScript
- React
- Tailwind CSS
- Prisma
- PostgreSQL
- Vitest

## 常用命令
- 安装依赖：npm install
- 本地开发：npm run dev
- 运行测试：npm test
- 类型检查：npm run typecheck
- 代码检查：npm run lint
- 构建项目：npm run build

## 代码规范
- 所有新代码必须使用 TypeScript
- 不要使用 any，除非有明确理由
- React 组件使用函数组件
- API 返回值必须有明确类型
- 新功能必须补充测试
- 修改数据库 schema 前必须先说明原因和影响

## 安全规则
- 不要读取 .env 文件
- 不要输出密钥、token、cookie
- 不要直接连接生产数据库
- 不要执行删除数据库或重置数据库的命令

## 工作方式
在修改代码前，请先：
1. 阅读相关文件
2. 简述修改计划
3. 再开始编辑
4. 修改后运行 lint、typecheck 和测试
5. 最后总结变更点和风险

这份 CLAUDE.md 不需要写得花哨，但一定要具体。不要只写“请写高质量代码”，而要告诉它什么叫高质量：用什么技术栈、跑什么命令、遵守什么目录结构、禁止什么操作。

一个好用的 CLAUDE.md 通常包含项目简介、技术栈、常用命令、目录结构、编码规范、安全规则和工作流程。

大项目可以拆分多个 CLAUDE.md

如果项目很大，可以在子目录中补充更具体的 CLAUDE.md。

frontend/CLAUDE.md
backend/CLAUDE.md
packages/ui/CLAUDE.md

这样 Claude Code 进入不同模块时，可以获得更贴近当前目录的上下文。

配好忽略规则：别让 Claude Code 读错东西

很多项目里都有一些不该被 AI 读取的内容，比如环境变量、密钥、构建产物、日志、数据库备份、大型依赖目录等。即使你在权限里拒绝读取 .env，也建议再用忽略规则做一层保护。

你可以创建 .claudeignore，然后写入：

.env
.env.*
*.pem
*.key
*.crt
*.p12
*.sqlite
*.db
*.log
node_modules/
dist/
build/
coverage/
.next/
.cache/
tmp/
secrets/
credentials/
private/

这类文件通常不需要 Claude Code 读取。特别是 .env、证书、私钥、数据库文件，应该默认排除。

如果你的项目有生成代码，也可以根据情况忽略 generated/、openapi-generated/、prisma/generated/。但这里要注意：有些生成代码虽然不该改，却可能需要读。比如 SDK 类型、API 类型定义、数据库类型声明。如果 Claude Code 需要理解它们，可以只在 CLAUDE.md 里说明“不要修改 generated 目录”，而不是完全忽略。

推荐规则是：密钥类文件必须忽略；构建产物和依赖目录建议忽略；生成代码视项目情况决定；业务配置不要盲目忽略。

Claude Code 的效果很依赖上下文。忽略规则不是越多越好，而是要把危险和噪音隔离掉，同时保留它完成任务所需的信息。

配好 MCP：只连接真正需要的外部工具

MCP，也就是 Model Context Protocol，是 Claude Code 连接外部工具和数据源的重要方式。它可以让 Claude Code 接入 GitHub、数据库、文档系统、浏览器自动化、内部工具等。

但 MCP 不是越多越好。每多接一个 MCP 服务，就多一个权限边界和安全风险。官方 Hooks 文档也提到 Claude Code 支持 MCP tool hooks，这说明 MCP 工具调用已经是 Claude Code 生命周期中可以被精细控制的一部分。

建议你先只配置最必要的 MCP：

一个安全的 MCP 使用原则是：开发环境可以接，生产环境不要接；只读优先，写入慎重。

数据库 MCP 只给只读非生产账号

如果你配置数据库 MCP，建议只给只读账号，并且连接测试库或 staging 库。

DATABASE_URL=postgresql://readonly_user:password@localhost:5432/app_staging

不要把生产库连接直接给 Claude Code。即使你非常信任模型，也不应该让 AI agent 默认靠近生产数据。

在团队里，MCP 配置最好统一审查。不要让每个开发者各自随意添加工具，否则安全边界会变得很难管理。

配好 Hooks：让 Claude Code 自动做检查，但别滥用

Hooks 是 Claude Code 的高级能力。官方 Hooks 文档说明，Hooks 可以是在 Claude Code 生命周期特定节点自动执行的 shell 命令、HTTP endpoint 或 LLM prompt。

Hooks 的价值很大。比如你可以在 Claude Code 修改文件后自动运行格式化，或者在它准备提交前自动跑测试。

常见 Hook 场景：

示例配置：

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

这表示 Claude Code 在编辑文件后，可以自动运行 lint。

不过，Hooks 一定要克制使用。不要把耗时很长、影响范围很大、可能修改数据的命令放进 Hook。Hooks 的目标不是“让 Claude Code 自动干所有事”，而是“让 Claude Code 每一步都自动被验证”。这两者差别很大。

Hooks 推荐和不推荐命令

推荐 Hook：

npm run lint
npm run typecheck
npm test
prettier --check .
ruff check .
pytest

不推荐 Hook：npm run deploy、npm run db:migrate、docker compose down -v、rails db:reset、terraform apply、kubectl delete。

配好环境变量：把默认行为固定下来

Claude Code 支持通过环境变量控制行为。官方环境变量文档说明，可以在 shell 中设置环境变量，也可以把变量放到 settings.json 的 env 字段中，这样 Claude Code 启动时会直接读取。

推荐把团队共用、非敏感的环境变量写进项目配置，把个人私密变量留在本地 shell 或本地配置中。

示例：

{
  "env": {
    "NODE_ENV": "development",
    "CI": "true",
    "FORCE_COLOR": "1"
  }
}

这类配置比较安全，因为它们不包含密钥。

不要把 OPENAI_API_KEY、生产 DATABASE_URL、AWS_SECRET_ACCESS_KEY 这类密钥写进仓库配置。密钥不应该提交到仓库，也不应该暴露给 Claude Code。即使是本地配置，也要谨慎。

更好的方式是：密钥放在本地环境变量管理器中；Claude Code 默认不读取 .env；测试使用假数据或本地模拟服务；数据库连接使用只读、非生产账号；CI/CD 中单独配置受控 secret。

团队环境变量可以只放非敏感标记

如果团队多人使用 Claude Code，建议约定：

{
  "env": {
    "CLAUDE_CODE_PROJECT": "admin-dashboard",
    "CLAUDE_CODE_ENV": "local-dev"
  }
}

这样在脚本、Hooks 或日志里可以明确知道当前 Claude Code 运行在哪个项目和环境中。

推荐的一套 Claude Code 起步配置

下面是一份可以直接复制后按项目调整的基础配置。

文件路径：.claude/settings.json。

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff)",
      "Bash(git log --oneline -10)",
      "Bash(npm test)",
      "Bash(npm run test)",
      "Bash(npm run lint)",
      "Bash(npm run typecheck)",
      "Bash(npm run build)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(chmod -R 777 *)",
      "Bash(curl * | sh)",
      "Bash(wget * | sh)",
      "Bash(*DROP DATABASE*)",
      "Bash(*TRUNCATE*)",
      "Bash(*DELETE FROM*)",
      "Read(.env)",
      "Read(**/.env)",
      "Read(**/id_rsa)",
      "Read(**/credentials*)",
      "Read(**/secrets*)"
    ]
  },
  "env": {
    "NODE_ENV": "development",
    "CI": "true",
    "FORCE_COLOR": "1"
  }
}

这一套配置不复杂，但足够稳。它既告诉 Claude Code 项目怎么做，也告诉它什么不能做。

起步配置还需要 .claudeignore 和 CLAUDE.md

再创建 .claudeignore，写入 .env、.env.*、*.pem、*.key、node_modules/、dist/、build/、coverage/、.next/、.cache/、secrets/、credentials/、private/ 等危险或噪音路径。

最后创建 CLAUDE.md，写清项目简介、技术栈、常用命令、代码规范、安全规则和工作流程。

# Claude Code Project Guide

## 项目简介
请在这里写清楚项目用途、主要用户、核心业务模块。

## 技术栈
- 请填写前端框架
- 请填写后端框架
- 请填写数据库
- 请填写测试工具

## 常用命令
- 安装依赖：
- 启动开发：
- 运行测试：
- 类型检查：
- 代码检查：
- 构建项目：

## 代码规范
- 修改代码前先阅读相关文件
- 新功能必须补充测试
- 不要随意引入新依赖
- 不要修改与任务无关的文件
- 不要使用 any，除非说明原因
- 不要删除现有测试，除非测试已经失效且说明原因

## 安全规则
- 不要读取 .env 文件
- 不要输出密钥、token、cookie
- 不要连接生产数据库
- 不要执行破坏性数据库命令
- 不要执行部署命令

## 工作流程
1. 先理解任务和相关文件
2. 简要说明计划
3. 再修改代码
4. 修改后运行测试和检查
5. 最后总结改动、验证结果和潜在风险

Claude Code 配置常见错误

只写 CLAUDE.md，不配权限，是很常见的错误。CLAUDE.md 是指令，不是硬边界。你可以在里面写“不要读取 .env”，但更稳妥的做法是在权限和忽略规则里也禁止它。

正确做法：

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

再配合 .claudeignore 忽略 .env 和 .env.*。

不要一上来就允许所有 Bash 命令

很多人为了省事，会给 Claude Code 很宽的命令权限。但 AI coding agent 能执行命令，就意味着它可能造成真实影响。

更好的做法是先允许这些安全命令：

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff)",
      "Bash(npm test)",
      "Bash(npm run lint)"
    ]
  }
}

不确定的命令，先让它请求确认。

不要把生产环境变量交给 Claude Code

Claude Code 不应该默认拥有生产环境密钥。无论是 .env.production、数据库连接串，还是云服务 token，都应该和 AI agent 隔离。

尤其是数据库权限，要坚持：本地库优先、测试库优先、只读账号优先、禁止生产写权限、禁止自动迁移生产库。

Hooks 不要写得太激进

Hooks 很强，但不能乱用。自动运行 lint、test、typecheck 是好事；自动 deploy、migrate、delete、reset 就很危险。

推荐 Hook：

npm run lint
npm run typecheck
npm test

不推荐 Hook：npm run deploy、terraform apply、kubectl delete、rails db:reset。

团队要统一配置

如果团队里每个人都用 Claude Code，但配置完全不同，就会出现结果不一致。有的人允许执行测试，有的人不允许；有的人能读某些目录，有的人不能；有的人遵守项目规则，有的人没加载规则。

建议把这些文件纳入团队规范：CLAUDE.md、.claude/settings.json、.claudeignore。

不要提交：.claude/settings.local.json、.env、.env.*。

Claude Code 配置验证清单

每次新项目接入 Claude Code 前，可以按这份清单检查。

FAQ：Claude Code 配置常见问题

最重要的配置文件是 CLAUDE.md 和 .claude/settings.json。前者告诉 Claude Code 项目规则和工作方式，后者控制权限、环境变量、Hooks 等行为。

CLAUDE.md 通常应该提交到 Git。它是项目级协作说明，能让团队成员使用 Claude Code 时获得一致的项目上下文。

.claude/settings.json 如果里面是团队共享规则，可以提交。如果包含个人路径、私密变量、本地实验配置，就不要提交。个人配置应放在本地配置文件中。

Claude Code 技术上可能可以读取 .env，但不建议允许。更安全的做法是在权限和忽略规则里禁止读取 .env、密钥、证书和凭据文件。

MCP 不需要一开始就配置。先用 Claude Code 完成本地代码阅读、修改、测试。等流程稳定后，再按需接入 GitHub、文档系统或测试工具。数据库和生产系统要特别谨慎。

Hooks 适合自动运行低风险验证命令，比如 lint、typecheck、unit test、formatter check。不要用 Hooks 自动部署、删除资源、重置数据库或执行生产变更。

Claude Code 不建议一开始就完全自动化。它更适合作为结对程序员：它可以主动完成任务，但你仍然应该保留关键审批、代码审查和测试验证。

总结：Claude Code 好不好用，关键在配置边界

Claude Code 的强大之处，不只是会写代码，而是能在你的项目里持续工作。它会读文件、理解上下文、执行命令、修改代码、总结结果。这样的工具一旦配置好，确实能像一位可靠的结对程序员。

但前提是，你要先把边界配清楚。

这 7 件事建议优先完成：

• 配好 settings.json 的层级。
• 配好权限规则。
• 写好 CLAUDE.md 项目记忆。
• 配好 .claudeignore。
• 谨慎接入 MCP。
• 克制使用 Hooks。
• 管好环境变量和团队配置。

真正高效的 Claude Code 工作流，不是让它“什么都能做”，而是让它“知道该做什么，也知道不该做什么”。当配置、权限、记忆和验证流程都到位后，Claude Code 才能从一个聪明的聊天助手，变成一个可靠的工程协作者。

参考来源

相关文章