Claude Code 完全指南：终端里的 AI 编程革命

我用 Claude Code 写代码已经快半年了。

这半年里，我的工作方式发生了一个根本性的变化：从"自己写代码"变成了"指挥 AI 写代码"。听起来有点夸张，但事实就是这样。我现在每天的工作流程是打开终端，启动 Claude Code，用自然语言描述我想要什么，然后看着它在我的项目里读文件、改代码、跑测试、修 bug。

Claude Code 不是一个聊天机器人。它是一个住在你终端里的程序员。

这篇文章是我能写的最完整的 Claude Code 指南。从安装到高级玩法，从基础功能到 MCP 集成，从独立使用到团队协作。不管你是刚听说这个工具，还是已经用了一段时间想解锁更多能力，这篇都适合你。

一、Claude Code 到底是什么

Claude Code 是 Anthropic 官方出品的命令行 AI 编程工具。

注意两个关键词：官方和命令行。

“官方"意味着它直接使用 Claude 最新最强的模型（目前是 Claude Opus 4.6），不是什么第三方套壳。“命令行"意味着它运行在你的终端里，不是浏览器，不是 IDE 插件。

这两个特点决定了 Claude Code 和其他 AI 编程工具的根本区别：

它能直接操作你的文件系统。

不是"生成代码让你复制粘贴”。是它自己读你的文件，自己改你的代码，自己运行你的命令，自己看报错信息，自己修 bug。你在旁边看着，觉得 OK 就点确认，觉得不对就告诉它哪里有问题。

打个比方：ChatGPT 和 Claude.ai 网页版是"远程咨询医生”，你描述症状，他给你方案，你自己去执行。Claude Code 是"上门医生"，他直接到你家里，看你的体检报告，开药，盯着你吃。

这个区别是质变级别的。

二、安装和配置

2.1 安装

前提条件：你的电脑上需要有 Node.js 18+。

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

一行命令，全局安装。完成后，在终端任意位置输入 claude 就能启动。

如果你在中国大陆，npm 可能比较慢，可以用 npmmirror：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

2.2 认证

第一次启动时，Claude Code 会引导你完成认证。有两种方式：

方式一：Anthropic API Key（按量付费）

去 console.anthropic.com 创建一个 API Key，然后设置环境变量：

export ANTHROPIC_API_KEY="sk-ant-xxxxx"

建议把这行加到你的 ~/.zshrc 或 ~/.bashrc 里，这样每次打开终端都自动生效。

方式二：Claude Pro/Max 订阅（包月制）

如果你有 Claude Pro（$20/月）或 Max（$100/月 或 $200/月）订阅，可以直接用 OAuth 认证。启动 Claude Code 后它会打开浏览器让你登录，登录后自动完成认证。

怎么选？ 如果你是重度用户（每天用好几个小时），Max 订阅更划算。如果你只是偶尔用用，API Key 按量付费更灵活。我个人用的是 Max $200/月的 plan，因为我几乎每天都在用。

2.3 基本设置

Claude Code 的配置文件在 ~/.claude/ 目录下。几个值得调整的设置：

设置默认模型：

claude config set model claude-opus-4-6

设置终端主题（避免配色冲突）：

claude config set theme dark

查看当前配置：

claude config list

三、核心功能：Claude Code 能做什么

3.1 读文件

Claude Code 可以读取你项目中的任何文件。它不需要你手动复制粘贴代码到聊天窗口。

你：看看 src/app/page.tsx 的代码，告诉我首页的渲染逻辑

它会直接读取文件内容，然后分析给你听。你也可以让它读整个目录：

你：看看 src/components/ 下面所有组件的结构，给我一个总结

3.2 写文件 / 改文件

这是 Claude Code 最核心的能力。你告诉它你想要什么，它直接改你的文件。

你：给 UserProfile 组件添加一个头像上传功能。使用现有的 Upload 组件，上传后保存到 Supabase Storage。

Claude Code 会：

1. 先读现有的 UserProfile 组件代码
2. 读 Upload 组件的接口定义
3. 读 Supabase 的配置
4. 生成新代码
5. 直接写入文件

每次写入前，它会展示 diff（修改对比），让你确认。你可以选择接受、拒绝、或者让它修改。

3.3 执行命令

Claude Code 可以在你的终端里运行任何命令。

你：安装 shadcn/ui 的 Button 和 Dialog 组件

它会运行：

npx shadcn-ui@latest add button dialog

你：项目能跑起来吗？启动开发服务器看看有没有报错

它会运行 npm run dev，查看输出，如果有报错就分析原因并修复。

3.4 搜索代码

不知道某个函数在哪定义的？某个变量在哪里被引用的？

你：找一下 handleAuth 函数在哪些文件里被调用了

Claude Code 会用内置的搜索工具扫描整个项目，给你一个完整的引用列表。

3.5 理解项目

这可能是对新人最有用的功能。

你：我刚 clone 了这个项目，帮我理解一下整体架构。重点看数据流和路由结构。

Claude Code 会扫描整个项目的目录结构、配置文件、入口文件、路由定义，然后给你一个项目架构概览。

我每次接手一个新项目或者新的开源代码时，第一件事就是让 Claude Code 帮我"读"一遍。比我自己翻文件快 10 倍。

四、实战场景

理论说完了，来点实际的。

场景 1：从零开发一个新功能

我需要给博客添加一个评论功能。

你：帮我实现博客文章的评论功能。

技术要求：
- 使用现有的 Supabase 数据库
- 评论需要登录才能发
- 支持 Markdown 格式
- 支持嵌套回复（最多 2 层）
- 新评论实时显示（不需要刷新页面）

先从数据库 schema 开始，然后是 API，最后是前端组件。

Claude Code 会按顺序执行：

1. 创建 Supabase migration 文件定义评论表
2. 运行 supabase db push 创建表
3. 写 API 路由处理评论的 CRUD
4. 写前端组件（评论列表、评论输入框、回复按钮）
5. 连接 Supabase 实时订阅，实现新评论即时显示
6. 运行开发服务器，检查是否正常工作

整个过程我主要是在看它的 diff 输出，确认逻辑是否符合预期。偶尔提一些调整意见，比如"回复按钮的样式和现有按钮不一致，参考 Button.tsx 的样式"。

场景 2：修复一个诡异的 Bug

“用户说在 Safari 上点击提交按钮没反应，但 Chrome 正常。”

你：有个 bug：Safari 上点击提交按钮没反应，Chrome 正常。请排查 components/SubmitButton.tsx 和相关的表单逻辑。

Claude Code 的排查过程：

1. 读取 SubmitButton.tsx
2. 读取关联的表单组件
3. 分析事件处理逻辑
4. 发现问题：“这里用了 event.target.closest() 方法，Safari 对这个方法的兼容性有问题”
5. 给出修复方案并直接改代码
6. 建议添加相关的兼容性测试

比我自己 debug 快得多。 特别是这种跨浏览器兼容性问题，Claude Code 的知识库覆盖面比人脑宽太多了。

场景 3：代码重构

项目里有一堆重复的数据获取逻辑，散落在十几个组件里。

你：扫描 src/components/ 和 src/app/ 下所有文件。找出重复的数据获取模式（fetch + useState + useEffect），提取成自定义 Hook。命名规范参考现有的 hooks 目录。

Claude Code 会：

1. 扫描所有文件，识别出重复模式
2. 归类：哪些是获取用户数据的、哪些是获取文章数据的、哪些是获取配置的
3. 为每个类别创建自定义 Hook
4. 逐个替换原始组件中的重复代码
5. 运行测试确保重构没有破坏功能

这种"批量重构"是 Claude Code 最擅长的事情之一。它能在几分钟内完成你可能需要一天才能做完的重构工作。

场景 4：理解别人的代码

公司新来的项目，文档几乎没有。

你：这个项目是干什么的？帮我梳理核心业务流程。从用户注册开始，到完成一笔交易结束。标出关键的文件和函数。

Claude Code 会给你一张清晰的"地图"：从入口文件开始，沿着数据流和控制流，一路追踪到业务逻辑的核心。

五、MCP 集成：让 Claude Code 连接一切

MCP（Model Context Protocol） 是 Anthropic 设计的一个协议，让 Claude Code 能够连接外部工具和服务。

简单理解：MCP 就是 Claude Code 的"USB 接口"。你可以通过 MCP 给它接上各种外部能力。

5.1 MCP 能连什么

5.2 怎么配置

MCP 的配置文件在 ~/.claude/settings.json 中：

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_xxx\"}"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    }
  }
}

每个 MCP 服务器就是一个独立的进程。Claude Code 启动时会自动启动所有配置的 MCP 服务器。

5.3 实战：Notion + Claude Code

这是我最常用的 MCP 组合。我的工作流程是：

1. 在 Notion 里写任务需求
2. 让 Claude Code 读取 Notion 任务
3. Claude Code 自动实现代码
4. 完成后让 Claude Code 把进展更新到 Notion

你：读取 Notion 里"本周待办"数据库，找到标记为"进行中"的任务，帮我逐个实现。每完成一个就在 Notion 里标记为"已完成"。

这种级别的自动化，在没有 MCP 之前是做不到的。

5.4 实战：GitHub + Claude Code

你：看看 GitHub 上 #142 这个 Issue。理解需求后，创建一个新分支，实现它，写测试，然后提交 PR。PR 描述里要说清楚改了什么、为什么这么改。

Claude Code 会完成从"读需求"到"提交 PR"的全流程。你只需要最后 review 一下 PR 就行。

六、高级技巧

6.1 CLAUDE.md：给 AI 写一份项目说明书

这是 Claude Code 最重要的进阶功能。

在项目根目录创建一个 CLAUDE.md 文件，Claude Code 每次启动时都会自动读取它。你可以把它理解为给 AI 写的项目文档。

一个好的 CLAUDE.md 应该包含：

# 项目概述
这是一个 Next.js 电商平台。用户可以浏览商品、加入购物车、完成支付。

# 技术栈
- Next.js 15 (App Router)
- TypeScript (strict mode)
- TailwindCSS
- Supabase (数据库 + 认证)
- Stripe (支付)

# 目录结构
src/app/          → 页面路由
src/components/   → 可复用组件
src/lib/          → 工具函数和配置
src/hooks/        → 自定义 Hooks
supabase/         → 数据库 migration

# 代码规范
- 组件文件用 PascalCase
- 工具函数用 camelCase
- 不用 any 类型
- 不用 console.log（用 logger）
- 测试文件和源文件放同目录

# 常用命令
- dev: npm run dev
- test: npm test
- build: npm run build
- db push: supabase db push

# 部署
通过 Vercel 自动部署。main 分支 push 后自动触发。

CLAUDE.md 的质量直接决定了 Claude Code 输出的质量。 我见过的最高效的 Claude Code 用户，都有一份精心维护的 CLAUDE.md。

你还可以创建分层的规则文件：

• ~/.claude/CLAUDE.md — 全局规则（对所有项目生效）
• 项目根目录/CLAUDE.md — 项目规则
• 子目录/CLAUDE.md — 子模块规则

Claude Code 会自动合并所有层级的规则。

6.2 Hooks：自动化工作流

Hooks 让你在 Claude Code 的特定事件点自动执行脚本。

在项目根目录创建 .claude/hooks.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "event": "Edit",
        "command": "npx prettier --write $FILE_PATH",
        "description": "Auto-format after edit"
      }
    ],
    "PreToolUse": [
      {
        "event": "Bash",
        "command": "echo '⚠️ AI is about to run a command'",
        "description": "Warn before bash execution"
      }
    ]
  }
}

常用的 Hook 场景：

6.3 自定义技能

你可以在 ~/.claude/skills/ 目录下创建 Markdown 文件，每个文件就是一个"技能"。当 Claude Code 遇到相关场景时，会自动加载对应的技能。

比如我有一个 cloudflare-deploy.md 技能：

# Cloudflare 部署技能

## 触发条件
用户提到 Cloudflare Workers、Pages、KV 部署

## 部署步骤
1. 确认 wrangler.toml 配置正确
2. 使用环境变量认证（不用 wrangler login）
3. 运行 wrangler deploy
4. 部署后验证 URL 可访问

技能文件让 Claude Code 拥有了你的专属知识。它知道你的部署方式、你的代码规范、你的项目架构。

6.4 团队协作模式

Claude Code 支持 Multi-Agent 模式。你可以创建一个"团队"，让多个 Claude Code 实例同时工作在同一个项目上。

你：创建一个团队。一个 Agent 负责写前端组件，另一个负责写 API 接口，第三个负责写测试。三个 Agent 并行工作。

每个 Agent 在自己的 worktree 上工作，互不干扰。完成后合并。

这对大型功能开发特别有用。以前一个功能需要前端、后端、测试三个人分别开发，现在三个 Agent 同时开干，你作为"项目经理"协调就行。

七、和 Cursor / Windsurf 的对比

这是大家最关心的问题：Claude Code、Cursor、Windsurf，选哪个？

先说结论：它们不是竞争关系，而是互补关系。 但如果你只能选一个，选择取决于你的工作方式。

对比表

什么时候用 Claude Code

• 你更喜欢终端。你觉得在命令行里工作更快、更灵活、更有控制感。
• 你需要执行复杂的自动化。MCP + Hooks + 自定义技能 + 团队模式，Claude Code 的生态比其他工具丰富得多。
• 你做的是整个功能的开发，不只是"写某一行代码"。Claude Code 更适合处理"从需求到实现"的完整流程。
• 你想要 Claude Opus 的原生体验。Claude Code 使用 Anthropic 最新模型，没有中间层，响应速度和质量都是最优的。

什么时候用 Cursor / Windsurf

• 你写代码时需要实时补全。在敲代码的过程中，AI 自动预测你下一行要写什么。这是 Claude Code 目前做不到的。
• 你习惯了 VS Code 生态。所有 VS Code 扩展、快捷键、界面布局都保留。
• 你更喜欢"看到代码再改"。在编辑器里直接看到 AI 的修改建议，和在终端里看 diff 是不同的体验。

我的选择

我目前的工作流是 Claude Code 为主，VS Code 为辅。

大块的功能开发、项目理解、重构、bug 排查，我用 Claude Code。它的 Agent 能力和自动化能力是 Cursor 比不了的。

写代码的时候如果需要实时补全，我打开 VS Code + Copilot。

两者配合使用，覆盖了几乎所有场景。

八、适合谁用

说实话，Claude Code 不适合所有人。

非常适合的人

1. 有经验的开发者

你已经知道怎么写代码、怎么架构项目、怎么调试。你需要的是"加速器"，不是"老师"。Claude Code 在你的指导下工作得最好。

2. 全栈独立开发者

你一个人做前端、后端、数据库、部署。Claude Code 的全能性在这种场景下发挥到极致。它就像你的"虚拟合伙人"。

3. 喜欢终端的人

你日常工作已经在终端里了。git、npm、docker、ssh，都是老朋友。Claude Code 只是在你熟悉的环境里多了一个超级助手。

4. 需要处理多项目的人

你同时维护好几个项目。Claude Code 的 CLAUDE.md 和自定义技能让它能快速适应不同项目的规范，不需要你每次都重新解释。

不太适合的人

1. 编程初学者

如果你还在学基础语法，Claude Code 可能不是最好的学习工具。它会帮你写出能跑的代码，但你可能不理解为什么这样写。建议先打好基础，再用 Claude Code 提效。

2. 不喜欢命令行的人

如果你看到终端就头疼，Cursor 或 Windsurf 可能更适合你。Claude Code 的全部交互都在终端里完成，没有图形界面。

3. 对 AI 生成的代码不放心的人

Claude Code 写的代码需要你 review。如果你不具备判断代码质量的能力，或者你的项目对安全性要求极高不能容忍任何 AI 犯错的可能，那你需要更谨慎地使用。

九、入门行动清单

如果你决定试试 Claude Code，这是我建议的第一周行动计划：

Day 1：安装 + 体验

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

启动后，让它帮你理解一个你熟悉的项目。看看它的分析是否准确。

Day 2：创建 CLAUDE.md

为你最常用的项目写一份 CLAUDE.md。不需要很长，先写项目概述、技术栈、代码规范就够了。

Day 3：尝试修改代码

找一个简单的 bug 或小功能，让 Claude Code 来实现。观察它的工作流程：读文件 → 分析 → 修改 → 验证。

Day 4：配置 MCP

选一个你常用的外部服务（GitHub、Notion、数据库），配置 MCP 连接。

Day 5：尝试自动化

配置一个 Hook。比如代码修改后自动格式化、会话结束后自动 commit。

Day 6-7：真实项目

在一个真实的开发任务上使用 Claude Code。记录哪些地方用得顺、哪些地方需要你手动介入。

十、常见问题

Q：Claude Code 会删除我的文件吗？

不会无故删除。每次文件操作前它都会展示修改内容让你确认。但如果你明确告诉它"删除这个文件"，它会执行。建议重要项目始终保持 git 版本管理。

Q：用 Claude Code 会泄露我的代码吗？

Claude Code 将代码发送到 Anthropic 的 API 进行处理。Anthropic 的 API 服务承诺不会使用用户数据进行训练。如果你的公司对代码安全有严格要求，建议咨询法务。

Q：Claude Code 能用中文交互吗？

完全可以。Claude Opus 的中文能力非常强。你可以用中文描述需求，它也会用中文回复。代码注释可以中英文混用。

Q：一个月大概要花多少钱？

取决于使用频率。轻度使用（每天几十分钟）大约 $20-50/月的 API 费用。重度使用建议直接买 Claude Max 订阅。

Q：网络不好怎么办？

Claude Code 需要稳定的网络连接来访问 Anthropic API。如果你在中国大陆，可能需要网络代理。设置 HTTPS_PROXY 环境变量即可。

写在最后

Claude Code 改变了我对"写代码"这件事的理解。

以前，编程是"我敲键盘，电脑执行"。现在，编程是"我描述意图，AI 实现，我审核结果"。

这不是偷懒。这是工作方式的进化。就像从手写信件到发邮件不是偷懒一样。

如果你是一个开发者，我真心建议你试试 Claude Code。不一定要全面切换，先在一个小项目上体验一下就好。

你会发现，终端里多了一个比任何人类队友都耐心、都快速、都不知疲倦的伙伴。

而且它从来不会在你写代码的时候过来问"在吗"。

本文首发于 aieii.com，一个关注 AI 工具与趋势的中文内容平台。