Claude Code 完整配置指南：从环境准备到 Skills 实战

Claude Code 完整配置指南：从环境准备到 Skills 实战

一句话：Claude Code 配置易上手、难精通。CLI 一行命令就能跑，但要把 Skills、Hooks、子代理、多项目工作流串起来，需要对每个配置位的作用心里有数。本文从环境准备讲到团队协作，是一篇给"装好之后怎么用得专业"的工程师准备的完整手册。

目录

1. Claude Code 是什么、能做什么
2. 环境准备：终端、Node.js、API Key
3. 基础配置：环境变量、模型选择、首跑测试
4. Skills 使用技巧：从内置到自定义
5. Hooks 自动化：把日常动作交给 Claude Code
6. 常见问题排查清单
7. 高级配置：代理、缓存、多项目隔离
8. 实战案例：项目规划与 Code Review
9. 团队协作配置
10. FAQ
11. 相关资料

Claude Code 是什么、能做什么

Claude Code 是 Anthropic 推出的命令行 AI 编程工具，区别于 Cursor / Continue 这种 IDE 内嵌的助手，它把"AI 编辑器"的逻辑反过来：编辑器是终端 + 你的工作目录，AI 在终端里以代理形态运作，能自主读文件、写文件、跑命令、起子代理。这种形态对长链路任务（多文件重构、跨服务迁移、整套测试与文档生成）友好得多。

成熟开发者用 Claude Code 时关心的不是"它会不会写代码"，而是：

• 模型选择是否得当（Sonnet / Opus / Haiku 在哪些任务上更划算）
• Skills 怎么让 AI 复用我团队的私有约定
• Hooks 怎么把"每次写完 Python 跑 ruff"自动化掉
• 多项目工作流如何配置才不互相串味

下面按这条路径展开。

环境准备：终端、Node.js、API Key

终端环境检查

# 终端版本
echo $SHELL

# Node.js 版本（要求 18+）
node --version

# npm 版本
npm --version

# Git 版本（Claude Code 大量依赖 git）
git --version

Node 版本不到 18 升级到 LTS（推荐 20.x）。Windows 用户强烈建议 WSL2 + Ubuntu，原生 PowerShell 在长任务、stdin 管道场景稳定性差一些。

安装 Claude Code CLI

npm install -g @anthropic-ai/claude-code
claude --version

更新机制是 npm 自管，需要时跑 npm update -g @anthropic-ai/claude-code。

准备 API Key

接 Anthropic 直连或接 CodeGateway 都能跑。本文以 CodeGateway 为例：

1. 注册 https://www.codegateway.dev，新账号绑定支付方式后可获得起步额度（折算购买力随所选模型价格变动，以 /models 定价页折算为准）。
2. Dashboard → API Keys → Create Key。
3. Key 前缀 sk-cg-，仅展示一次，及时存到密码管理器。

截图占位：API Key 创建页。

基础配置：环境变量、模型选择、首跑测试

环境变量

# ~/.zshrc 或 ~/.bashrc
export ANTHROPIC_BASE_URL="https://api.codegateway.dev"
export ANTHROPIC_API_KEY="sk-cg-xxxxxxxxxxxxxxxxxxxxxx"

# 默认模型（可按项目覆盖）
export ANTHROPIC_MODEL="claude-sonnet-4-6"

source ~/.zshrc 让变量生效。

模型选择

Anthropic 当下三个主力模型，对 Claude Code 工作流的对应关系：

按价值密度建议：把日常主力设 Sonnet，子代理（频繁调用、并行多个）切 Haiku，一次性架构决策 / 长 chain 推理切 Opus。

首跑测试

mkdir hello-claude && cd hello-claude
git init
echo "# Hello" > README.md

claude

进入交互式会话，输入：

请把这个仓库初始化成一个 Python 项目，用 uv 管理依赖，加一个基础的 hello.py，
并写一个小 pytest 测试。

正常情况下 Claude Code 会自主执行 uv init、写文件、运行测试，全程在终端 stream 输出。

Skills 使用技巧：从内置到自定义

什么是 Skill

Claude Code 的 Skills 是"可复用的行为规范"。每个 Skill 是一个目录，含 SKILL.md 描述触发条件、行为约束、引用的工具白名单。Skill 可以是个人级（~/.claude/skills/）也可以是项目级（.claude/skills/）。

举个例子，常用 Skill：

• tdd-workflow：强制先写测试再实现
• python-patterns：Pythonic 习惯 + PEP 8 + 类型提示
• golang-testing：Go 测试模式，table-driven 风格
• e2e-testing：Playwright Page Object Model 写法
• frontend-design：前端设计系统约定（颜色、字体、动效语言）

怎么调用 Skill

在 Claude Code 会话里：

/skill tdd-workflow

或者隐式触发：当 Claude Code 识别到任务匹配某个 Skill 描述时会自动加载。

自定义 Skill

新建 .claude/skills/my-team-react/SKILL.md：

---
name: my-team-react
description: 团队 React 组件约定。每次新增 React 组件时启用：使用函数组件 + TS、props 类型显式声明、CSS 用 CSS Modules、单元测试用 Vitest + RTL。
---

# 团队 React 约定

## 组件结构
- 函数组件 + TypeScript
- Props 接口命名 `<Component>Props`
- 默认导出，不使用 `React.FC`

## 样式
- CSS Modules（`Component.module.css`），不用 styled-components
- 主色变量统一引用 `tokens.css`

## 测试
- Vitest + React Testing Library
- 每个交互态至少一个测试用例
- 单元测试覆盖率 ≥ 80%

## 文件组织
- `Component.tsx` + `Component.module.css` + `Component.test.tsx`
- 同目录下放 `index.ts` 导出

之后 Claude Code 在该项目里写 React 组件就会按这套规范走。Skill 文件托到团队仓库，新人 clone 之后直接复用。

推荐 Skills 组合

按角色配 Skills：

Hooks 自动化：把日常动作交给 Claude Code

Hook 类型

Claude Code 提供三类 hook：

• PreToolUse：工具调用前触发（用来校验、修改参数、阻断）
• PostToolUse：工具调用后触发（自动格式化、运行 lint、跑测试）
• Stop：会话结束时触发（最终验证）

例子：写完 Python 自动跑 ruff

.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "ruff check --fix \"$FILE_PATH\" && ruff format \"$FILE_PATH\"",
        "description": "格式化 + lint Python 文件"
      }
    ]
  }
}

每次 Claude Code 写或编辑文件，hook 自动把对应文件 lint + 格式化一遍，避免最后统一收拾。

例子：会话结束自动 build

{
  "hooks": {
    "Stop": [
      {
        "command": "pnpm build",
        "description": "会话结束验证 production build"
      }
    ]
  }
}

适合本地开发当"最后一道闸"。

例子：写大文件直接拒绝

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const c=i.tool_input?.content||'';const lines=c.split('\\n').length;if(lines>800){console.error('[Hook] BLOCKED: 超过 800 行');process.exit(2)}console.log(d)})\"",
        "description": "阻止写超过 800 行的文件"
      }
    ]
  }
}

常见问题排查清单

高级配置：代理、缓存、多项目隔离

HTTP 代理

公司网络强制走 HTTP 代理时：

export HTTPS_PROXY=http://corp-proxy.example.com:8080
export HTTP_PROXY=http://corp-proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

如果公司代理使用自签证书，再加：

export NODE_EXTRA_CA_CERTS=/etc/ssl/corp-ca.pem

缓存策略

Claude Code 在客户端会缓存最近的 prompt / context 索引。占用过大时清理：

rm -rf ~/.claude/cache

服务侧（Anthropic 自己 / CodeGateway 透传）支持 prompt caching，长 context 重复使用时显著降低成本（具体折扣见 Anthropic 文档）。

多项目配置

不同项目想用不同模型 / 不同 hooks，落到 .claude/settings.json（项目级）覆盖个人级：

~/.claude/settings.json       # 个人默认
project-a/.claude/settings.json  # 项目 A 覆盖（更严格的 hook）
project-b/.claude/settings.json  # 项目 B 覆盖（不同模型）

Claude Code 启动时自动找最近的 .claude/settings.json 合并。项目级一直优先。

实战案例：项目规划与 Code Review

案例 1：从 PRD 到任务拆分

把 PRD（Markdown）丢到项目里，会话开头：

读 docs/PRD.md，按里程碑拆任务，每个任务给出验收条件、影响文件清单、预估工时。
输出到 docs/tasks.md。

Claude Code 会读文档、列任务、写文件。这种规划阶段建议挂 Opus 模型，深度推理优势更明显。

案例 2：Code Review

对当前 git diff 跑一遍 review，重点关注：
1. 是否有未处理的错误
2. 是否引入了硬编码密钥
3. 是否破坏了已有测试

按 CRITICAL / HIGH / MEDIUM / LOW 输出，含改动建议代码片段。

Claude Code 自动跑 git diff、读相关文件、出 review 报告。让团队节奏快很多。配合 code-reviewer Skill 时输出更结构化。

案例 3：跨服务重构

跨多个仓库改字段名是 Claude Code 擅长的典型场景之一。/agents 起 sub-agent 并行处理：

• agent A：跑 grep + 列出待改清单
• agent B：改后端服务
• agent C：改前端调用
• agent D：跑测试 + 报告失败项

主代理负责调度与汇总。Sub-agent 推荐用 Haiku，避免过高成本。

团队协作配置

公共 Skills 仓库

团队建一个 team-skills 仓库放共用 Skills：

team-skills/
├── react-conventions/SKILL.md
├── pr-template/SKILL.md
├── changelog-style/SKILL.md
└── README.md

每个项目通过 .claude/skills/ 软链或 git submodule 引入。

Hooks 标准化

CI 容易出现"本地没 lint，PR 一片红"的情况。把 lint / format / type-check hooks 写到 .claude/settings.json 并 commit 到仓库，团队里所有人在 Claude Code 写文件时都自动跑同一套质量门，CI 失败率显著下降。

共享 API Key 策略

不要共享个人 Key。CodeGateway 上每人单独账号，统一按 1.07× 倍率计费，不随消耗变化。共享 Key 会导致：

• 用量混乱，无法归责
• 上游 rate limit 触发后所有人一起停摆
• 一旦泄露需要全员重配

CI 单独申请 Key（命名 ci-<repo>），保存在 GitHub Actions / GitLab CI 的 Secrets 里。

FAQ

Q：Claude Code 和 Cursor 哪个更值？

A：两个工具的形态不同，不直接竞争。Cursor 是 IDE，强在交互式编辑、行内补全、UI 反馈。Claude Code 是终端代理，强在长链路任务、自动化、与 git / shell 工具链直接集成。日常做编辑器内编辑选 Cursor，做大块自动化任务选 Claude Code。完整对比参见Claude Code vs Cursor vs GitHub Copilot。

Q：Skills 和 Hooks 有什么区别？

A：Skills 偏"行为规范"，影响 Claude Code 怎么思考与组织代码；Hooks 偏"自动化机制"，在工具调用前后强制跑命令。两者经常组合：Skill 给规范，Hook 兜底执行。

Q：必须用 CodeGateway 吗？

A：不必须。Claude Code 原生支持 Anthropic 直连。CodeGateway 主要解决"接入复杂度 + 网络稳定性 + 计费灵活度"三个变量。具体取舍看直连 / 第三方代理 / CodeGateway 对比。

Q：Sub-agent 数量有上限吗？

A：Claude Code 客户端没硬上限，主要受网关 RPM 与并发数限制。CodeGateway 默认 RPM 比 Anthropic 直连宽松，正常用法下不会撞限。

Q：能不能在企业内网无外网环境跑？

A：不行。Claude Code 必须能访问模型 API。内网通常的方案是配置出口代理（参见上面"高级配置 → HTTP 代理"），或者部署 CodeGateway 自托管版本（联系企业版咨询）。

Q：配置文件能不能版本管理？

A：推荐。把 .claude/settings.json、.claude/skills/、.claude/hooks/ commit 到仓库，新成员 clone 之后零配置就能复用团队约定。注意 API Key 不要进仓库。

Q：怎么看自己花了多少钱？

A：CodeGateway Dashboard → Logs / Overview。Overview 顶上有 Total Tokens 卡片，Logs 支持时间范围筛选（Today / 7d / 30d / 90d / All），按模型按 Key 都能拆。详细计算公式见充值费用指南。

Q：Claude Code 会不会偷跑命令？

A：Claude Code 默认对潜在破坏性操作（rm -rf、git reset --hard、force push）会先请求用户确认。可以在 settings 里调整自动允许范围，但不要全开 --dangerously-skip-permissions，相当于把方向盘给了 AI。

相关资料

• Claude Code 5 分钟快速配置
• Claude Code 连接超时排查指南
• Claude Code vs Cursor vs GitHub Copilot
• 充值费用指南
• 统一倍率说明
• 错误排查指南
• Anthropic 官方文档：Claude Code Quickstart
• Anthropic 官方文档：Skills

把上面这些配置一次性铺开看似复杂，但实际接入路径很短：装 CLI → 配 Key 与默认模型 → 跑通一次会话。Skills 和 Hooks 是"用熟之后慢慢加"，不必一开始全配。配置文件 commit 到仓库，团队节奏自然对齐。