如果你只是想”装上 Claude Code 就开始改代码”，看完前 3 节就够。如果你想把它从一个聊天框升级成”团队里最熟练的那个工程师”，那就要看完全部 10 节。

这篇是 PromptNet 的 Claude Code 母页面，串联站内 13+ 篇深度文（链接全文带），覆盖从第一次安装到自建 Agent 工作流的完整路径。

一、Claude Code 是什么：vs Cursor、Codex、网页版 ChatGPT

Claude Code 是 Anthropic 出品的官方终端 AI 编程工具，目前支持 4 种形态：

  • CLI 终端版：npm install -g @anthropic-ai/claude-code，在任意项目目录直接 claude 启动
  • Desktop 桌面应用（Mac / Windows）
  • VS Code / JetBrains 扩展：编辑器内置面板
  • Web 版（claude.ai/code）：浏览器内运行，无需本地装

它和市面上其他 AI 编程工具的本质区别在于运行模式：

工具模式特点
Claude CodeAgent 模式进入项目目录、读文件、改文件、跑命令、看报错、再修
Cursor / Windsurf编辑器集成在 IDE 内嵌入，主要做 inline 补全 + chat
Codex / Copilot补全模式输入时按 Tab 出建议
网页版 ChatGPT聊天框你复制代码进去问，再粘贴出来

一句话判断：你需要它读你整个项目并改多个文件——选 Claude Code；你只是写代码时想要补全——Cursor / Copilot；你只是问个概念——网页版 Claude / ChatGPT 就够。

详细横向对比见 Claude Code vs Cursor 选型分析。

二、安装与首次配置：5 分钟把环境跑起来

CLI 终端版（最常用）

前置：Node.js 20+。

1
2
npm install -g @anthropic-ai/claude-code
claude  # 第一次运行会引导登录

登录走 OAuth 跳浏览器，不需要 API Key——只要你有 Claude.ai 账号（Pro / Max / Team / Enterprise 任意档），都可以直接用。

第一次进入项目

1
2
cd /path/to/your/project
claude

进入后第一条建议消息：让它读项目结构。

1
> 看一下这个项目，告诉我它是什么、用了什么技术栈

这一步看似多余，但能让 Claude Code 把你的项目结构、关键文件、依赖关系存进它的本地索引（CodeGraph / 项目快照），后续改代码效率高出 30%+。

完整新手流程见 Claude Code 怎么用：从安装到第一次改代码。

Windows / Linux 注意

  • Windows 用 PowerShell 或 Git Bash，不要用 cmd（路径解析不一致）。
  • WSL 里跑 Claude Code 比原生 Windows 体验好，文件 watcher 更稳。
  • 终端宽度建议 ≥ 100 列，否则 diff 显示会折行。

三、三种核心模式：默认、Plan Mode、Fast Mode

Claude Code 在 2026 年正式分化出三种执行模式：

模式触发方式适用场景
默认（Sonnet）直接输入任务90% 日常改代码
Plan Mode/plan 或 Shift+Tab复杂改动前先看计划
Fast Mode/fast简单确定性任务，要速度

默认模式：什么都不做就是这个

用 Claude Sonnet 4.6，在性价比和能力之间最平衡的档位。日常改代码、写测试、修 bug 全用它就够。

Plan Mode：值得专门开一节讲

按 Shift+Tab 切入 Plan Mode，Claude 会先列出”打算怎么做”，让你确认后再动文件。

适合：

  • 改动跨 ≥ 3 文件
  • 不确定它会不会”理解错你的意图”
  • 你不想被它写一堆没用的东西再回滚

不适合：

  • 改一个 typo
  • 加一行 console.log

详细使用：Claude Code Plan Mode 实战。

Fast Mode：用 Opus 但更快

/fast 切换到 Opus 4.7 + 输出加速。适合：批量改、明确无歧义的任务、长 session 后期。

注意：Fast Mode 不是”用便宜模型”，反而是用更贵的 Opus——但因为输出质量更稳定、不需要多轮纠正，总账单往往比默认模式还低 10-20%。详见 Claude Code Fast Mode 详解。

四、核心命令与提示工程：让它真的懂你的项目

Claude Code 的命令体系不复杂，记住下面 6 个就能覆盖 80% 场景：

命令作用
/clear清空当前 session（context 太长时用）
/plan进入 Plan Mode
/fast进入 Fast Mode
/skill <name>主动调用某个 skill
/init为项目生成 CLAUDE.md（项目级常驻指令）
Ctrl+C 两次退出

提示工程的 3 条铁律

很多人觉得 Claude Code “不听话”，多半是提示问题。3 条原则：

1. 先给目标，再给约束。

❌ “请用 React Hook 重写这个函数，不要用 class，不要改测试，要保持现有 API”
✅ “把 src/components/UserCard.tsx 重写成函数组件 + Hook。约束：API 不变；不改 __tests__ 目录”

2. 让它先 Read 再写。

❌ “加一个登录页”（它会凭想象生成）
✅ “看一下 src/pages/signup.tsx，仿照它的结构在同目录加一个 login.tsx“

3. 验证方式写在任务里。

❌ “改一下这个 bug”
✅ “改完后跑 npm test -- UserCard，绿了再说改完”

更多最佳实践见 Claude Code 进阶实战 10 个技巧。

五、Skills 体系：自带技能 + 自定义 + Skill Hub

Skills 是 Claude Code 2026 年最重要的能力升级。本质是可复用的提示包——把”如何做某类任务”封装成一个文件，让 Claude 在合适场景自动调用。

三层 Skills

  1. 官方自带：Claude Code 安装后默认带 30+ 内建 skill（superpowers、debugging、TDD、git-worktrees 等）
  2. 社区 Skill Hub：github.com/anthropics/skills 收录开源 skill
  3. 自定义：在项目 .claude/skills/ 或全局 ~/.claude/skills/ 写自己的

自定义一个最简 skill（5 分钟）

新建 ~/.claude/skills/run-tests/SKILL.md：

1
2
3
4
5
6
7
8
9
---
name: run-tests
description: Use when user asks to run tests or verify changes. Detects test runner from package.json and runs the right command.
---

When the user asks to run tests:
1. Read package.json to detect test runner (jest / vitest / playwright)
2. Run the appropriate command
3. If failures, summarize and suggest fixes

然后 Claude Code 在任何项目里都能 /skill run-tests 调用。

完整教程：Claude Skills 实战指南：从写一个到注册成可调用技能。

推荐先装的 10 个 Skill

参考 Claude Code Skills 推荐：GitHub Stars 最高的 10 个。

六、MCP 接入实战：stdio / 路径 / JSON-RPC 排错

MCP（Model Context Protocol）是 Anthropic 推动的开放协议，让 Claude Code 能调用外部工具——文件系统、Git、数据库、Slack、Notion 全部能挂载。

最简 MCP 配置

~/.claude/claude_desktop_config.json：

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    }
  }
}

重启 Claude Code，会看到 MCP filesystem connected。

接入失败 90% 的原因

按发生频率排：

  1. 路径用相对路径或带空格：MCP 必须用绝对路径，且不能含空格
  2. stdio 卡死：服务端没正确实现 stdio 协议（用 stdin/stdout，不要 print 调试信息）
  3. JSON-RPC 格式错：服务端返回的不是合法 JSON-RPC 2.0
  4. 权限问题：Windows 下 npm 全局安装路径要在 PATH 里

完整排错流程：MCP Server 接入 Claude Code 老是失败？。

七、Subagent 与并行执行：Workflow / Task tool

当一个任务能被拆成多个独立子任务，Claude Code 可以并行派出多个 subagent，每个负责一块。

什么时候该用 Subagent

  • 同时审计 N 个文件（每个 agent 看一段）
  • 跨多个模块同时重构
  • 大批量内容生成（每个 agent 一篇文章）
  • 需要”分头探索 + 汇总”（research 类任务）

Workflow 工具

1
2
3
const results = await parallel(
  files.map(f => () => agent(`Audit ${f} for SQL injection`))
)

5 分钟跑完原本要 50 分钟的任务，token 成本只增加 20-30%（因为大部分是新 context，不重复读历史）。

实战完整代码见 Claude Code 实战工作流 的”并行审计”段。

八、Git 工作流 + Code Review 嵌入

Claude Code 默认会做 Git 操作——但有几条铁规则：

  1. 从不主动 commit / push，除非你明确说”提交”
  2. 不在默认分支直接改，会先建 feature 分支
  3. PR 描述要带 evidence（运行了什么测试、看了什么 diff）

最佳搭配：Code Review skill

让 Claude Code 写完代码后主动跑一次 code review：

1
> 写完了，现在用 code-reviewer skill 检查一下我刚改的几个文件

它会切换成”审稿员”角色：找 bug、找性能问题、找命名不一致。比你自己看 diff 找得更全。

完整 Git 工作流详见 Claude Code Git 工作流：分支、提交与代码审查怎么配合。

九、真实项目案例 + 常见错误排查 checklist

案例：把一个静态站点加上多语言 i18n

任务：BeanRank（WordPress + 静态主题）加中英文双语，改约 25 个文件。

走法：

  1. /plan 进入 Plan Mode，让它先列出”要改哪些文件、改什么”
  2. 我审计计划，删掉 3 个不该改的（friend-link 组件不要碰）
  3. 退出 Plan Mode，让它执行
  4. 跑构建，碰到 3 个 i18n key 没注册的报错
  5. 直接把报错丢给它，3 分钟修完
  6. 用 code-reviewer skill 跑一遍，发现 1 个硬编码中文漏改

总耗时 45 分钟，独立完成约 90 分钟工作量。

错误排查 checklist（按出现频率）

症状多半是修复
“context too long”session 太久没 /clear/clear 重开
改完代码不工作它没看到关联文件主动 Read 那些文件后再改
一直问”要不要做 X”任务粒度太大拆到具体步骤
工具调用失败权限或 MCP 配置看 ~/.claude/logs/
输出突然变笨model 自动降级（额度满了）看右上角 model 标识

详细 checklist：Claude Code 常见错误与排错清单。

十、自建 Agent 工作流：SDK + Hooks + CronCreate

到这一步，你已经把 Claude Code 当工具用得很熟了。下一步是把它变成你工作流的一部分——后台运行、自动触发、嵌入应用。

三层进阶能力

Hooks：在事件发生时自动跑代码。

~/.claude/settings.json：

1
2
3
4
5
6
7
8
9
10
11
12
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {"type": "command", "command": "npm run lint:fix"}
        ]
      }
    ]
  }
}

每次 Claude 改文件后自动跑 lint:fix。

CronCreate：让 Claude 自动定时执行。

1
> 每天早上 9 点检查一次 PR，有新评论提醒我

Claude Code 会用 CronCreate 工具登记到调度器。

Claude Agent SDK：把 Claude Code 嵌进你自己的应用。

1
2
3
4
5
6
7
from anthropic import Anthropic

client = Anthropic()
result = client.agents.create(
    instructions="你是 BeanRank 的内容审稿员...",
    tools=[...]
)

SDK 适合：你想做一个自己的 SaaS 产品，里面用 Claude 做内容审核 / Agent / 自动化。

CLI 适合：你只是用它干活，不打算嵌进产品。

详细取舍：Claude Agent SDK vs Claude Code CLI：怎么选。如果你纠结的是”自建 SDK 还是用现成的托管 Agent 平台”，Managed Agents vs Claude Code 这篇延展回答了这个分支。

高频问答（FAQ）

Q1：Claude Code 收费吗？

CLI 本身免费，但要消耗 Claude API 额度。如果你用 Claude.ai Pro 订阅，CLI 用量从订阅额度里扣；如果用 API Key，按 token 计费（Sonnet $3/M 输入、$15/M 输出）。

详细成本计算见 Claude API 成本对比，同主题的全模型横向价格表见 2026 AI API 价格对比。

Q2：和 Cursor 比，哪个适合大型项目？

Claude Code 更适合大型多文件项目——因为它跑在终端、能并行、能挂 MCP 工具、能自定义 Skill。Cursor 优势在编辑器内即时反馈，适合中小项目和快节奏 coding。完整对比：Claude Code vs Cursor 选型分析。

Q3：Plan Mode 和 Fast Mode 能同时用吗？

不能同时，但可以串联：先 /plan 看计划，确认后退出 Plan Mode，再 /fast 切到 Opus 加速执行。这是改动较大但你已经清楚要怎么做时的最优组合。

Q4：Claude Code 能用国内大模型吗？

不能直接用。Anthropic 的官方 CLI 只对接 Claude API。但 Claude Agent SDK 支持自定义 model provider，理论上可接 DeepSeek / Qwen 等——前提是它们兼容 Anthropic 的 tool-use 格式。社区有 anyrouter 类项目做协议转换，但稳定性不如官方。

Q5：会被自动 commit / push 吗？

不会，除非你明确允许。Claude Code 的安全规则之一：所有”对外可见”的操作（git push / 部署 / 发邮件）必须用户确认。你可以放心让它在本地随便改。

Q6：3 万行的老项目能用吗？

能，但要做两件事：

  1. 项目根写 CLAUDE.md，告诉它项目结构、命名约定、要避免改的文件
  2. 第一次进项目让它先跑 /init，建立索引

之后它能在 30K+ 行项目里精准改 5-10 个文件，不会乱碰。