1. 项目概述与思路拆解1.1 国内开发者为什么关注 Claude Code先说结论Claude Code 是 Anthropic 官方推出的终端编程代理工具它能在命令行里直接理解你的代码库帮你写代码、改代码、跑测试、查错误、做代码审查甚至帮你执行 git 操作。跟很多聊天框里写代码的 AI 工具不同Claude Code 直接长在你的项目目录里能读你本地的文件能调用终端命令像一个真正的结对程序员坐在你旁边而不是一个只能隔空对话的助手。国内开发者对这类工具的关注度一直很高原因也很现实大家日常要面对的技术栈越来越杂从前后端到脚本、DevOps、数据分析一个人要干的活越来越多。终端型的 AI 编程工具能显著减少上下文切换——不用在 IDE 和聊天网页之间来回粘贴代码直接在终端里说帮我看看这里为什么报错它自己会去翻代码、跑命令、给你答案。这种工作方式比单纯用网页版聊天窗口效率高出太多。不过这里必须先把合规前提说清楚Claude Code 的使用受 Anthropic 服务条款和区域政策的约束你需要使用官方支持的账号体系并在符合相关要求的环境下运行。本文分享的所有实操细节都是我在这类合规前提下验过的东西不讲任何绕开限制的操作也不会推荐任何违规的工具或手段。合规是底线大家在使用前务必自行确认自己所在区域和服务条款的允许范围。1.2 终端型 AI 编程工具的定位差异如果你用过网页版的 AI 助手再去用 Claude Code最大的感受是它不再是一个回答问题的 AI而是一个动手干活的 AI。为什么差别这么大关键在于它拥有两个普通聊天工具没有的能力——文件系统访问和命令执行权限。具体来说Claude Code 能做的事情包括扫描整个项目目录理解代码结构而不是只看你粘贴的那一段。读写项目文件自动修改代码并生成 diff。执行测试、lint、构建、git 命令等并把输出结果反馈给模型继续分析。通过 CLAUDE.md 文件记住你最常用的约定、架构偏好和项目规则。支持子代理sub-agent并行处理任务让一个小团队的工作量在终端里单口相声式完成。这些能力意味着你可以直接对它说这个功能目前太慢帮我找出瓶颈并优化它会自己去看性能数据、定位热点、改代码、再跑一遍测试验证。这已经接近低配版 AI 程序员了。对国内开发者来说还有一个非常实际的点终端工具不吃 IDE 内存SSH 到服务器上也能用适合在后端开发、服务部署、服务器运维等场景里直接干活。这篇博文我就围绕拿到 Claude Code 之后怎么一步步用起来展开把安装、配置、常用工作流、中文优化和踩坑经验一次讲透。2. 安装与初始化配置全记录2.1 环境准备先看 Node.js 版本Claude Code 是通过 npm 分发的命令行工具安装的前置条件比较简单但对 Node.js 版本有要求。官方建议 Node.js 18我实测下来较老的 14/16 版本会在启动时报各种奇怪的语法错误还不如直接用 nvm 装一个最新的 LTS 版本更省心。检查方法很直接node -v npm -v如果版本不够可以这样升级以 nvm 为例curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新打开终端后 nvm install --lts nvm alias default --lts装好 Node.js 后安装 Claude Code 本身非常简单npm install -g anthropic-ai/claude-code安装完可以运行claude --version验证。我第一次看到这个命令时还愣了一下——这里claude是命令名后面跟参数跟聊天没关系它就是一整个交互式终端程序。2.2 登录认证账号体系的几种方式Claude Code 的认证方式有几种国内开发者最常用的其实是 API Key 方式。但不管哪种前提都是你在官方支持的范围内注册并拥有合法的账号。推荐用 API Key 方式因为它的隔离性最好适合团队内部按成员分配额度。具体步骤是在 api 控制台创建 API Key。在终端里设置环境变量export ANTHROPIC_API_KEYsk-ant-xxxxxxx直接运行claude它会自动识别环境变量并进入交互模式。另一种方式是运行claude后选择登录按钮完成 OAuth 流程这种方式会绑定你的 Claude 账号订阅比较适合个人用户。我个人的经验是如果是自己一个人用用订阅登录最方便因为不用管 API 计费细节如果是在公司团队里推广用 API Key 环境变量管理更规范方便按项目配置不同的限额和审计。2.3 首次启动后的关键配置项首次进入 Claude Code 交互界面后你会看到一个简单的提示符。这时候先别急着干活建议先确认几个配置项。在交互界面里斜杠命令是你的好朋友。最常用的是/config它会打开一个配置面板里面可以设置模型选择默认用 Claude 系列的最强模型但可以根据任务类型切换。复杂重构选能力更强的简单问答选更快的。权限模式建议首次使用先设置为询问模式每当它要执行命令或改文件时都会征求你的同意。等你熟悉了再按项目调整成自动。主题和显示这个看个人喜好我一般用暗色主题。另外还有一个非常关键的文件叫~/.claude/settings.json它相当于全局配置文件。比如我想让所有项目统一走 API Key可以提前设置好默认的环境变量来源想加代理这里加的是 HTTP 代理配置但注意必须在合法合规的前提下使用且仅用于满足网络合规要求的场景我不展开讲具体配置因为那是另一个话题。具体配置结构类似这样{ env: { ANTHROPIC_API_KEY: sk-ant-... }, permissions: { defaultMode: acceptEdits } }我踩过的一个坑是如果同时设置了多个认证来源比如环境变量和登录态都有可能会认到不同的身份导致配额混乱。建议只用一种认证方式别混用。2.4 模型选择什么时候用什么模型Claude Code 里的模型选择直接决定了生成代码的质量、速度和成本。我个人的经验是分层使用任务类型推荐模型原因大规模重构、架构设计、疑难 bug 分析最强模型推理能力强能 hold 住复杂上下文日常写函数、写注释、写测试标准模型成本/质量平衡好批量简单脚本生成快速模型速度快token 消耗低适合机械性任务在/config里可以切换也可以用快捷键。刚开始不要太纠结先用默认模型跑通一个任务感受一下它怎么读代码、怎么给反馈再逐步调整。3. 核心工作流与实操要点3.1 让 Claude Code 先看懂你的项目Claude Code 启动后的第一件事不是立刻让它改代码而是先让它熟悉项目结构。虽然它自己会去扫描目录但如果项目特别大或者有些目录不希望它读取比如 node_modules、dist、.git最好一开始就设置好忽略规则。它默认遵循项目的.gitignore这是比较省心的做法。但如果你想自定义它的视野可以在项目根目录创建一个.claudeignore文件语法跟.gitignore类似node_modules/ dist/ build/ .env *.png这个文件的作用是告诉 Claude Code这些目录里头的文件你都不用看。我第一次跑一个微服务仓库时没配这个文件结果它把整个 target 目录编译输出都读了一遍白白浪费了一堆 token而且分析质量被无关文件干扰。加了忽略列表后明显清爽多了。还要提一句 CLAUDE.md。这是 Claude Code 的项目记忆文件放在项目根目录每次会话启动时它都会自动读取。我通常在里面写这几类内容项目的技术栈和目录结构。代码风格规范比如缩进、命名法、注释头。哪些目录是关键模块、哪些是生成文件不要动。常用的构建/测试命令。比如# 项目配置说明 - 前端React TypeScript组件用函数式写法不用 class 组件。 - 后端Python FastAPI路由文件放在 routes/ 目录下。 - 测试项目根目录运行 pytest tests/。 - 不要修改生成目录src/generated/。这样一来每次会话它都会自动带着这些规矩去干活不会反复问同样的问题。3.2 实战演示从接手一个新仓库到完成一个小功能我拿一个常见的场景来做示例假设你要在一个已有的 Python 项目里加一个从 CSV 导入用户的功能但你不熟悉这个项目的结构。第一步直接启动cd ~/work/some-project claude然后在交互界面里输入CLAUDE: 请先看一下项目结构然后告诉我如果我要加一个从 CSV 导入用户的功能应该放在哪个模块涉及哪些文件它会先读项目树然后结合代码内容给你一个建议。我当时遇到的情况是项目里已经有现成的数据库访问层和用户模型但导入逻辑没有它建议我在services/importers/下面新建一个模块并复用现有的UserRepository类。接下来直接下指令CLAUDE: 那就实现这个功能遵循项目的命名规范写入合适的模块先不要改现有代码。它就开始干活了——读相关文件、写新代码、生成 diff。这里注意如果设置的是询问权限它每写一个文件都会先问你要不要应用更改。我建议刚开始不要放开所有权限至少先亲眼看看它写的 diff 质量。等操作熟了再考虑对某些低风险目录开自动写入。写完后让它跑测试CLAUDE: 运行项目的测试套件看这个新功能有没有破坏现有逻辑。它会执行测试命令读取输出如果失败了还会自己分析报错原因尝试修复再跑一遍。这一整套交互流程从看代码到写代码到验证代码全部在终端里完成不需要把代码复制到任何网页对话框里。3.3 权限控制让 AI 干活但不失控权限控制是使用 Claude Code 的核心安全课题。它需要执行命令、写文件如果完全放开相当于给了一个能操作你电脑的 AI如果完全不放开那效率又起不来。所以我使用这样的三级策略全局默认所有文件编辑和命令执行都询问。对某个项目如果这是我已经熟悉的仓库、且只做低风险操作就开成允许自动执行测试和 lint 命令。对高风险目录比如.github/workflows、生产配置目录永远设为禁止或询问。在实际对话中它也会主动报出自己打算执行什么命令例如⏺ 想要运行pytest tests/test_import_users.py 是否允许 (Y/n)这时候不要无脑按 y先看一眼命令是什么。我遇到过它想执行一个删除编译产物的命令虽然无害但也说明它有可能推断错目标所以该拦还是拦。3.4 斜杠命令和快捷操作在日常使用中斜杠命令能省很多事。我经常用的有/help查看所有命令说明。/clear清空当前会话上下文适合换任务的时候用避免上一话题干扰下一话题。/review对当前改动做一次代码审查。这个我强烈推荐它相当于给你加了一个不会累的 code reviewer。/compact把当前超长的上下文做压缩保留核心信息继续对话。当对话特别长、token 消耗变高的时候很好用。/init在项目根目录快速生成一个 CLAUDE.md 配置文件。此外Claude Code 还支持从命令行直接传参数适合写脚本化调用。比如claude -p 分析当前目录下所有 Python 文件的圈复杂度 --output-format text这样可以把它当成一个命令行 AI 工具来集成到自己的工作流中比如在 CI 里做代码审查或者写一个 shell 脚本批量处理多个文件。不过要提醒批量调用时注意 API 配额消耗我见过有人写了个循环调用结果一晚上跑掉了不少额度。4. 中文场景优化与本地化实战4.1 Claude Code 对中文的支持能力Claude Code 的底层模型本身对中文的理解和生成能力很强所以完全可以用中文来对话。我在实际使用中基本全程用中文下指令它能准确理解帮我把这个函数改成异步的这个接口的返回字段少了一个 create_time加上这类描述。生成代码里的注释和文档它也能按你的要求用中文写。不过有一个细节如果你让它在代码里写中文注释要注意项目的编码格式。绝大多数现代项目都是 UTF-8 编码没问题但如果碰到老项目是 GBK 或 GB2312 编码Claude Code 读取文件时可能会出现乱码。遇到这种情况先不要急着怪工具先确认文件编码然后统一转成 UTF-8 再让它加工否则改完的文件很可能互相打架。4.2 用 CLAUDE.md 打磨中文项目风格很多国内项目的代码注释习惯跟国外不太一样比如喜欢在文件头部写作者/创建时间在函数里写参数说明/返回值说明等。为了让 Claude Code 生成的代码风格符合团队习惯我会在 CLAUDE.md 里写得非常细# 代码风格 - 所有代码注释使用中文但要避免口语化使用该字结构。 - 函数文档使用 Google 风格 docstring说明文字用中文。 - 日志消息使用英文避免控制台输出乱码。 - Python 变量命名统一用 snake_case类名用 PascalCase。设置好之后它写出来的代码确实会贴合团队风格不用你再手动改一遍。这个文件值得花时间打磨因为它是你与 AI 之间最重要的约定。4.3 中文 prompt 的几个实用技巧用中文跟 Claude Code 交流有几个技巧能让它更听话。第一把需求说完整但不要说废话。比如不推荐你帮我看看吧这个有点问题。推荐请在src/utils/time.py中找到parse_time函数它目前不能处理带毫秒的时间字符串请修改它兼容2024-01-01 12:00:00.123格式并补充测试用例。第二一次性给出约束条件。它写代码时如果没给约束可能会自由发挥。我一般会在指令里直接加上不要引入新的第三方依赖保持现有函数签名不变兼容 Python 3.8等。这些约束就像需求文档里的非功能要求必须明确说出来。第三让它说思路再动手。复杂任务先让它给方案你确认后再执行。比如CLAUDE: 先不要写代码分析这个模块现有实现给出 2 种重构方案对比它们的取舍。等它列出方案你再选择很多时候能避免它一头扎进某个坑里。4.4 处理中文环境下的路径和文件名问题Windows 系统上使用 Claude Code 时要特别小心中文路径。比如项目目录是D:\项目A\服务端\在交互界面中输入路径时建议直接用相对路径避免因为在命令行粘贴了带中文的全路径导致解析问题。另外如果配置文件里的路径用到中文也要确保终端编码是 UTF-8。在 Linux 服务器上这种问题相对少见但如果你的系统 locale 没设置好可能在创建中文文件名时出现 Unicode 乱码。建议检查echo $LANG一般输出en_US.UTF-8或zh_CN.UTF-8都行。如果输出C或POSIX就手动改一下~/.bashrcexport LANGen_US.UTF-8 export LC_ALLen_US.UTF-8这些细节看着小但真遇到乱码问题的时候排查起来特别费时间提前配好能省不少心。5. 实战案例用 Claude Code 完成一个模拟项目 X 的代码重构5.1 项目背景为了把前面的方法串起来我模拟一个真实场景某项目模块代称模拟项目 X是一个内部报表系统早期代码是单文件方式写的一个report.py里堆了四千多行既有数据库查询、又有 HTML 渲染逻辑、又有邮件发送代码。新需求是要支持多种报表格式PDF、Excel、CSV并且后续还要接入更多数据源。这个任务如果用人工重构少说也得一两天用 Claude Code 能不能加速我实际跑过一遍效果可以但过程有不少值得记录的细节。5.2 第一步让 Claude Code 全面体检启动 Claude Code 后我先没让它动手而是做了这样一轮对话我 请分析 report.py 的结构输出以下内容 1. 这个文件里的所有函数和类及其职责。 2. 哪些部分是强耦合的例如直接操作全局变量、依赖 HTML 模板等。 3. 根据职责划分设想一种把该文件拆分为多个模块的方式。它花了几十秒扫描代码然后给出了一个结构报告。我看了下基本上准确它识别出了数据获取层、处理层、展示层混在一起的问题甚至指出某个全局连接池对象在多处被隐式复用是隐患。这一步相当于先让 AI 帮你画了一张代码地图。5.3 第二步制定重构方案根据它的分析我要求它在不写代码的前提下先给重构计划我 请给出一份详细的重构计划要求 - 保持外部调用接口不变避免影响其他模块。 - 拆分后模块按 data/、render/、delivery/ 三个目录组织。 - 不引入新依赖。 - 拆完后补充单元测试。它给出的计划包括具体文件划分、每个文件里的函数清单、依赖关系图文本形式以及一个分阶段执行的顺序。我根据经验微调了其中两个文件的命名然后批准它执行。5.4 第三步分阶段执行与检查我不建议让 AI 一口气完成一个大重构因为一旦它陷入某个局部问题容易越改越乱。所以我把重构拆成三个阶段每个阶段单独执行和验证阶段一抽出data_loader.py把数据库连接和查询代码搬进去。阶段二抽出renderer.py把 HTML 渲染逻辑拆进去。阶段三抽出delivery.py把邮件发送和文件输出逻辑拆进去。在阶段一执行时它很快写完新文件并在旧report.py里留下了调用新文件的代码。但我发现一个问题新模块的函数名跟旧函数名不一致它没有自动重构所有调用点。此时我提醒它检查全项目是否还有引用旧函数名的地方并统一更新。它才执行了全局搜索替换。这个经验很重要Claude Code 理解拆代码这个动作但不一定自动帮你完成全局联动重构你得明确要求它搜索所有引用点。好在新重构完有一个优势——它自己可以跑测试来验证有没有漏改的地方。5.5 第四步测试补齐与代码审查重构完让它跑一遍原有测试果然挂了两个用例。原因是有个地方它把常量值写错了另一个是模块导入路径少了一层。这些错误如果人工排查靠报错信息也能定位但它自己定位更快——它读取堆栈自己改了文件又跑了一遍测试全部通过。接着我用了/review让它在已经改完的代码上做一次 code review。它给出的意见大致是有个函数参数过多建议用数据类封装。data_loader中部分查询语句没有参数化有 SQL 注入风险。某些异常处理太笼统应该捕获具体异常类型并记录上下文。这些意见里第一条是风格问题可改可不改但第二条是实打实的风险点我让它立刻修复。最后它补充了几个针对拆分后模块的单元测试整个重构就算是闭环了。6. 常见问题与排查技巧实录6.1 登录与认证类问题现象可能原因解决办法运行claude报未认证环境变量未生效echo $ANTHROPIC_API_KEY检查确认 export 后重启终端在交互界面里提示账户无权限账号类型不支持 API 访问确认账号已开通 API 权限或改走订阅登录会话开始后很快结束日志里出现 401API Key 过期或错误重新创建 Key检查是否多出空格或换行符团队内多人共用同一个 Key并发超限每人分配独立 Key或者用官方的配额管理我踩过最笨的一个坑把 Key 写入.bashrc之后忘记source ~/.bashrc结果一直说未认证。这类低级问题反而最浪费情绪以后检查顺序一定是先看环境变量再看 Key 本身是否有效。6.2 权限与执行类问题现象可能原因解决办法它想改文件但一直问很烦权限模式是询问在/config里将该目录调整为允许编辑不允许删除文件但它需要清理旧版本权限配置未放开删除对临时目录单独放开删除权限或手动删除后再让它继续执行命令时输出乱码终端字符集问题设置 UTF-8 环境变量Windows 上使用新版终端某目录无法读取权限不足或符号链接问题检查目录权限ls -la或让其读取绝对路径下的同名文件这里我想说一个容易被忽略的点Claude Code 在权限模式下即使允许编辑文件它也可能过度保守。比如它要修改某个配置文件时会停下来请求确认哪怕你已经授权过同类文件。这是因为不同文件的危险级别不同。遇到这种情况别嫌烦安全第一总比数据被误删好。6.3 token 消耗与性能优化Claude Code 的本质是把项目上下文发送给大模型所以 token 消耗跟项目体量、对话长度直接相关。我用的几个省钱技巧项目大时先配好.claudeignore把无关的编译产物、资源文件、日志全部排除。任务不要跨太大如果一次做了三件不相关的事中途/clear换一个新会话。使用/compact压缩超长对话它会把前面的话题浓缩成摘要继续保留有效信息。批量任务不要循环调用写成单个命令一次完成减少重复的上下文加载开销。我自己试过最夸张的一次在没配 ignore 的 monorepo 里让它读全部文件结果几分钟就消耗了几十万 token。配好 ignore 之后同样的任务 token 量至少下降了 80%。6.4 输出质量问题与处理思路有时候它写出来的代码不一定符合预期常见的包括逻辑正确但风格不合多半是 CLAUDE.md 没有写清风格约定。把它要求的风格写进文件能显著减少这类问题。局部修改导致全局不兼容提醒它搜索所有引用点并运行测试验证。幻觉式 API 调用特别是它记住的某个第三方库方法名可能是错的。遇到这种情况让它直接 去读node_modules里这个包的类型定义文件 或者pip show对应包信息让它基于真实代码来修正答案。过度设计给一个小函数生成了一堆抽象类。解决办法是把保持简单写进 CLAUDE.md并在指令中明确不要新增多余的抽象层。6.5 一个隐藏技巧让 Claude Code 自己诊断问题当我遇到它行为诡异的时候比如突然改错了多个文件、或者在一个问题上绕来绕去最有效的做法是直接问它CLAUDE: 你现在处于什么状态回忆一下你执行过的操作分析可能出错的地方然后告诉我下一步建议。你会发现它能很好地自我复盘甚至帮你找出是因为上下文太长导致它忘掉了最初的约束。这个能力本质上是模型对对话历史的反思能力用好了能解决很多隐性问题。7. 一些经验上的沉淀与提醒用 Claude Code 这段时间我最大的体会是它不会替你思考但它能把你的思考落地得飞快。你仍然需要懂项目、懂架构、懂业务否则你根本不知道该让它改什么、怎么约束它、怎么验收它。它更像是把手动挡换成了自动挡但方向盘还是得你来握。我习惯把 Claude Code 当成极速结对程序员而不是全自动外包。每次对话前我会先想清楚三个问题我的目标是什么。哪些边界它不能碰。怎么验证它做对了。整个过程里CLAUDE.md和权限配置是反复打磨的地方。一个完善的知识库配置能让你和它之间的沟通成本下降一大半而严格的权限设置能在它偶尔抽风时保住你的代码库和服务器。最后分享一个小技巧在项目里建立一份CLAUDE.md之后别担心它不更新。你完全可以每隔一段时间让它自己总结项目的变化并更新这份文件让 AI 帮你维护给 AI 看的项目手册。这算是用魔法打败魔法吧。工具在不断迭代工作方式也要跟着调整但底层的思考能力和工程判断永远是开发者的核心竞争力。 
长河君 · 2026/10/13 17:05:37 · 阅读 1.2k Claude Code实战指南：终端AI编程工具的安装、配置与高效工作流
1. 项目概述与思路拆解1.1 国内开发者为什么关注 Claude Code先说结论Claude Code 是 Anthropic 官方推出的终端编程代理工具它能在命令行里直接理解你的代码库帮你写代码、改代码、跑测试、查错误、做代码审查甚至帮你执行 git 操作。跟很多聊天框里写代码的 AI 工具不同Claude Code 直接长在你的项目目录里能读你本地的文件能调用终端命令像一个真正的结对程序员坐在你旁边而不是一个只能隔空对话的助手。国内开发者对这类工具的关注度一直很高原因也很现实大家日常要面对的技术栈越来越杂从前后端到脚本、DevOps、数据分析一个人要干的活越来越多。终端型的 AI 编程工具能显著减少上下文切换——不用在 IDE 和聊天网页之间来回粘贴代码直接在终端里说帮我看看这里为什么报错它自己会去翻代码、跑命令、给你答案。这种工作方式比单纯用网页版聊天窗口效率高出太多。不过这里必须先把合规前提说清楚Claude Code 的使用受 Anthropic 服务条款和区域政策的约束你需要使用官方支持的账号体系并在符合相关要求的环境下运行。本文分享的所有实操细节都是我在这类合规前提下验过的东西不讲任何绕开限制的操作也不会推荐任何违规的工具或手段。合规是底线大家在使用前务必自行确认自己所在区域和服务条款的允许范围。1.2 终端型 AI 编程工具的定位差异如果你用过网页版的 AI 助手再去用 Claude Code最大的感受是它不再是一个回答问题的 AI而是一个动手干活的 AI。为什么差别这么大关键在于它拥有两个普通聊天工具没有的能力——文件系统访问和命令执行权限。具体来说Claude Code 能做的事情包括扫描整个项目目录理解代码结构而不是只看你粘贴的那一段。读写项目文件自动修改代码并生成 diff。执行测试、lint、构建、git 命令等并把输出结果反馈给模型继续分析。通过 CLAUDE.md 文件记住你最常用的约定、架构偏好和项目规则。支持子代理sub-agent并行处理任务让一个小团队的工作量在终端里单口相声式完成。这些能力意味着你可以直接对它说这个功能目前太慢帮我找出瓶颈并优化它会自己去看性能数据、定位热点、改代码、再跑一遍测试验证。这已经接近低配版 AI 程序员了。对国内开发者来说还有一个非常实际的点终端工具不吃 IDE 内存SSH 到服务器上也能用适合在后端开发、服务部署、服务器运维等场景里直接干活。这篇博文我就围绕拿到 Claude Code 之后怎么一步步用起来展开把安装、配置、常用工作流、中文优化和踩坑经验一次讲透。2. 安装与初始化配置全记录2.1 环境准备先看 Node.js 版本Claude Code 是通过 npm 分发的命令行工具安装的前置条件比较简单但对 Node.js 版本有要求。官方建议 Node.js 18我实测下来较老的 14/16 版本会在启动时报各种奇怪的语法错误还不如直接用 nvm 装一个最新的 LTS 版本更省心。检查方法很直接node -v npm -v如果版本不够可以这样升级以 nvm 为例curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新打开终端后 nvm install --lts nvm alias default --lts装好 Node.js 后安装 Claude Code 本身非常简单npm install -g anthropic-ai/claude-code安装完可以运行claude --version验证。我第一次看到这个命令时还愣了一下——这里claude是命令名后面跟参数跟聊天没关系它就是一整个交互式终端程序。2.2 登录认证账号体系的几种方式Claude Code 的认证方式有几种国内开发者最常用的其实是 API Key 方式。但不管哪种前提都是你在官方支持的范围内注册并拥有合法的账号。推荐用 API Key 方式因为它的隔离性最好适合团队内部按成员分配额度。具体步骤是在 api 控制台创建 API Key。在终端里设置环境变量export ANTHROPIC_API_KEYsk-ant-xxxxxxx直接运行claude它会自动识别环境变量并进入交互模式。另一种方式是运行claude后选择登录按钮完成 OAuth 流程这种方式会绑定你的 Claude 账号订阅比较适合个人用户。我个人的经验是如果是自己一个人用用订阅登录最方便因为不用管 API 计费细节如果是在公司团队里推广用 API Key 环境变量管理更规范方便按项目配置不同的限额和审计。2.3 首次启动后的关键配置项首次进入 Claude Code 交互界面后你会看到一个简单的提示符。这时候先别急着干活建议先确认几个配置项。在交互界面里斜杠命令是你的好朋友。最常用的是/config它会打开一个配置面板里面可以设置模型选择默认用 Claude 系列的最强模型但可以根据任务类型切换。复杂重构选能力更强的简单问答选更快的。权限模式建议首次使用先设置为询问模式每当它要执行命令或改文件时都会征求你的同意。等你熟悉了再按项目调整成自动。主题和显示这个看个人喜好我一般用暗色主题。另外还有一个非常关键的文件叫~/.claude/settings.json它相当于全局配置文件。比如我想让所有项目统一走 API Key可以提前设置好默认的环境变量来源想加代理这里加的是 HTTP 代理配置但注意必须在合法合规的前提下使用且仅用于满足网络合规要求的场景我不展开讲具体配置因为那是另一个话题。具体配置结构类似这样{ env: { ANTHROPIC_API_KEY: sk-ant-... }, permissions: { defaultMode: acceptEdits } }我踩过的一个坑是如果同时设置了多个认证来源比如环境变量和登录态都有可能会认到不同的身份导致配额混乱。建议只用一种认证方式别混用。2.4 模型选择什么时候用什么模型Claude Code 里的模型选择直接决定了生成代码的质量、速度和成本。我个人的经验是分层使用任务类型推荐模型原因大规模重构、架构设计、疑难 bug 分析最强模型推理能力强能 hold 住复杂上下文日常写函数、写注释、写测试标准模型成本/质量平衡好批量简单脚本生成快速模型速度快token 消耗低适合机械性任务在/config里可以切换也可以用快捷键。刚开始不要太纠结先用默认模型跑通一个任务感受一下它怎么读代码、怎么给反馈再逐步调整。3. 核心工作流与实操要点3.1 让 Claude Code 先看懂你的项目Claude Code 启动后的第一件事不是立刻让它改代码而是先让它熟悉项目结构。虽然它自己会去扫描目录但如果项目特别大或者有些目录不希望它读取比如 node_modules、dist、.git最好一开始就设置好忽略规则。它默认遵循项目的.gitignore这是比较省心的做法。但如果你想自定义它的视野可以在项目根目录创建一个.claudeignore文件语法跟.gitignore类似node_modules/ dist/ build/ .env *.png这个文件的作用是告诉 Claude Code这些目录里头的文件你都不用看。我第一次跑一个微服务仓库时没配这个文件结果它把整个 target 目录编译输出都读了一遍白白浪费了一堆 token而且分析质量被无关文件干扰。加了忽略列表后明显清爽多了。还要提一句 CLAUDE.md。这是 Claude Code 的项目记忆文件放在项目根目录每次会话启动时它都会自动读取。我通常在里面写这几类内容项目的技术栈和目录结构。代码风格规范比如缩进、命名法、注释头。哪些目录是关键模块、哪些是生成文件不要动。常用的构建/测试命令。比如# 项目配置说明 - 前端React TypeScript组件用函数式写法不用 class 组件。 - 后端Python FastAPI路由文件放在 routes/ 目录下。 - 测试项目根目录运行 pytest tests/。 - 不要修改生成目录src/generated/。这样一来每次会话它都会自动带着这些规矩去干活不会反复问同样的问题。3.2 实战演示从接手一个新仓库到完成一个小功能我拿一个常见的场景来做示例假设你要在一个已有的 Python 项目里加一个从 CSV 导入用户的功能但你不熟悉这个项目的结构。第一步直接启动cd ~/work/some-project claude然后在交互界面里输入CLAUDE: 请先看一下项目结构然后告诉我如果我要加一个从 CSV 导入用户的功能应该放在哪个模块涉及哪些文件它会先读项目树然后结合代码内容给你一个建议。我当时遇到的情况是项目里已经有现成的数据库访问层和用户模型但导入逻辑没有它建议我在services/importers/下面新建一个模块并复用现有的UserRepository类。接下来直接下指令CLAUDE: 那就实现这个功能遵循项目的命名规范写入合适的模块先不要改现有代码。它就开始干活了——读相关文件、写新代码、生成 diff。这里注意如果设置的是询问权限它每写一个文件都会先问你要不要应用更改。我建议刚开始不要放开所有权限至少先亲眼看看它写的 diff 质量。等操作熟了再考虑对某些低风险目录开自动写入。写完后让它跑测试CLAUDE: 运行项目的测试套件看这个新功能有没有破坏现有逻辑。它会执行测试命令读取输出如果失败了还会自己分析报错原因尝试修复再跑一遍。这一整套交互流程从看代码到写代码到验证代码全部在终端里完成不需要把代码复制到任何网页对话框里。3.3 权限控制让 AI 干活但不失控权限控制是使用 Claude Code 的核心安全课题。它需要执行命令、写文件如果完全放开相当于给了一个能操作你电脑的 AI如果完全不放开那效率又起不来。所以我使用这样的三级策略全局默认所有文件编辑和命令执行都询问。对某个项目如果这是我已经熟悉的仓库、且只做低风险操作就开成允许自动执行测试和 lint 命令。对高风险目录比如.github/workflows、生产配置目录永远设为禁止或询问。在实际对话中它也会主动报出自己打算执行什么命令例如⏺ 想要运行pytest tests/test_import_users.py 是否允许 (Y/n)这时候不要无脑按 y先看一眼命令是什么。我遇到过它想执行一个删除编译产物的命令虽然无害但也说明它有可能推断错目标所以该拦还是拦。3.4 斜杠命令和快捷操作在日常使用中斜杠命令能省很多事。我经常用的有/help查看所有命令说明。/clear清空当前会话上下文适合换任务的时候用避免上一话题干扰下一话题。/review对当前改动做一次代码审查。这个我强烈推荐它相当于给你加了一个不会累的 code reviewer。/compact把当前超长的上下文做压缩保留核心信息继续对话。当对话特别长、token 消耗变高的时候很好用。/init在项目根目录快速生成一个 CLAUDE.md 配置文件。此外Claude Code 还支持从命令行直接传参数适合写脚本化调用。比如claude -p 分析当前目录下所有 Python 文件的圈复杂度 --output-format text这样可以把它当成一个命令行 AI 工具来集成到自己的工作流中比如在 CI 里做代码审查或者写一个 shell 脚本批量处理多个文件。不过要提醒批量调用时注意 API 配额消耗我见过有人写了个循环调用结果一晚上跑掉了不少额度。4. 中文场景优化与本地化实战4.1 Claude Code 对中文的支持能力Claude Code 的底层模型本身对中文的理解和生成能力很强所以完全可以用中文来对话。我在实际使用中基本全程用中文下指令它能准确理解帮我把这个函数改成异步的这个接口的返回字段少了一个 create_time加上这类描述。生成代码里的注释和文档它也能按你的要求用中文写。不过有一个细节如果你让它在代码里写中文注释要注意项目的编码格式。绝大多数现代项目都是 UTF-8 编码没问题但如果碰到老项目是 GBK 或 GB2312 编码Claude Code 读取文件时可能会出现乱码。遇到这种情况先不要急着怪工具先确认文件编码然后统一转成 UTF-8 再让它加工否则改完的文件很可能互相打架。4.2 用 CLAUDE.md 打磨中文项目风格很多国内项目的代码注释习惯跟国外不太一样比如喜欢在文件头部写作者/创建时间在函数里写参数说明/返回值说明等。为了让 Claude Code 生成的代码风格符合团队习惯我会在 CLAUDE.md 里写得非常细# 代码风格 - 所有代码注释使用中文但要避免口语化使用该字结构。 - 函数文档使用 Google 风格 docstring说明文字用中文。 - 日志消息使用英文避免控制台输出乱码。 - Python 变量命名统一用 snake_case类名用 PascalCase。设置好之后它写出来的代码确实会贴合团队风格不用你再手动改一遍。这个文件值得花时间打磨因为它是你与 AI 之间最重要的约定。4.3 中文 prompt 的几个实用技巧用中文跟 Claude Code 交流有几个技巧能让它更听话。第一把需求说完整但不要说废话。比如不推荐你帮我看看吧这个有点问题。推荐请在src/utils/time.py中找到parse_time函数它目前不能处理带毫秒的时间字符串请修改它兼容2024-01-01 12:00:00.123格式并补充测试用例。第二一次性给出约束条件。它写代码时如果没给约束可能会自由发挥。我一般会在指令里直接加上不要引入新的第三方依赖保持现有函数签名不变兼容 Python 3.8等。这些约束就像需求文档里的非功能要求必须明确说出来。第三让它说思路再动手。复杂任务先让它给方案你确认后再执行。比如CLAUDE: 先不要写代码分析这个模块现有实现给出 2 种重构方案对比它们的取舍。等它列出方案你再选择很多时候能避免它一头扎进某个坑里。4.4 处理中文环境下的路径和文件名问题Windows 系统上使用 Claude Code 时要特别小心中文路径。比如项目目录是D:\项目A\服务端\在交互界面中输入路径时建议直接用相对路径避免因为在命令行粘贴了带中文的全路径导致解析问题。另外如果配置文件里的路径用到中文也要确保终端编码是 UTF-8。在 Linux 服务器上这种问题相对少见但如果你的系统 locale 没设置好可能在创建中文文件名时出现 Unicode 乱码。建议检查echo $LANG一般输出en_US.UTF-8或zh_CN.UTF-8都行。如果输出C或POSIX就手动改一下~/.bashrcexport LANGen_US.UTF-8 export LC_ALLen_US.UTF-8这些细节看着小但真遇到乱码问题的时候排查起来特别费时间提前配好能省不少心。5. 实战案例用 Claude Code 完成一个模拟项目 X 的代码重构5.1 项目背景为了把前面的方法串起来我模拟一个真实场景某项目模块代称模拟项目 X是一个内部报表系统早期代码是单文件方式写的一个report.py里堆了四千多行既有数据库查询、又有 HTML 渲染逻辑、又有邮件发送代码。新需求是要支持多种报表格式PDF、Excel、CSV并且后续还要接入更多数据源。这个任务如果用人工重构少说也得一两天用 Claude Code 能不能加速我实际跑过一遍效果可以但过程有不少值得记录的细节。5.2 第一步让 Claude Code 全面体检启动 Claude Code 后我先没让它动手而是做了这样一轮对话我 请分析 report.py 的结构输出以下内容 1. 这个文件里的所有函数和类及其职责。 2. 哪些部分是强耦合的例如直接操作全局变量、依赖 HTML 模板等。 3. 根据职责划分设想一种把该文件拆分为多个模块的方式。它花了几十秒扫描代码然后给出了一个结构报告。我看了下基本上准确它识别出了数据获取层、处理层、展示层混在一起的问题甚至指出某个全局连接池对象在多处被隐式复用是隐患。这一步相当于先让 AI 帮你画了一张代码地图。5.3 第二步制定重构方案根据它的分析我要求它在不写代码的前提下先给重构计划我 请给出一份详细的重构计划要求 - 保持外部调用接口不变避免影响其他模块。 - 拆分后模块按 data/、render/、delivery/ 三个目录组织。 - 不引入新依赖。 - 拆完后补充单元测试。它给出的计划包括具体文件划分、每个文件里的函数清单、依赖关系图文本形式以及一个分阶段执行的顺序。我根据经验微调了其中两个文件的命名然后批准它执行。5.4 第三步分阶段执行与检查我不建议让 AI 一口气完成一个大重构因为一旦它陷入某个局部问题容易越改越乱。所以我把重构拆成三个阶段每个阶段单独执行和验证阶段一抽出data_loader.py把数据库连接和查询代码搬进去。阶段二抽出renderer.py把 HTML 渲染逻辑拆进去。阶段三抽出delivery.py把邮件发送和文件输出逻辑拆进去。在阶段一执行时它很快写完新文件并在旧report.py里留下了调用新文件的代码。但我发现一个问题新模块的函数名跟旧函数名不一致它没有自动重构所有调用点。此时我提醒它检查全项目是否还有引用旧函数名的地方并统一更新。它才执行了全局搜索替换。这个经验很重要Claude Code 理解拆代码这个动作但不一定自动帮你完成全局联动重构你得明确要求它搜索所有引用点。好在新重构完有一个优势——它自己可以跑测试来验证有没有漏改的地方。5.5 第四步测试补齐与代码审查重构完让它跑一遍原有测试果然挂了两个用例。原因是有个地方它把常量值写错了另一个是模块导入路径少了一层。这些错误如果人工排查靠报错信息也能定位但它自己定位更快——它读取堆栈自己改了文件又跑了一遍测试全部通过。接着我用了/review让它在已经改完的代码上做一次 code review。它给出的意见大致是有个函数参数过多建议用数据类封装。data_loader中部分查询语句没有参数化有 SQL 注入风险。某些异常处理太笼统应该捕获具体异常类型并记录上下文。这些意见里第一条是风格问题可改可不改但第二条是实打实的风险点我让它立刻修复。最后它补充了几个针对拆分后模块的单元测试整个重构就算是闭环了。6. 常见问题与排查技巧实录6.1 登录与认证类问题现象可能原因解决办法运行claude报未认证环境变量未生效echo $ANTHROPIC_API_KEY检查确认 export 后重启终端在交互界面里提示账户无权限账号类型不支持 API 访问确认账号已开通 API 权限或改走订阅登录会话开始后很快结束日志里出现 401API Key 过期或错误重新创建 Key检查是否多出空格或换行符团队内多人共用同一个 Key并发超限每人分配独立 Key或者用官方的配额管理我踩过最笨的一个坑把 Key 写入.bashrc之后忘记source ~/.bashrc结果一直说未认证。这类低级问题反而最浪费情绪以后检查顺序一定是先看环境变量再看 Key 本身是否有效。6.2 权限与执行类问题现象可能原因解决办法它想改文件但一直问很烦权限模式是询问在/config里将该目录调整为允许编辑不允许删除文件但它需要清理旧版本权限配置未放开删除对临时目录单独放开删除权限或手动删除后再让它继续执行命令时输出乱码终端字符集问题设置 UTF-8 环境变量Windows 上使用新版终端某目录无法读取权限不足或符号链接问题检查目录权限ls -la或让其读取绝对路径下的同名文件这里我想说一个容易被忽略的点Claude Code 在权限模式下即使允许编辑文件它也可能过度保守。比如它要修改某个配置文件时会停下来请求确认哪怕你已经授权过同类文件。这是因为不同文件的危险级别不同。遇到这种情况别嫌烦安全第一总比数据被误删好。6.3 token 消耗与性能优化Claude Code 的本质是把项目上下文发送给大模型所以 token 消耗跟项目体量、对话长度直接相关。我用的几个省钱技巧项目大时先配好.claudeignore把无关的编译产物、资源文件、日志全部排除。任务不要跨太大如果一次做了三件不相关的事中途/clear换一个新会话。使用/compact压缩超长对话它会把前面的话题浓缩成摘要继续保留有效信息。批量任务不要循环调用写成单个命令一次完成减少重复的上下文加载开销。我自己试过最夸张的一次在没配 ignore 的 monorepo 里让它读全部文件结果几分钟就消耗了几十万 token。配好 ignore 之后同样的任务 token 量至少下降了 80%。6.4 输出质量问题与处理思路有时候它写出来的代码不一定符合预期常见的包括逻辑正确但风格不合多半是 CLAUDE.md 没有写清风格约定。把它要求的风格写进文件能显著减少这类问题。局部修改导致全局不兼容提醒它搜索所有引用点并运行测试验证。幻觉式 API 调用特别是它记住的某个第三方库方法名可能是错的。遇到这种情况让它直接 去读node_modules里这个包的类型定义文件 或者pip show对应包信息让它基于真实代码来修正答案。过度设计给一个小函数生成了一堆抽象类。解决办法是把保持简单写进 CLAUDE.md并在指令中明确不要新增多余的抽象层。6.5 一个隐藏技巧让 Claude Code 自己诊断问题当我遇到它行为诡异的时候比如突然改错了多个文件、或者在一个问题上绕来绕去最有效的做法是直接问它CLAUDE: 你现在处于什么状态回忆一下你执行过的操作分析可能出错的地方然后告诉我下一步建议。你会发现它能很好地自我复盘甚至帮你找出是因为上下文太长导致它忘掉了最初的约束。这个能力本质上是模型对对话历史的反思能力用好了能解决很多隐性问题。7. 一些经验上的沉淀与提醒用 Claude Code 这段时间我最大的体会是它不会替你思考但它能把你的思考落地得飞快。你仍然需要懂项目、懂架构、懂业务否则你根本不知道该让它改什么、怎么约束它、怎么验收它。它更像是把手动挡换成了自动挡但方向盘还是得你来握。我习惯把 Claude Code 当成极速结对程序员而不是全自动外包。每次对话前我会先想清楚三个问题我的目标是什么。哪些边界它不能碰。怎么验证它做对了。整个过程里CLAUDE.md和权限配置是反复打磨的地方。一个完善的知识库配置能让你和它之间的沟通成本下降一大半而严格的权限设置能在它偶尔抽风时保住你的代码库和服务器。最后分享一个小技巧在项目里建立一份CLAUDE.md之后别担心它不更新。你完全可以每隔一段时间让它自己总结项目的变化并更新这份文件让 AI 帮你维护给 AI 看的项目手册。这算是用魔法打败魔法吧。工具在不断迭代工作方式也要跟着调整但底层的思考能力和工程判断永远是开发者的核心竞争力。