Claude Code：命令行 AI 助手

Claude Code 简介

为什么 Claude Code 与众不同

Claude Code 是 Anthropic 于 2024 年发布的命令行 AI Agent，它的独特之处在于：不受 IDE 约束，可以处理整个代码库级别的任务；能够执行任意 shell 命令；具备文件系统的完整读写权限；可以运行测试、安装依赖、执行代码。

这让 Claude Code 特别适合"重型任务"：大规模重构、跨多个模块的功能实现、复杂的 Bug 调试（需要运行程序观察输出）、以及自动化脚本编写。

安装与初始配置

安装 Claude Code

# 需要 Node.js 18+
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

# 设置 Anthropic API Key
# 方式1：环境变量（推荐）
export ANTHROPIC_API_KEY="sk-ant-..."

# 方式2：添加到 ~/.bashrc 或 ~/.zshrc（永久生效）
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc

# 首次运行：Claude Code 会要求登录确认
claude

基本使用模式

# 交互式聊天模式（默认）
claude
# 然后输入任意问题或任务描述

# 单次任务模式（非交互式，适合脚本）
claude -p "解释这个 Python 文件的功能" src/main.py

# 从 stdin 读取（管道使用）
cat error.log | claude -p "分析这个错误日志，找出根本原因"

# 在项目目录中启动（Claude 会自动读取 CLAUDE.md）
cd /path/to/my-project
claude

CLAUDE.md：项目上下文文件

CLAUDE.md 的作用

当你在项目目录中启动 Claude Code 时，它会自动读取 CLAUDE.md 文件（如果存在），将其内容作为上下文注入到对话开始。这是让 Claude Code 快速理解项目结构的关键配置。

# 示例 CLAUDE.md（放在项目根目录）

# MyProject CLAUDE.md

## 项目概述
这是一个 SaaS 多租户平台，使用 Python 3.12 + FastAPI + PostgreSQL。

## 关键架构决策
- 多租户通过 `tenant_id` 列实现行级隔离（Row-Level Security）
- 认证使用 JWT，刷新令牌存储在 Redis
- 任务队列使用 Celery + RabbitMQ

## 常用命令
```bash
# 启动开发服务器
make dev

# 运行测试
make test

# 生成数据库迁移
alembic revision --autogenerate -m "描述"

# 应用迁移
alembic upgrade head
```

## 代码规范
- 所有 API 端点文件在 `src/api/v1/` 目录
- 服务层逻辑在 `src/services/` 目录
- 数据库模型在 `src/models/` 目录
- 每个模块有对应的测试文件（`tests/test_{module}.py`）

## 注意事项
- 不要修改 `alembic/versions/` 目录下已有的迁移文件
- 所有外部 API 调用必须有超时设置（最大 30 秒）
- 生产环境变量在 `.env.production`，不要提交到 git

CLAUDE.md 层级结构

Claude Code 支持多层级的 CLAUDE.md 文件：

• ~/.claude/CLAUDE.md：全局配置，对所有项目生效（个人偏好、工作习惯）
• {project}/CLAUDE.md：项目根配置，对整个项目生效
• {project}/src/CLAUDE.md：子目录配置，只对该目录生效

Hooks：自动化工作流

什么是 Hooks？

Hooks 是 Claude Code 在执行特定操作前后自动运行的脚本。你可以用 Hooks 来：格式化代码（每次修改文件后）、运行 lint 检查（提交前）、自动运行相关测试、记录 AI 操作日志。

// ~/.claude/settings.json 或项目目录 .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        // 每次 Claude 修改 Python 文件后，自动运行 Black 格式化
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ \"$CLAUDE_TOOL_FILE\" == *.py ]]; then black \"$CLAUDE_TOOL_FILE\"; fi"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        // 在执行危险命令前要求确认
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"将执行: $CLAUDE_TOOL_COMMAND\" | grep -qE 'rm|drop|delete' && echo 'BLOCK' || echo 'ALLOW'"
          }
        ]
      }
    ]
  }
}

MCP 服务器集成

什么是 MCP（Model Context Protocol）？

MCP 是 Anthropic 发布的开放协议，允许 Claude Code 连接外部工具和数据源。通过 MCP，Claude Code 可以直接访问数据库、调用外部 API、操作 Web 浏览器、读取私有文档库等。

// .claude/mcp.json（项目级 MCP 配置）
{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "postgresql://localhost/mydb"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/path/to/docs"]
    },
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

常用 MCP 服务器

计划模式（Plan Mode）

先规划，再执行

对于复杂任务，直接让 Claude Code 执行可能导致混乱。计划模式（通过 --plan 标志或在对话中要求）让 Claude 先输出执行计划，等你确认后再实施：

# 要求 Claude 先制定计划
claude -p "在实施之前，先给我列出你的执行计划：
将整个项目从 Python 3.10 迁移到 3.12，
更新所有使用了已废弃 API 的代码"

# Claude 的计划输出示例：
# 1. 扫描所有 .py 文件，找出使用 Python 3.10/3.11 废弃 API 的代码
#    - 检查 datetime.utcnow()（已废弃，应使用 datetime.now(timezone.utc)）
#    - 检查 asyncio.coroutine 装饰器
# 2. 更新 pyproject.toml 中的 python_requires
# 3. 逐文件修复废弃 API 使用
# 4. 运行测试验证
# 是否按此计划执行？

成本控制策略

Claude Code 的 Token 消耗

Claude Code 按 Anthropic API 的 token 计费，大型代码库任务可能消耗大量 token。以下策略可以显著降低成本：

# .claudeignore 示例
node_modules/
.git/
dist/
build/
__pycache__/
*.pyc
.venv/
*.lock
*.log
*.png
*.jpg
*.pdf

Claude Code 的工作原理

Claude Code 如何访问代码库

Claude Code 与 Cursor/Copilot 的根本不同在于：它是一个命令行 Agent，通过工具调用（Tool Use）直接操作文件系统，而不是通过 IDE 插件 API。理解这个区别很重要：

计划模式（Plan Mode）的价值

Claude Code 的计划模式（/plan）在执行前先生成详细计划并请求用户确认，这不只是"安全措施"，更有深层的工程价值：

不用计划模式（直接执行）：
  用户: "把所有 callback 风格的代码改成 async/await"
  Claude: [直接开始修改文件...可能改了50个文件]
  问题：你不知道它要改哪些文件，改完才能看结果

使用计划模式：
  用户: /plan 把所有 callback 风格的代码改成 async/await

  Claude 输出计划：
  我计划修改以下 12 个文件（跳过 vendor/ 和 test/ 目录）：
  1. src/api/user.js - callback 函数 3 处
  2. src/api/order.js - callback 函数 5 处
  3. src/utils/db.js  - callback 函数 2 处
  ...
  估计共 23 处修改，影响 12 个文件。
  是否继续？

  你: 好的，但跳过 src/api/payment.js（有特殊逻辑）
  Claude: 明白，排除 payment.js，共修改 11 个文件...

Hooks 的安全考量

Claude Code Hooks 允许在特定事件触发时自动执行 shell 命令。这非常强大，但也有安全风险需要了解：

Claude Code vs Cursor：如何选择

选择 Claude Code 的场景：
  ✓ 需要在 CI/CD 中自动运行的任务（无 GUI 环境）
  ✓ 整个代码库级别的批量修改（重命名、迁移、代码风格统一）
  ✓ 需要执行复杂 shell 命令链（build → test → deploy）
  ✓ 需要 MCP 集成外部系统（数据库、API、Slack）
  ✓ 不想为 IDE 订阅额外费用（已有 Anthropic API Key）

选择 Cursor 的场景：
  ✓ 日常编码，需要实时代码补全
  ✓ 单个文件或少量文件的修改
  ✓ 需要可视化的 diff 审查界面
  ✓ 不熟悉命令行操作
  ✓ 团队已统一使用 VS Code 生态

两者结合的最佳实践：
  • 日常编码 → Cursor（实时补全 + Composer）
  • 大型重构任务 → Claude Code（整库操作 + 自动测试）
  • 代码审查 → 两者均可（Claude Code 直接在 PR 中运行）