Claude Code 快速开始

憋了很久，还是想说说心里话。

这两年很多人第一次打开 Claude Code，脑子里想的是一件事，能不能一句话把需求丢进去，然后等它自己把系统写完。

这种预期通常会把你带进坑里。

Claude Code 真正强的地方，不是替你思考，不是帮你蒙答案，而是把你已经拆明白的问题，变成一段能执行、能验证、能回滚的工程动作。你负责判断、拆解和验收，它负责读代码、改文件、跑命令、补测试。它更像一个外脑，一个执行力很强的搭档，而不是一个"神谕机"。

这篇文档解决什么问题

如果你是 Java、Golang、Node.js 这类工程项目的开发者，这篇文档会直接解决三件事。

• 怎么把 Claude Code 在本机稳定跑起来
• 怎么在项目里初始化出可维护的上下文
• 怎么把它纳入真正的开发工作流，而不是停留在演示阶段

如果你还没完全建立概念，可以先补一眼 什么是 Claude Code。如果你已经带着具体故障进来，建议同时打开 Claude Code 常见问题大全。

快速开始之前，先把认知摆正

我见过太多人把 Claude Code 用废，问题不在模型，问题在使用姿势。

低效的方式，是把它当成聊天机器人，想到什么问什么，给一行模糊需求，然后等它猜你心思。

高效的方式，是把它当成一个能读仓库、能执行命令、能连续迭代的 Agent。你给目标、边界、约束、验证方式，它沿着这个轨道去干活。

这个区别，决定了你感受到的是惊喜，还是失望。

第一步，确认环境已经够用

Claude Code 跑在 Node.js 生态上，最低要求是 Node.js >= 18.0。我自己的建议更直接一点，别卡最低线，尽量用 LTS 版本。

node -v
npm -v

如果 node -v 输出低于 v18.0.0，或者命令根本找不到，先去看 Node.js 环境配置指南。

如果你人在国内，npm install 很慢，或者 claude login、claude 一启动就超时，这很常见，直接看 国内网络避坑指南。

第二步，安装 Claude Code

环境没问题之后，直接装。

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

安装完先确认命令已经进 PATH。

claude --version
which claude

如果 which claude 没结果，通常就三种情况。

npm 全局目录没在 PATH 里

npm config get prefix

如果输出类似 /usr/local、/opt/homebrew、~/.npm-global，但 claude 还是找不到，把对应的 bin 目录加进 shell 配置。

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

权限不够，装了一半就失败

macOS 或 Linux 下不要急着全局 sudo，优先用 Node 版本管理器把权限问题收掉。实在临时救火，再用下面这条。

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

npm 源有缓存污染

npm cache clean --force
npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code

第三步，登录或者接入中转

官方链路能直连，就走官方登录。

claude login

终端会拉起浏览器完成授权。看到 Login successful，这一步就算过了。

如果你用的是兼容网关或者中转 API，就别走浏览器登录，直接走环境变量。

export ANTHROPIC_API_KEY="your_api_key"
export ANTHROPIC_BASE_URL="https://your-gateway.example.com/v1"
claude

你如果希望每次开终端自动生效，把这两行写进 ~/.zshrc 或 ~/.bashrc。

echo 'export ANTHROPIC_API_KEY="your_api_key"' >> ~/.zshrc
echo 'export ANTHROPIC_BASE_URL="https://your-gateway.example.com/v1"' >> ~/.zshrc
source ~/.zshrc

第四步，进入项目根目录做初始化

别在空目录里瞎聊，直接进真实仓库。

cd /path/to/your-project
claude /init

/init 这一步很重要。很多朋友会跳过，然后抱怨输出不稳定。这很正常，因为你没告诉它这个仓库该怎么工作。

初始化之后，你要把 CLAUDE.md 当成项目协作协议去维护。写得越具体，后面返工越少。

一个能直接用的 CLAUDE.md 模板

# Project Overview

## Tech Stack
- Java 21
- Spring Boot 3.3
- MySQL 8
- Redis 7
- Maven

## Run Commands
- Build: mvn clean package -DskipTests
- Test: mvn test
- Dev: mvn spring-boot:run

## Architecture Notes
- controller 只处理入参校验和响应封装
- service 负责业务编排
- repository 只做数据访问
- 外部依赖统一走 gateway 层

## Coding Rules
- 优先复用现有模块，不要新造轮子
- 新增接口必须补充参数校验
- 新增逻辑必须补单元测试
- 不要修改无关文件

## Delivery Rules
- 先分析，再给计划，再执行
- 每次改动后说明影响范围
- 执行结束后给出验证命令

CLAUDE.md 里最该写清楚的 5 件事

• 项目怎么构建，怎么测试，怎么启动
• 目录分层和依赖边界
• 命名规范和代码风格
• 什么能改，什么不要碰
• 任务完成后你希望它如何自检

第五步，别急着改代码，先让它理解仓库

真正高效的起手式，不是直接说「给我加个支付系统」。

更稳的做法是先让它建立上下文。

请先阅读当前项目的目录结构、构建文件和核心 README。
告诉我这个仓库的核心模块、启动方式、测试方式，以及你认为改动用户订单链路时需要注意的边界。
暂时不要修改代码。

这一步看起来慢，其实是在省后面的返工时间。

第六步，进入完整工作流

很多人把 AI 当算命先生，丢一句模糊的话过去，等它自己悟。

这种玩法，短演示可能还能看，真进项目，大概率翻车。

常见低效做法，把 AI 当成算命先生

第一种，上来就要结果。

帮我重构支付模块

问题在于，支付模块多大，动到哪些文件，要不要兼容老接口，要不要补测试，它都得猜。

第二种，只给报错，不给边界。

这个项目启动不了，你修一下

它可能会一路改到你不想碰的配置、脚本、依赖版本，最后你自己都不知道它动了什么。

第三种，让它自由发挥。

你觉得怎么做好就怎么改

这种指令最危险。Claude Code 能执行，不代表它应该替你做架构决策。

推荐高效做法，清晰 Context，加明确约束

同样是做支付模块，我更建议按下面这个节奏走。

第一轮，只让它读和讲。

分析当前订单、支付、退款相关代码。
告诉我现有支付链路涉及哪些模块、核心类、外部依赖和潜在耦合点。
不要修改代码。

第二轮，让它出计划。

/plan
目标是把支付渠道适配层从 OrderPaymentService 中拆出来。
要求兼容现有 API，不修改数据库表结构，新增单元测试。
请给出分步骤计划和风险点。

第三轮，开始执行，但一次只做一小段。

按计划先完成第 1 步和第 2 步。
改完后总结变更点，并告诉我下一步要不要继续。

第四轮，把验证写进流程里。

执行 mvn test。
如果测试失败，先分析失败原因，再修复和重跑。
不要跳过失败用例。

第五轮，交付前做复盘。

总结这次改动涉及的文件、潜在影响面、回滚方式，以及我上线前还要人工确认的点。

你想想看，这一套下来，你没有把判断权丢掉，但执行速度会快很多。

这才是 Claude Code 在工程里真正有价值的用法。

如果你想把这种工作方式再往上收一层，下一步建议读 Vibe Coding 概念与实战。如果你想把规则和上下文做成可查询能力，再继续读 MCP 基础：Week 1 从零到入门。

一个最小可用的真实工作流

如果你今天就想上手，可以从这个闭环开始。

场景，修一个明确的 Bug

分析最近一次提交后用户登录失败的问题。
先阅读 auth 模块和最近的报错日志，定位根因。
不要直接改代码，先给判断。

确认判断没跑偏，再继续。

只修复你刚才确认的根因。
改动范围限制在 auth 模块。
补充最少必要的测试。
执行 mvn test，并汇总结果。

最后让它给你一段交付说明。

给我一份简洁的变更说明，包含：
1. 改了什么
2. 为什么这样改
3. 测试怎么验证
4. 还有什么风险

场景，给遗留系统补测试

阅读 OrderService 的核心逻辑。
梳理当前分支下最值得补的 3 个单元测试场景。
说明每个场景覆盖的风险点，暂时不要写代码。

选中一个场景，再让它落地。

先实现你提到的第 1 个测试场景。
如果依赖太重，允许使用 mock，但不要为了通过测试而修改生产逻辑。
执行 mvn -Dtest=OrderServiceTest test

常用命令

命令	用途
claude	启动交互模式
claude --version	查看当前版本
claude /init	初始化项目上下文
Ctrl + C	中断当前执行

最容易踩的坑

任务描述太大

一句话想让它「完成整个模块」，基本等于把判断、执行、验证全混在一起了。

不提供约束

不说哪些文件能改，不说不能动数据库，不说要不要补测试，后面就容易出现你不想要的改动。

不做验收

只看 diff 不跑测试，最后线上兜底，代价会很高。

把 CLAUDE.md 当一次性文件

项目演化了，CLAUDE.md 不更新，Agent 拿到的上下文就会越来越陈旧。

下一步该看哪篇

• 想把环境一次性装顺，去看 安装与集成配置
• 想把 Node、npm、PATH 这些细节处理干净，去看 Node.js 环境配置指南
• 想在国内网络下稳定用起来，去看 国内网络避坑指南
• 想把 Agent 真正纳入日常开发，去看 实战自动化工作流
• 想把输出风格和项目边界稳定下来，去看 Vibe Coding 概念与实战
• 想让 Claude Code 读取项目规则而不是靠猜，去看 MCP 基础：Week 1 从零到入门
• 遇到具体故障和排障问题，直接查 Claude Code 常见问题大全