Claude Code 实战手册：从安装到多仓库并行开发（2026）
Claude Code 实战手册：从安装到多仓库并行开发（2026）
如果说 2025 年是「AI 补全代码」的一年，那 2026 年就是「AI 接管终端」的一年。Claude Code 是这波变化里最有代表性的工具之一——它不是编辑器插件，而是一个跑在命令行里、能读你整个仓库、能自己跑测试、能改多个文件的编码代理。
这篇是我实际用下来的一份操作手册，不讲愿景，只讲怎么用、怎么用好、以及哪些地方会翻车。
一、安装与第一次运行
Claude Code 通过 npm 分发，需要 Node 18 以上：
npm install -g @anthropic-ai/claude-code
claude --version
在你的项目目录里直接启动：
cd ~/projects/my-app
claude
第一次运行会引导你登录（浏览器授权或粘贴 API Key）。登录后你会看到一个交互式提示符，直接用自然语言说话就行：
> 这个项目是干什么的？先给我一个架构概览
它会自己去读 README、package.json、目录结构，然后给你总结。注意它不是一次性把整个仓库塞进上下文，而是按需检索——这是它能处理大仓库的关键。
二、CLAUDE.md：最重要的一个文件
用 Claude Code 最大的效率分水岭，就是有没有写 CLAUDE.md。
这个文件放在仓库根目录，会在每次会话开始时自动加载，相当于给 AI 的「入职文档」。没有它，你每次都要重复解释一遍项目约定；有了它，AI 一上来就知道规矩。
一份实用的 CLAUDE.md 大概长这样：
# 项目约定
## 技术栈
- Node.js 22 + Express（ESM，type: module）
- EJS 模板，无构建链
- 数据库：node:sqlite（内置，不要引入 better-sqlite3 等原生依赖）
## 代码风格
- 单引号、2 空格缩进、不加分号以外的额外格式化
- 新增路由统一写在 server.js 的 ROUTES 区块内
- 不要自作主张添加 TypeScript
## 命令
- 启动：npm start
- 测试：npm test（必须全绿才算完成）
- 部署：python deploy-linux/sync.py
## 禁止事项
- 不要修改 data/ 目录下的任何文件
- 不要 git commit，改完让我 review
关键点：写「禁止事项」比写「应该做什么」更有效。AI 的默认行为通常是合理的，你真正要管的是那些它会想当然做错的地方。
三、日常工作流：三种典型用法
1. 探索型：先问再动
进入一个不熟悉的仓库，别急着让它改代码：
> 用户登录这条链路是怎么走的？从请求进来到 session 写入，列出涉及的文件和函数
它会自己 grep、读文件，给你一条清晰的调用链。这一步花 30 秒，能省掉后面十分钟的来回纠错。
2. 修改型：给足上下文
差的提示词：
> 修一下登录的 bug
好的提示词：
> server.js 第 210 行的 verifyToken，在 token 过期时抛异常而不是返回 null，
> 导致 /admin 路由 500 而不是 302 跳登录。改成返回 null，
> 并在 requireAuth 中间件里加上 302 处理。改完跑一下 npm test。
差别不在「礼貌」，在你有没有把问题定位清楚。Claude Code 很擅长执行，不那么擅长猜你的意图。
3. 批量型：交给它自己迭代
> 把 views/ 下所有模板里硬编码的站点名改成从 res.locals.siteName 读取，
> 改完逐个文件 diff 给我看
这类机械但繁琐的活是它的主场。记得加上「diff 给我看」，否则它改完你不知道动了什么。
四、并行开发：Git Worktree 是隐藏大招
单线程用 Claude Code，你会一直在等它。真正提速的做法是开多个 worktree，让多个实例同时干活：
# 主仓库保持干净
git worktree add ../my-app-feat-auth -b feat/auth
git worktree add ../my-app-fix-perf -b fix/perf
# 开两个终端，分别在两个目录跑 claude
cd ../my-app-feat-auth && claude
cd ../my-app-fix-perf && claude
两个实例互不干扰，各自跑各自的测试，最后分别提 PR。这套做法对「一个大重构 + 若干小修复」的场景特别管用。
注意：worktree 之间 node_modules 不共享，每个目录要单独 npm install。可以用 pnpm 的全局 store 缓解磁盘占用。
五、成本控制：几个真实有效的办法
按 token 计费的工具，不控制成本会很痛。实测有效的几条：
1. 用 /clear 而不是一直聊下去
上下文越长，每一轮的输入 token 越多。一个任务做完就 /clear，别让无关历史一直跟着。
2. 大文件先摘要再处理
让它读一个 5000 行的日志文件是纯烧钱。先用 shell 过滤：
grep -n "ERROR" app.log | tail -50 > /tmp/errors.txt
再让它读 /tmp/errors.txt。
3. 把重复性规则写进 CLAUDE.md
每次都在对话里解释「我们用 ESM 不用 CommonJS」，等于每次都付这段话的钱。写进文件里也要付，但至少你不用打字，而且它更可靠。
4. 简单任务别用它
改个错别字、加个 console.log，自己两秒钟的事，不用惊动 AI。
六、五个真实会踩的坑
坑 1：它以为改完了，其实没跑通
Claude Code 会报告「已完成」，但不一定验证过。养成习惯：让它必须跑测试或起服务验证，并把输出贴出来。在 CLAUDE.md 里写死「完成的定义是 npm test 全绿」。
坑 2：大范围重构会失控
让它「重构整个数据层」这种任务，它会改一大片然后你 review 不过来。拆成小步：一次一个模块，一次一个 PR。
坑 3：它会「贴心地」加你不要的东西
比如自动加 TypeScript 类型、自动加 ESLint 配置、自动写一堆注释。禁止事项一定要写清楚。
坑 4：破坏性命令
它有执行 shell 的能力。rm -rf、git reset --hard、git push --force 这类命令，务必开启确认模式，别无脑放行。生产环境凭据不要放在它能读到的地方。
坑 5：长会话会「忘事」
上下文压缩后早期的约定可能丢失。重要约定放 CLAUDE.md（每次重载），而不是只在对话里说过一次。
七、什么时候不该用它
- 你自己都不知道要做什么：AI 不能替你想清楚需求，模糊需求只会得到模糊代码。
- 高度依赖领域知识的业务逻辑：它写得出代码，写不出你行业里那些「大家都知道但没人写下来」的规则。
- 对安全性要求极高的模块：认证、加密、支付，AI 写完你必须逐行看懂再合并。看不懂就别合。
小结
Claude Code 的定位不是「更聪明的自动补全」，而是一个初级到中级的工程师同事：干活快、执行力强、需要明确指令、需要 review。
把它当同事用，你会发现三件事最重要：写好 CLAUDE.md（入职文档）、把任务拆小（合理派活）、坚持验证（code review）。这三件做到位，它能实实在在帮你省下每天一两个小时。
做不到位，它就是个很贵的随机数生成器。
版本迭代很快，具体命令与计费策略请以 Anthropic 官方文档为准，本文基于 2026 年 8 月的实践整理。