Claude Code终端AI编程完全教程

前言

在AI辅助编程领域，大多数开发者熟悉的是IDE内嵌的AI工具（如GitHub Copilot、Cursor）。然而，Anthropic推出的Claude Code开辟了一条完全不同的路径——在终端中进行AI编程。这种方式不仅保留了命令行的高效与灵活，还深度集成了代码生成、项目理解、Git操作等能力。本教程将全面讲解Claude Code的使用方法，帮助你掌握这一强大的终端AI编程工具。

一、Claude Code概述

1.1 什么是Claude Code？

Claude Code是Anthropic推出的命令行AI编程工具，它将Claude大模型的能力直接带入终端环境。与传统AI编程助手不同，Claude Code：

• 运行在终端中：不需要IDE，直接在命令行交互
• 深度理解项目：能够读取、分析整个项目结构
• 执行实际操作：不只是生成代码，还能执行命令、操作文件
• 支持多种模式：交互模式、Headless模式、管道模式

1.2 与其他AI编程工具对比

comparison = {
    "Claude Code": {
        "类型": "终端CLI工具",
        "优势": "项目级理解、可执行命令、无需IDE",
        "适合": "终端用户、大型项目、CI/CD集成"
    },
    "Cursor": {
        "类型": "AI-native IDE",
        "优势": "可视化编辑、内嵌AI对话",
        "适合": "偏好GUI的开发者"
    },
    "Windsurf": {
        "类型": "AI IDE",
        "优势": "代码流体验、多文件协作",
        "适合": "全栈开发"
    },
    "GitHub Copilot": {
        "类型": "IDE插件",
        "优势": "即时补全、多IDE支持",
        "适合": "日常编码辅助"
    }
}

1.3 核心能力一览

二、安装与配置

2.1 系统要求

• 操作系统：macOS、Linux、Windows (WSL)
• Node.js：v18+ (推荐v20+)
• 网络：需要访问Anthropic API

2.2 安装方法

# 方式一：npm全局安装（推荐）
npm install -g @anthropic-ai/claude-code

# 方式二：使用npx直接运行（无需安装）
npx @anthropic-ai/claude-code

# 方式三：Homebrew (macOS)
brew install claude-code

2.3 配置API密钥

# 方式一：环境变量
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# 方式二：使用claude命令配置
claude config set apiKey sk-ant-your-key-here

# 方式三：.env文件（项目级）
echo "ANTHROPIC_API_KEY=sk-ant-your-key-here" > .env

2.4 验证安装

# 检查版本
claude --version

# 查看帮助
claude --help

# 启动交互模式
claude

2.5 基本配置

# 查看当前配置
claude config list

# 设置默认模型
claude config set model claude-sonnet-4-20250514

# 设置输出风格
claude config set outputStyle detailed

# 设置主题
claude config set theme dark

三、交互模式详解

3.1 启动交互式会话

# 在当前目录启动
cd /path/to/your/project
claude

# 进入交互式终端
# 你会看到一个提示符，可以直接输入自然语言指令

3.2 基本对话操作

# 直接输入指令
> 帮我看看这个项目的结构

# 多行输入（Shift+Enter换行）
> 帮我写一个Python函数，
  功能是解析CSV文件并返回统计数据

# 引用文件
> 请分析 src/main.py 的代码质量

# 使用 @ 引用文件路径
> 请重构 @src/utils/helper.py 中的重复代码

3.3 特殊命令

# 内斜杠命令
/help          # 查看帮助
/clear         # 清除对话历史
/compact       # 压缩上下文（减少token使用）
/config        # 打开配置
/cost          # 查看当前会话成本
/doctor        # 诊断问题
/init          # 初始化项目配置
/memory        # 编辑记忆文件
/model         # 切换模型
/review        # 代码审查
/terminal-setup # 终端设置
/vim           # 切换vim模式

3.4 上下文管理

# Claude Code会自动读取项目文件，但你也可以手动控制

# 添加文件到上下文
> 请读取 src/config.py 和 src/database.py

# 忽略特定文件（通过.claudeignore）
echo "*.log" > .claudeignore
echo "node_modules/" >> .claudeignore
echo ".env" >> .claudeignore

# 清除并重新开始
/clear

四、代码生成与重构

4.1 代码生成

# 生成单个函数
> 写一个Python函数，实现LRU缓存，支持过期时间

# 生成完整模块
> 创建一个用户认证模块，包含JWT token生成、
  验证、刷新功能，使用FastAPI

# 生成类
> 写一个数据库连接池管理类，支持MySQL和PostgreSQL

Claude Code会直接创建文件：

# 它可能会直接创建 src/auth/jwt_handler.py
"""
JWT认证模块
"""

import jwt
import datetime
from typing import Optional, Dict

class JWTHandler:
    """JWT Token处理器"""
    
    def __init__(self, secret_key: str, algorithm: str = "HS256"):
        self.secret_key = secret_key
        self.algorithm = algorithm
    
    def generate_token(self, user_id: str, expires_hours: int = 24) -> str:
        """生成JWT Token"""
        payload = {
            "user_id": user_id,
            "exp": datetime.datetime.utcnow() + datetime.timedelta(hours=expires_hours),
            "iat": datetime.datetime.utcnow(),
        }
        return jwt.encode(payload, self.secret_key, algorithm=self.algorithm)
    
    def verify_token(self, token: str) -> Optional[Dict]:
        """验证JWT Token"""
        try:
            payload = jwt.decode(token, self.secret_key, algorithms=[self.algorithm])
            return payload
        except jwt.ExpiredSignatureError:
            return None
        except jwt.InvalidTokenError:
            return None

4.2 代码重构

# 分析并重构
> 分析 src/services/order_service.py，找出重复代码并重构

# 提取公共方法
> 把 src/utils/ 下各文件中重复的验证逻辑提取到公共模块

# 设计模式应用
> 将 src/payment/ 下的支付处理代码重构为策略模式

# 性能优化
> 优化 src/data_processor.py 中的数据处理逻辑，提高性能

Claude Code会：

1. 读取相关文件
2. 分析代码结构
3. 提出重构方案
4. 执行重构操作
5. 更新相关导入

4.3 代码审查

# 审查单个文件
> 审查 src/api/users.py 的代码质量

# 审查最近的改动
> 审查我最近的git改动，找出潜在问题

# 安全审查
> 对 src/ 目录进行安全审查，检查SQL注入、XSS等风险

五、多文件项目操作

5.1 项目级理解

# Claude Code能理解整个项目结构
> 解释这个项目的架构和主要模块

# 查找特定功能
> 找到处理用户登录的所有相关代码

# 依赖分析
> 分析 src/core/ 模块的依赖关系

5.2 跨文件编辑

# 添加新功能（涉及多文件）
> 给项目添加一个文件上传功能：
  1. 在 src/api/ 添加上传接口
  2. 在 src/services/ 添加文件处理服务
  3. 在 src/models/ 添加文件模型
  4. 更新配置文件

# 修改接口（影响多处）
> 将 User.get_name() 重命名为 User.get_display_name()，
  更新所有调用处

5.3 使用CLAUDE.md项目规则

在项目根目录创建CLAUDE.md文件，定义项目特定规则：

# CLAUDE.md - 项目规则

## 代码风格
- 使用TypeScript strict模式
- 函数使用camelCase，类使用PascalCase
- 每个函数必须有JSDoc注释

## 项目结构
- src/api/ - API路由
- src/services/ - 业务逻辑
- src/models/ - 数据模型
- src/utils/ - 工具函数

## 测试要求
- 每个新功能必须有对应测试
- 测试覆盖率不低于80%
- 使用Jest作为测试框架

## Git规范
- 提交信息格式：type(scope): description
- type: feat, fix, docs, style, refactor, test, chore

## 禁止事项
- 不要使用any类型
- 不要在生产代码中使用console.log
- 不要直接操作数据库，必须通过Repository层

六、Git工作流集成

6.1 Git操作

# 查看当前状态
> 查看当前git状态，哪些文件有改动

# 创建提交
> 帮我提交当前改动，写一个合适的commit message

# 创建分支
> 创建一个feature/user-profile分支并切换过去

# 查看差异
> 显示src/api/目录下所有改动的diff

6.2 Pull Request操作

# 创建PR
> 创建一个Pull Request，标题为"添加用户头像上传功能"，
  描述包含改动说明和测试情况

# 审查PR
> 审查PR #42 的代码改动

# 合并建议
> 当前分支与main有什么冲突？如何解决？

6.3 Git工作流最佳实践

# 功能开发流程
> 帮我完成以下git工作流：
1. 从main创建feature/new-api分支
2. 实现新的用户API接口
3. 编写测试
4. 提交代码
5. 创建PR

# 代码审查流程
> 审查当前分支相对于main的所有改动，
  检查代码质量、安全问题和测试覆盖

七、MCP工具扩展

7.1 什么是MCP？

MCP（Model Context Protocol）是Claude Code的扩展协议，允许你为Claude Code添加自定义工具。

7.2 配置MCP服务器

// .claude/mcp.json
{
  "servers": {
    "database": {
      "command": "node",
      "args": ["mcp-servers/database-server.js"],
      "env": {
        "DB_URL": "postgresql://localhost:5432/mydb"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-filesystem", "/path/to/allowed/dir"]
    }
  }
}

7.3 常用MCP工具

# 文件系统MCP
npx @anthropic-ai/mcp-filesystem /path/to/project

# 数据库MCP（查看和查询数据库）
# 配置后可以直接用自然语言查询数据库
> 查询users表中最近7天注册的用户数量

# GitHub MCP
# 配置后可以直接操作GitHub
> 查看仓库的open issues

7.4 自定义MCP工具

// mcp-servers/custom-tool.js
const { Server } = require("@anthropic-ai/mcp");

const server = new Server({
  name: "custom-tools",
  version: "1.0.0",
});

// 添加自定义工具
server.tool(
  "deploy",
  "部署应用到指定环境",
  {
    environment: { type: "string", enum: ["dev", "staging", "prod"] },
    version: { type: "string" },
  },
  async ({ environment, version }) => {
    // 部署逻辑
    return { content: [{ type: "text", text: `已部署 ${version} 到 ${environment}` }] };
  }
);

server.start();

八、Headless模式

8.1 什么是Headless模式？

Headless模式允许你以非交互方式运行Claude Code，适合自动化脚本和CI/CD集成。

8.2 基本用法

# 单次执行模式
claude -p "解释这段代码的作用" < src/main.py

# 管道输入
cat error.log | claude -p "分析这个错误日志，找出根本原因"

# 输出为JSON格式
claude -p "列出src/目录下所有Python文件" --output-format json

# 限制输出轮次
claude -p "重构这个文件" --max-turns 5 < src/old_code.py

8.3 批量处理脚本

#!/bin/bash
# batch_review.sh - 批量代码审查脚本

# 审查所有Python文件
for file in src/**/*.py; do
    echo "审查: $file"
    claude -p "审查这个文件的代码质量，只输出问题和建议" < "$file" > "reviews/$(basename $file).review.md"
done

echo "审查完成！结果保存在 reviews/ 目录"

8.4 自动化测试

#!/bin/bash
# auto_test.sh - 自动生成测试

# 获取源文件列表
files=$(find src/ -name "*.py" -not -name "test_*")

for file in $files; do
    test_file="tests/test_$(basename $file)"
    
    if [ ! -f "$test_file" ]; then
        echo "为 $file 生成测试..."
        claude -p "为这个Python文件生成完整的pytest测试用例，保存到 $test_file" < "$file"
    fi
done

九、CLAUDE.md规则文件详解

9.1 项目级CLAUDE.md

在项目根目录创建，定义项目特定的规则和上下文：

# CLAUDE.md

## 项目概述
这是一个基于FastAPI的电商平台后端服务。

## 技术栈
- Python 3.11+
- FastAPI 0.100+
- SQLAlchemy 2.0+
- PostgreSQL 15+
- Redis 7+
- Docker

## 代码规范
- 遵循PEP 8
- 使用type hints
- 文档字符串使用Google风格
- 每个模块必须有模块级文档字符串

## 目录结构

src/ ├── api/ # API路由和端点 ├── models/ # SQLAlchemy模型 ├── schemas/ # Pydantic schema ├── services/ # 业务逻辑层 ├── repositories/ # 数据访问层 ├── utils/ # 工具函数 └── config.py # 配置管理

## 命名约定
- 文件名：snake_case
- 类名：PascalCase
- 函数名：snake_case
- 常量：UPPER_SNAKE_CASE
- 私有方法：_prefix_underscore

## 测试要求
- 使用pytest
- 测试文件命名：test_<module>.py
- 每个service方法必须有单元测试
- API端点必须有集成测试

## 数据库规范
- 所有查询必须通过Repository层
- 禁止在service层直接写SQL
- 迁移使用Alembic

## API规范
- RESTful风格
- 统一响应格式：{"code": 0, "data": {}, "message": ""}
- 错误码定义在src/constants.py

9.2 全局CLAUDE.md

在用户主目录创建，适用于所有项目：

# ~/.claude/CLAUDE.md

## 通用规则
- 代码优先，少说多做
- 修改前先理解上下文
- 不确定时先确认再执行
- 保持代码简洁，避免过度工程

## 输出偏好
- 代码注释使用中文
- 错误信息要具体且有帮助
- 优先使用标准库而非第三方库

## Git偏好
- 提交信息使用英文
- 一个提交做一个功能点
- PR描述要详细

9.3 CLAUDE.md最佳实践

# CLAUDE.md 最佳实践

## 该写什么
✅ 项目特有的规范和约定
✅ 重要的架构决策
✅ 常见坑和解决方案
✅ 代码风格偏好
✅ 测试和部署要求

## 不该写什么
❌ 通用编程知识
❌ 过于详细的实现细节
❌ 频繁变化的信息
❌ 敏感信息（密码、密钥等）

十、高级技巧

10.1 上下文优化

# 当上下文太长时使用compact
/compact

# 手动添加重要上下文
> 请先阅读以下文件了解项目背景：
  README.md, ARCHITECTURE.md, src/config.py

# 使用clear重新开始
/clear

10.2 模型选择

# 切换模型
/model claude-sonnet-4-20250514      # 平衡性能和速度
/model claude-opus-4-20250514        # 最强能力
/model claude-haiku-4-20250514       # 最快速度

# 根据任务选择
# - 代码生成/重构：opus或sonnet
# - 简单问答：haiku
# - 复杂分析：opus

10.3 快捷键

# 常用快捷键（交互模式）
Ctrl+C        # 取消当前操作
Ctrl+D        # 退出
Ctrl+L        # 清屏
Up/Down       # 浏览历史命令
Tab           # 自动补全

10.4 自定义快捷命令

# 在项目中创建快捷脚本
cat > review.sh << 'EOF'
#!/bin/bash
# 快速代码审查
git diff --staged | claude -p "审查这些改动，指出问题和改进建议"
EOF

chmod +x review.sh

十一、实战案例：大型项目重构

11.1 场景描述

假设我们有一个老旧的Python项目，需要进行现代化重构。

11.2 重构流程

# 第一步：分析现状
> 分析这个项目的代码结构，识别主要问题：
  - 代码异味
  - 架构问题
  - 重复代码
  - 缺失的测试

# 第二步：制定计划
> 根据分析结果，制定重构计划，按优先级排序

# 第三步：逐步执行
# 3.1 重构数据层
> 将 src/database/ 中的直接SQL调用重构为Repository模式

# 3.2 重构业务层
> 将 src/services/ 中的大型函数拆分为更小的职责单一的函数

# 3.3 添加类型注解
> 为 src/ 下的所有Python文件添加完整的type hints

# 3.4 生成测试
> 为核心模块生成单元测试

# 第四步：验证
> 运行测试并确保重构后功能不变

11.3 完整重构示例

# 重构前后对比
> 对比 src/services/user_service.py 重构前后的代码，
  解释每个改动的原因

# 生成重构报告
> 生成本次重构的完整报告，包含：
  - 改动文件列表
  - 主要改动说明
  - 新增测试覆盖
  - 性能影响评估

十二、CI/CD集成

12.1 GitHub Actions集成

# .github/workflows/ai-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      
      - name: Run AI Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # 获取PR的diff
          git diff origin/main...HEAD > /tmp/pr_diff.txt
          
          # 使用Claude Code审查
          claude -p "审查这个PR的代码改动，检查：
          1. 代码质量问题
          2. 潜在的bug
          3. 安全风险
          4. 性能问题
          输出格式化的审查报告。" < /tmp/pr_diff.txt > review_report.md
      
      - name: Comment PR
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review_report.md', 'utf8');
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `## 🤖 AI Code Review\n\n${review}`
            });

12.2 自动生成文档

# .github/workflows/auto-docs.yml
name: Auto Generate Docs

on:
  push:
    branches: [main]
    paths:
      - 'src/**'

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Generate API Docs
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npm install -g @anthropic-ai/claude-code
          
          # 为每个API模块生成文档
          for file in src/api/*.py; do
            module_name=$(basename "$file" .py)
            claude -p "为这个API模块生成详细的API文档，包含端点说明、参数、返回值和示例" < "$file" > "docs/api/${module_name}.md"
          done
      
      - name: Commit Docs
        run: |
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git add docs/
          git commit -m "docs: auto-generate API documentation" || true
          git push

12.3 自动测试生成

# .github/workflows/auto-tests.yml
name: Auto Generate Tests

on:
  workflow_dispatch:
  schedule:
    - cron: '0 0 * * 0'  # 每周日执行

jobs:
  generate-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Find Untested Files
        run: |
          # 找出没有对应测试文件的源文件
          for file in src/**/*.py; do
            if [[ ! "$file" == *test_* ]] && [[ ! "$file" == *__* ]]; then
              test_file="tests/test_$(basename $file)"
              if [ ! -f "$test_file" ]; then
                echo "$file" >> untested_files.txt
              fi
            fi
          done
      
      - name: Generate Tests
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npm install -g @anthropic-ai/claude-code
          
          while IFS= read -r file; do
            echo "Generating tests for: $file"
            claude -p "为这个Python文件生成完整的pytest测试用例，覆盖所有公开方法，包含正常和边界情况" < "$file" > "tests/test_$(basename $file)"
          done < untested_files.txt

十三、与Cursor/Windsurf对比详解

13.1 工作流对比

# ===== Claude Code工作流 =====
# 1. 打开终端
# 2. cd到项目目录
# 3. 启动claude
# 4. 输入自然语言指令
# 5. Claude执行操作

# ===== Cursor工作流 =====
# 1. 打开Cursor IDE
# 2. 打开项目
# 3. 使用Cmd+K内联编辑或Chat面板
# 4. 接受/拒绝修改建议

# ===== Windsurf工作流 =====
# 1. 打开Windsurf IDE
# 2. 使用Cascade AI助手
# 3. AI理解上下文并建议修改
# 4. 一键应用修改

13.2 能力对比表

13.3 选择建议

def recommend_tool(user_profile):
    """根据用户画像推荐工具"""
    
    if user_profile["prefers_terminal"]:
        return "Claude Code"
    
    if user_profile["needs_visual_editing"]:
        if user_profile["budget"] >= 20:
            return "Cursor"
        else:
            return "Windsurf"
    
    if user_profile["needs_cicd_integration"]:
        return "Claude Code"
    
    if user_profile["team_size"] > 10:
        return "Claude Code + Cursor"  # 组合使用
    
    return "Cursor"  # 默认推荐

十四、测试驱动开发（TDD）

14.1 TDD工作流

# 步骤1：先写测试
> 为用户注册功能编写测试用例，包含：
  - 正常注册
  - 邮箱已存在
  - 密码不符合要求
  - 必填字段缺失

# 步骤2：运行测试（此时会失败）
> 运行测试并显示失败的测试用例

# 步骤3：实现功能
> 根据测试用例实现用户注册功能

# 步骤4：运行测试（此时应通过）
> 运行测试并确保所有用例通过

# 步骤5：重构
> 在保持测试通过的前提下，优化注册代码

14.2 测试生成最佳实践

# 为现有代码生成测试
> 为 src/services/payment_service.py 生成测试，
  要求：
  - 使用pytest
  - 使用mock隔离外部依赖
  - 覆盖所有公开方法
  - 包含正常和异常情况
  - 测试文件保存到 tests/test_payment_service.py

# 增强现有测试
> 分析 tests/ 目录，找出测试覆盖不足的地方并补充

十五、调试与问题排查

15.1 错误分析

# 分析错误堆栈
> 我运行 python main.py 时报了这个错误，请帮我分析：
  [粘贴错误信息]

# 日志分析
> 分析 app.log 中的错误模式，找出最常见的问题

# 性能问题
> 这个函数运行很慢，帮我分析性能瓶颈：
  [粘贴代码]

15.2 常见问题解决

# Claude Code本身的问题
/doctor  # 运行诊断

# API连接问题
> 我遇到了API连接错误，帮我诊断网络问题

# 权限问题
> 文件操作时提示权限不足，如何解决？

十六、安全最佳实践

16.1 敏感信息保护

# .claudeignore - 排除敏感文件
.env
.env.*
*.key
*.pem
credentials/
secrets/

16.2 代码安全审查

# 安全审查
> 对项目进行安全审查，重点检查：
  - SQL注入风险
  - XSS漏洞
  - 敏感信息硬编码
  - 不安全的依赖
  - 认证和授权问题

十七、总结与最佳实践

17.1 使用技巧总结

## Claude Code使用技巧

### 效率提升
1. 善用CLAUDE.md定义项目规则
2. 使用.claudeignore排除无关文件
3. 复杂任务分步骤执行
4. 使用compact管理上下文

### 代码质量
1. 先理解再修改
2. 让Claude解释它的修改
3. 保持测试覆盖
4. 定期进行代码审查

### 团队协作
1. 团队共享CLAUDE.md
2. 统一代码风格配置
3. 使用CI/CD集成AI审查
4. 建立代码审查流程

17.2 推荐学习路径

入门：安装配置 → 基本对话 → 代码生成
进阶：多文件操作 → Git集成 → CLAUDE.md配置
高级：Headless模式 → CI/CD集成 → MCP扩展
专家：自定义MCP → 团队工作流 → 自动化流水线

17.3 官方资源

• 官方文档：https://docs.anthropic.com/claude-code
• GitHub：https://github.com/anthropics/claude-code
• MCP协议：https://modelcontextprotocol.io
• 社区示例：https://github.com/anthropics/claude-code-examples

本教程持续更新中。Claude Code作为终端AI编程的先驱工具，正在改变开发者的工作方式。掌握它，你将拥有一种全新的编程体验。