Claude Code 完整指南：从新手到专家的进阶之路

Claude Code 不仅仅是一个简单的 AI 聊天工具，它是 Anthropic 打造的一款强大的命令行 AI 编程助手。本文将深入讲解 Claude Code 的核心功能和最佳实践，帮助你从新手快速进阶为专家。

快速开始

安装 Claude Code

根据你的操作系统选择合适的安装方式：

macOS/Linux:

curl -fsSL https://claude.ai/install.sh | bash

Windows:

irm https://claude.ai/install.ps1 | iex

使用 NPM:

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

使用 Homebrew (macOS):

brew install --cask claude-code

启动使用

安装完成后，在你的项目目录中运行：

cd your-project
claude

核心组件详解

1. CLAUDE.md - 代理配置文件

CLAUDE.md 是 Claude Code 的”宪法”，定义了代理的行为准则和约束。这个配置文件应该简洁明了，专注于关键规则，避免嵌入大量文档。

推荐的 CLAUDE.md 结构：

# 项目概述
简要描述项目目标和背景

## 技术栈
- 前端：React 18 + TypeScript + Vite
- 后端：Node.js + Express
- 数据库：PostgreSQL
- 样式：TailwindCSS

## 开发命令
- `npm install` - 安装依赖
- `npm run dev` - 启动开发服务器
- `npm run test` - 运行测试
- `npm run lint` - 代码检查

## 编码规范
- 使用 2 空格缩进
- 优先使用 async/await 处理异步
- 所有函数必须有 JSDoc 注释
- TypeScript 严格模式

## Git 工作流
- 功能分支命名：`feature/功能名`
- 优先使用 rebase 而不是 merge
- Commit 格式：`type: description`
  - feat: 新功能
  - fix: 修复
  - refactor: 重构
  - docs: 文档

## 文件结构
- `src/` - 源代码
- `tests/` - 测试文件
- `scripts/` - 工具脚本
- `migrations/` - 数据库迁移

## 已知问题
- API 限流：单 IP 每分钟 100 次请求
- 避免在 Windows 上使用符号链接

## 代码风格偏好
- 简洁优于复杂
- 有疑问时向用户询问

关键要点：

保持简洁，避免冗长
专注于项目特定的规则和约束
不要复制粘贴整个框架文档
定期更新以反映项目变化

2. 上下文管理

长时间会话中，上下文管理至关重要。Claude Code 提供了多种工具帮助你管理 token 使用。

检查上下文使用

使用 /context 命令查看当前会话的 token 使用情况：

/context

输出示例：

当前上下文: 45,234 tokens / 200,000 tokens (22.6%)
- 对话历史: 12,450 tokens
- 文件内容: 28,340 tokens
- 系统提示: 4,444 tokens

清空并重载上下文

当接近 token 上限时，使用 /clear + /catchup 组合：

# 1. 清空对话历史
/clear

# 2. 从 Git 分支重载变更文件
/catchup main

这个组合会清除对话历史，然后从指定的 Git 分支或 commit 重新加载变更的文件。

“文档与清空” 工作流

对于复杂的长期任务：

保存计划到 Markdown 文件

将当前的重构计划保存到 docs/refactor-plan.md

清空上下文
```
/clear
```

从保存的文件重新开始

阅读 docs/refactor-plan.md 并继续执行重构

3. 斜杠命令速查表

命令	功能	使用场景
`/catchup`	从 Git 分支加载变更文件	切换分支或更新上下文
`/clear`	清空对话历史	上下文过载或开始新任务
`/add-dir`	添加目录到工作区	扩展代码扫描范围
`/mcp`	管理 MCP 服务器	连接外部工具和数据源
`/model`	切换模型版本	根据任务选择 Sonnet 或 Opus
`/pr`	准备 Pull Request	自动生成 PR 描述
`/agents`	访问子代理	委托复杂任务
`/context`	查看 token 使用情况	监控上下文消耗

4. Plan Mode (计划模式)

对于复杂任务，Plan Mode 让 Claude 在编码前先制定实施计划，允许你审查和改进方案。

适用场景：

大型功能开发
代码重构
架构变更
跨多个文件的修改

使用方法：

使用 Plan Mode 帮我重构整个认证系统

Claude 会：

分析现有代码结构
制定详细的重构步骤
展示计划供你审查
等待你的确认后执行

示例输出：

## 认证系统重构计划

### 第一步：分析现有实现
- 扫描 src/auth/ 目录
- 识别依赖关系
- 记录当前的安全漏洞

### 第二步：设计新架构
- 采用 JWT 替代 session
- 实现 refresh token 机制
- 添加 rate limiting

### 第三步：实施迁移
- 创建新的 auth 模块
- 更新所有 API 端点
- 迁移用户数据

### 第四步：测试与验证
- 编写单元测试
- 进行集成测试
- 安全性测试

是否继续执行？

5. 子代理与任务委托

Claude Code 支持创建子代理（subagents）来处理复杂任务。推荐使用”主控-克隆”架构，通过 Task(...) 保持灵活性。

使用场景：

并行处理多个独立任务
隔离复杂的重构工作
实验性功能开发

示例：

创建一个子代理来优化数据库查询，同时我继续开发前端功能

主控-克隆架构的优势：

保持上下文一致性
避免过度专业化的代理
更好的灵活性和可维护性

6. Claude Skills vs MCP

这是两个容易混淆的概念，理解它们的区别很重要：

Claude Skills (技能)

用途： 传授程序性知识和领域特定工作流

特点：

按需加载，节省 token
教授”如何做”
适合编码模式、最佳实践
轻量级实现

示例：

# skills/testing-strategy.md

## 测试金字塔原则
1. 大量单元测试（70%）
2. 适量集成测试（20%）
3. 少量 E2E 测试（10%）

## 单元测试模板
describe('Component', () => {
  it('should render correctly', () => {
    // Arrange
    // Act
    // Assert
  });
});

Model Context Protocol (MCP)

用途： 连接外部工具和数据源

特点：

提供数据访问能力
启用 API、数据库、系统工具
可能消耗大量 token
需要谨慎启用

关键区别：

Skills 教授”怎么做”
MCP 提供”访问什么”

推荐实践：

优先使用 Skills 传授知识
仅在需要外部数据时使用 MCP
定期审查 MCP 工具的使用情况

7. Hooks 自动化

Hooks 允许你在 Claude 执行特定操作时自动运行命令，强制执行规则。

Hook 类型

1. Block-at-submit（提交时阻止）

阻止不符合规则的操作
例如：阻止未通过测试的 commit

2. Hint hooks（提示性 hooks）

非阻塞性的建议
提供指导而不强制

配置示例

在 .claude/settings.toml 中配置：

[[hooks]]
event = "PostToolUse"

[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py", "api/**/*.py"]

command = "ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"
run_in_background = false

这个 hook 会：

监听文件编辑事件
匹配 Python 文件
自动运行代码格式化工具

最佳实践

避免 block-at-write hooks：

# ❌ 不推荐：在写入时阻止
[[hooks]]
event = "PreToolUse"
tool_name = "write_file"
command = "exit 1"  # 会阻碍 Claude 工作

推荐 post-validation hooks：

# ✅ 推荐：完成后验证
[[hooks]]
event = "PostToolUse"
tool_name = "write_file"
command = "npm run lint $CLAUDE_FILE_PATHS"

原因： 让 Claude 完成计划，然后验证，而不是在过程中阻止。

8. CLI SDK

Claude Code 提供了 SDK，支持脚本化和批量操作。

安装：

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

使用场景：

批量重构
自动化代码生成
内部工具集成
代理原型开发

示例（TypeScript）：

import { ClaudeAgent } from '@anthropic-ai/claude-agent-sdk';

const agent = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: 'claude-sonnet-4-5'
});

// 批量重构
const files = await glob('src/**/*.js');
for (const file of files) {
  await agent.run({
    prompt: `将 ${file} 转换为 TypeScript，添加类型注解`
  });
}

9. GitHub Actions 集成

将 Claude Code 集成到 CI/CD 流程中，实现自动化代码审查和标准执行。

功能：

自动生成 Pull Request
强制执行代码标准
运行 CLAUDE.md 驱动的检查
审计代理行为

示例工作流（.github/workflows/claude-review.yml）：

name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Claude Code
        run: |
          npm install -g @anthropic-ai/claude-code

      - name: Run Claude Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "审查这个 PR 的代码变更，检查是否符合 CLAUDE.md 中的规范"

      - name: Generate Review Report
        run: |
          claude -p "生成代码审查报告，包括改进建议"

收益：

一致的代码质量
自动化的最佳实践执行
详细的审计日志
持续改进反馈

10. 设置与配置

通过 settings.json 自定义 Claude Code 的行为。

权限控制

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

作用：

防止 Claude 访问敏感文件
限制危险命令执行
定义安全边界

环境变量配置

{
  "env": {
    "HTTPS_PROXY": "http://proxy.company.com:8080",
    "MCP_TOOL_TIMEOUT": "30000",
    "BASH_MAX_TIMEOUT_MS": "120000",
    "ANTHROPIC_API_KEY": "your-api-key",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

常用配置：

HTTPS_PROXY - 代理服务器
MCP_TOOL_TIMEOUT - MCP 工具超时时间
BASH_MAX_TIMEOUT_MS - Bash 命令最大执行时间

高级功能

1. 模型切换

根据任务复杂度选择合适的模型：

# 使用 Sonnet (成本优化)
/model claude-sonnet-4-5

# 使用 Opus (复杂任务)
/model claude-opus-4-5

选择建议：

Sonnet 4.5： 日常编码、重构、文档编写
Opus 4.5： 复杂架构设计、大规模重构、性能优化

2. 思维模式调整

控制 Claude 的推理深度：

# 标准模式
/think

# 深度思考
/think hard

# 更深度思考
/think harder

# 超级思考
/ultrathink

使用场景：

简单任务：标准模式
算法优化：深度思考
架构设计：超级思考

3. 自定义命令

在 .claude/commands 目录创建可复用的命令：

示例：review-pr.md

审查 PR #{{pr_number}}，检查：

1. 代码是否符合 CLAUDE.md 规范
2. 是否有测试覆盖
3. 是否有安全漏洞
4. 性能影响分析

生成详细的审查报告。

使用：

/review-pr pr_number=123

4. 会话历史恢复

恢复之前的会话：

# 恢复最近会话
claude --resume

# 继续上次会话
claude --continue

场景：

意外中断的长时间重构
跨天持续的大型任务
需要回顾之前的决策

5. 反馈循环

持续改进 Claude Code 的表现：

审查操作日志
- 检查 Claude 执行的命令
- 识别不理想的行为
更新 CLAUDE.md
- 添加新的规则
- 明确偏好和约束
测试与验证
- 在新会话中测试改进
- 观察行为变化
迭代优化
- 持续调整配置
- 记录最佳实践

最佳实践

1. 编写高效的 CLAUDE.md

✅ 推荐：

## 测试要求
- 所有公开 API 必须有测试
- 使用 Vitest 框架
- 覆盖率 > 80%

❌ 避免：

## 测试要求
请确保代码质量良好，测试覆盖充分。我们重视测试...
（冗长的说明）

原则：

简洁明了
可操作
具体量化

2. 渐进式上下文管理

# 开始新功能
claude

# 检查上下文
/context

# 如果接近上限（> 80%）
/clear
/catchup main

# 继续工作
继续开发用户认证功能

3. 合理使用子代理

✅ 推荐场景：

隔离的实验性功能
可以并行的独立任务
需要不同上下文的工作

❌ 避免过度使用：

简单的单文件修改
相互依赖的任务
需要频繁交互的工作

4. Hook 配置策略

优先级：

格式化工具（自动修复）
Linter 检查（提示）
测试运行（验证）
安全扫描（阻止）

示例完整配置：

# 1. 自动格式化
[[hooks]]
event = "PostToolUse"
tool_name = "edit_file"
file_paths = ["*.ts", "*.tsx"]
command = "prettier --write $CLAUDE_FILE_PATHS"

# 2. Linting
[[hooks]]
event = "PostToolUse"
tool_name = "write_file"
command = "eslint $CLAUDE_FILE_PATHS"

# 3. 测试
[[hooks]]
event = "PreCommit"
command = "npm run test"

# 4. 安全检查
[[hooks]]
event = "PreCommit"
command = "npm audit"

5. 项目初始化清单

在新项目中使用 Claude Code 前：

创建 CLAUDE.md 文件
配置 .claude/settings.toml
设置必要的 hooks
定义自定义命令（如果需要）
测试权限配置
添加 .claudeignore 排除不需要的文件

.claudeignore 示例：

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

常见问题

Q1: CLAUDE.md 应该包含什么内容？

A: CLAUDE.md 定义代理的行为规则、工具和约定，确保跨仓库的一致行为。

应该包含：

项目概述和技术栈
开发命令
编码规范和风格偏好
Git 工作流
文件结构说明
已知问题和限制

不应该包含：

完整的框架文档
详细的 API 参考
冗长的教程

Q2: 何时使用子代理？

A: 使用”主控-克隆”模式（Task(...)）提供更好的灵活性，避免过度专业化。

适用场景：

需要隔离的复杂任务
可以并行的独立工作
实验性功能开发

不推荐：

创建过多专业化的子代理
用于简单的单文件任务
紧密耦合的工作

Q3: 如何管理长会话？

A: 使用 /clear 然后 /catchup 重置会话，同时保持完整的 Git 上下文。

完整工作流：

# 1. 保存当前进度到文件
将重构计划保存到 docs/plan.md

# 2. 清空上下文
/clear

# 3. 重新加载变更
/catchup main

# 4. 从保存的计划继续
阅读 docs/plan.md 并继续执行

Q4: Hooks 如何工作？

A: Hooks 在代理提交和操作期间自动执行规则和检查。

事件类型：

PreToolUse - 工具使用前
PostToolUse - 工具使用后
PreCommit - Git 提交前
PostCommit - Git 提交后

最佳实践：

优先使用 PostToolUse
避免过度阻止性的 hooks
保持命令快速执行

Q5: 如何在 CI/CD 中使用 Claude Code？

A: GitHub Actions 集成使得在自动化流程中可以进行 CLAUDE.md 驱动的验证。

典型用例：

PR 自动审查
```
- run: claude -p "审查这个 PR"
```

代码标准执行

- run: claude -p "检查是否符合 CLAUDE.md 规范"

自动化重构

- run: claude -p "升级所有依赖并修复破坏性变更"

文档生成

- run: claude -p "为所有新增的 API 生成文档"

总结

Claude Code 是一个功能强大的 AI 编程助手，掌握以下关键点可以充分发挥其潜力：

CLAUDE.md 是基础 - 投入时间编写清晰、简洁的配置文件
主动管理上下文 - 定期检查并清理，避免 token 浪费
善用 Plan Mode - 复杂任务先规划后执行
合理使用 Skills 和 MCP - 知识传授用 Skills，数据访问用 MCP
配置适当的 Hooks - 自动化质量保证，但避免过度阻塞
持续优化 - 审查日志，更新配置，不断改进

通过掌握这些高级功能和最佳实践，你可以将 Claude Code 打造成真正适合你团队的 AI 编程伙伴。

相关阅读：