Claude Code 2026 入门:从安装到第一次提交

Claude Code 到底是什么

Claude Code 不是聊天界面,而是一个命令行代理。它读取你的文件系统、执行 bash 命令、修改文件,并不断对自己的产出做迭代,直到达成你描述的目标。你在项目目录里启动它、交付任务,它就会逐步推进:阅读现有代码、做出修改、运行测试,失败就回到上一步重做。

这意味着一件很务实的事:Claude Code 在真实代码库的、范围明确的具体问题上表现最好。让它"帮我看看这个项目"几乎一定会跑偏;让它"在 src/api/users.ts 的 createUser 函数里加上输入校验,并同步更新对应测试" —— 这才会拿到真正可用的结果。

第一步 —— 安装

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

验证安装是否成功:

claude --version
# → claude-code 1.x.x

在 macOS 或 Linux 上若遇到权限报错,标准做法是调整 npm 全局目录的所有权,而不是用 sudo 强行安装。Anthropic 文档的环境准备章节有详细说明。Windows 上用管理员身份打开终端可解决多数权限问题,但若你打算频繁跑代理任务,WSL2 路径要稳定得多。

第二步 —— 认证

claude login

命令会打开浏览器完成 OAuth。完成后凭据保存在 ~/.claude/ 中,除非你切换账户,无需重复这一步。

如果你直接使用 API key —— 例如在 CI 环境或没有浏览器的机器上 —— 改为设置环境变量即可:

export ANTHROPIC_API_KEY="sk-ant-api03-..."

Claude Pro 订阅自带每月 token 额度,足以覆盖中等强度的个人使用。如果你跑的是大型代码库、写大量测试、或者循环跑代理任务,基本会触顶 Pro 限额,需要再充 API 余额补充。Anthropic 控制台实时显示用量 —— 跑完前几次会话就去看一眼,把基线校准好。

第三步 —— 写好你的 CLAUDE.md

一份精简而有效的 CLAUDE.md 至少覆盖这五件事:

# Project: [name]

## Stack
- Runtime: Node 20, TypeScript 5.3
- Framework: Next.js 14 (App Router)
- Database: PostgreSQL via Prisma
- Tests: Vitest, run with `npm test`

## Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Lint: `npm run lint` — fix before committing
- Migrate: `npx prisma migrate dev`

## Rules
- All new API routes go in src/app/api/
- Zod for all input validation — no raw req.body access
- Never touch the /legacy/ directory
- Do not remove console.error calls in error handlers

## Do not
- npm install packages without asking first
- Modify .env files
- Run database migrations without confirmation

"Do not"小节是大多数开发者第一次写时跳过的,但它恰恰是防止昂贵失误的关键。如果有 Claude 永远不该碰的文件,把它们点名;如果有它不能擅自执行的命令,直接写明。

关于 CLAUDE.md 结构的更深入展开,见 写一份真正能用的 CLAUDE.md。Septim Starter 套件(9 美元)已为五种常见项目类型(Next.js、Python Flask、Rails、Go、纯 Node)备好了经实战检验的模板,免去你从空白文件起步的麻烦。

第四步 —— 交它一项真实任务

cd ~/projects/my-app
claude

在提示符下,交付一个完成标准明确的任务。下面这些都是适合新手的第一项任务:

• 给 /api/login 路由加上限流 —— 每个 IP 每分钟最多 5 次,超出返回 429
• 为 src/lib/date-utils.ts 中的每个函数写单元测试 —— 目标是 90% 分支覆盖率
• 把 src/components/UserTable.tsx 重构为使用 React Query,替换原始 fetch 调用

Claude Code 会读取相关文件、给出修改方案,在写盘或执行命令之前向你请示。默认配置下,任何写操作之前都会等你确认 —— 这是新手期最合适的工作模式。当你熟悉它的行为之后,可以在 ~/.claude/settings.json 中把权限放宽或收紧。

代理循环里到底发生了什么

一个典型的 Claude Code 任务会走完这样的循环:

1. 读取相关源文件,理解当前结构
2. 给出实现方案,列出将要改动的文件
3. 逐个文件写入修改,并附上说明
4. 跑测试套件(若 CLAUDE.md 中有配置),失败则迭代修复
5. 报告任务完成,列出所有改动过的文件

对相对简单的任务 —— 给表单加一个字段、写一个工具函数、修一个类型错误 —— 通常两分钟内跑完。对较大任务(模块重构、端到端加新功能),预留 5–15 分钟和几轮迭代。

第五步 —— 核对成本

访问 Anthropic 控制台 console.anthropic.com,你会看到按模型与日期拆分的 token 用量。前两三次会话之后就先去看一眼,把自己的"消耗节奏"摸清楚,再去跑更长的任务。

三种最容易导致成本失控的模式:

• 把大文件丢进上下文。如果 Claude Code 为了回答一个关于某函数的小问题,把一个 1 万行的文件全部读了一遍,你就为这 1 万行输入 token 付了钱。要点是:把它指向具体文件,而不是丢一个泛泛的"整体"问题给它。
• 反复重建上下文。会话中每条新消息都会重发完整对话历史。长会话的成本会迅速堆高。不相关的任务,起新会话,不要把一整天都塞进同一个会话里。
• 子代理派生。Claude Code 可以派生子代理做并行工作。每个子代理都有自己的上下文。同时跑多个代理时,成本会按比例放大。Tokenocalypse 指南有详细拆解 —— 见 子代理成本拆解。

一项范围合理的编程任务通常花费 0.05–0.40 美元的 API 余额,具体看文件大小与复杂度。如果你让 Claude Code"先理解整个代码库再动手",一次会话花掉几美元都很正常。第三步写好的 CLAUDE.md 能显著缓解第二种模式 —— 预先供给的上下文,直接替换掉它原本要花在探索上的 token。

新手第一次会话最容易踩的坑

让 Claude Code"看看我的项目,告诉我哪里有问题"

这是用整个上下文窗口去赌一次没准头的"巡视"。最终输出可能是一份泛泛的代码评审,确实能挑出一些真问题,但 token 代价昂贵。结构化的代码评审练习,请用 Septim Drills(29 美元);或者把 Claude Code 指向具体文件,问一个具体问题。

不读方案就直接批准

Claude Code 在执行前会先给出方案。请认真读。复杂任务里,方案中有时会包含你绝对不想批准的步骤 —— 删表、移除缓存层、动到你已经明令排除的文件。在方案阶段拦下,代价是零;让它写完盘再回滚,代价是 git revert。

不在版本控制下运行

Claude Code 会写盘。请只在工作树干净的仓库里运行,这样每次改动都能 git diff 复核,不满意的部分可以 git checkout . 撤掉。如果项目尚未使用 git,在第一次会话之前就先初始化仓库。

跳过 CLAUDE.md

没有 CLAUDE.md,Claude Code 会通过文件探索去推断项目上下文。这种推断既烧 token,在约定俗成、禁用命令、测试运行器这些方面又经常猜错。第三步上花的 20 分钟,会在你使用它的第一周就为你省回多倍。

下一步走向哪里

当你顺利完成几次任务之后,自然下一步是用 MCP server 扩展 Claude Code —— 把数据库、GitHub、浏览器等外部工具接入到它的工具链里。一份可执行的演练见 MCP server 教程。

如果你打算在团队内部署 Claude Code、自动化 PR 评审,PR 评审搭建指南 端到端讲解了 GitHub Action 配置。

面向规模化的成本管控 —— 当你过了新手阶段、Claude Code 成为日常工具后 —— 可参阅 成本监控指南 与 上下文管理。