Claude Code CLI 上手与项目协作指南

它是活在终端里的，不是另一个聊天窗口

先把认知校准一下：Claude Code 不是 Web 版 Claude 的终端翻版，而是一个直接在你的项目目录里工作的 AI agent。它能读你的文件、改你的代码、跑你的命令、访问你的 Git 历史。装好之后 cd 到项目根目录，敲 claude 就能开始。

安装和初始化

装好 Claude Code

npm install -g @anthropic-ai/claude-code，装完终端里就有 claude 命令了。需要 Node.js 18+。第一次运行会要求登录 Anthropic 账号或配置 API key。

第一次进项目

cd 到项目根目录，运行 claude。它会自动扫描目录结构。如果项目里有 CLAUDE.md 文件（项目级指令），它会自动读取并遵循里面的规则。

这个 CLAUDE.md 文件非常重要——可以在里面写清楚技术栈、代码规范、目录约定、禁止操作。Claude Code 后续所有操作都会参考它，相当于给它立规矩。如果你跟它协作经常出现风格不一致的问题，八成是这个文件没写好。

权限机制

Claude Code 默认在执行文件修改、运行命令之前请求你确认。你可以逐次手动确认（最安全），也可以对特定类型的操作授予 session 级别的信任，还可以在 settings.json 里预设信任范围。正式项目里建议不要一开始就全部放开，先跑几轮观察它的行为模式。

更稳的使用方式

1. 先让它读懂项目

第一步别急着改代码。先问它："这个项目的目录结构是什么样的""入口文件在哪""数据库操作走的什么方案"。这步的目的不是要一份漂亮总结，而是确认它有没有真的摸到关键边界。如果它对项目的理解有偏差，后续改动的准确率都会打折扣。

2. 任务拆小再交给它

Claude Code 最怕一句话打包的大任务，比如"把这个页面重构一下"。更稳的方式是拆开来：先定位问题在哪几个文件 → 圈定要改的范围 → 改一小段 → 跑一下验证。任务越清楚，它动手的准确率越高，你后续 review 的成本越低。

实际体验下来，像"把这 3 个文件里的 XXX 接口调用从旧版迁移到新版"这种边界明确的任务，它完成度很高；但"帮我优化一下这个页面的用户体验"这种模糊任务，结果就难预测了。

3. 让它处理多文件改动和重复杂活

跨文件重命名、接口对齐、批量修 lint、整理 commit message、改配置文件——这些 Claude Code 做得很利索。它的优势不只是写代码，而是能在终端上下文里把几步连续操作串起来做，不用你反复切文件。

举个例子：你让它"把所有 API 路由里的错误响应从直接返回 500 改成统一的错误处理中间件"，它会自己找到所有相关文件、看当前的错误处理逻辑、改代码、顺便处理 import，一轮下来比你手动跳十几个文件快得多。

4. 善用 CLAUDE.md

在项目根目录放一个 CLAUDE.md，写进去的内容举例：

• 技术栈：Next.js 15 + TypeScript + Tailwind + Prisma
• 命名规范：组件用 PascalCase，工具函数用 camelCase
• 目录约定：API 路由统一放 app/api/，服务端逻辑放 src/services/
• 禁止操作：不要动 prisma/schema.prisma，不要删测试文件
• 项目上下文：这是一个 AI 工具导航站，面向 C 端用户

这个文件写得越具体，Claude Code 的行为就越稳定。

5. 关键判断不能外包

Claude Code 可以跑命令、改文件、做 Git 操作，但涉及业务逻辑、安全边界、数据风险和发布决策时，最终判断必须留在你手里。

最有价值的使用场景

• 看懂陌生仓库：刚接手一个项目，让它快速梳理模块结构、关键依赖和代码链路。比自己翻文件快得多，尤其是几万行代码的项目。
• 多文件批量改动：全局替换一个 API 接口名、统一错误处理风格、批量更新配置——自己做要开十几个文件，它一轮就搞完。
• 排查问题：贴一段报错让它定位原因，它会自己去读相关代码、查依赖关系、看配置文件，效率比在 IDE 里来回跳转高。
• 写脚本和工具：临时需要一个数据迁移脚本、一个测试数据生成器、一个部署检查工具——说清楚需求直接让它写。
• Git 操作协助：写 commit message、整理 changelog、准备 release notes。它能直接看到 diff 和提交历史，比你手动拼更准。

最容易踩的坑

坑 1：什么上下文都不给就让它改

cd 到项目里什么都不说就让它改代码，它只能靠猜。先花两分钟让它读一遍项目、看一下 CLAUDE.md，后续效率翻倍。

坑 2：一个 session 塞太多不相关的任务

Claude Code 的上下文窗口有限。如果一个 session 里又改前端又调后端又修部署脚本，到后面它对前面的改动记忆会模糊。任务差异大的时候果断开新 session。

坑 3：不看 diff 就全部放行

它每次改文件都会显示改动内容并请求确认。这不是走形式——认真看一眼 diff，能拦住很多细节问题。直接全部 approve 的人，最后花在排错上的时间通常更长。

坑 4：大型重构一步到位

让它一次性重构整个模块结构，结果往往难以 review。拆成小步，每步确认，最后的总体质量反而更高。

什么时候该用它

手里有真实项目，要做代码问答、多文件改动、批量修改、排查问题、写脚本——这些场景 Claude Code 很值得用。

不太适合的场景：只补一两行代码（IDE 补全更快）、对项目完全不了解还没建立上下文（先自己理解一下再让它帮忙）、需要极长时间持续运行的超大任务（上下文会耗尽，建议分 session）。