1. 为什么值得把 Claude Code 装进你的工作流第一次听说 Claude Code 的时候我正被一个遗留项目里三百多行的工具函数折磨——改一个参数上下游五个文件跟着报错手动一个个改完还要跑测试确认没漏。当时我的第一反应是如果有个工具能直接读懂整个仓库的上下文我描述需求它来改改完还能自己跑测试验证那得省多少事。Claude Code 就是干这个的。它不是那种只会在编辑器里补全几行代码的插件而是一个跑在终端里的智能体能读文件、改代码、执行命令、跑测试甚至帮你提交 Git。你可以把它理解成一个坐在你旁边、熟悉你整个项目结构、随时听你指挥的结对搭档。这篇内容适合三类人一是完全没接触过命令行工具、但想试试 AI 辅助编程的开发者二是已经用过各种代码补全插件、想进一步把“改代码”这件事也交给 AI 的人三是团队里需要统一开发流程、想把 AI 工具接入现有 Git 工作流的技术负责人。不管你之前有没有用过类似的终端工具只要你能照着步骤敲命令就能跟着走完从安装到完成第一次代码修改的全过程。我会把每一步为什么这么做、可能踩什么坑都讲清楚而不是只丢一堆命令让你复制。核心关键词先摆出来Claude Code 的安装、代码修改、Git 集成、CLAUDE.md 配置文件。这四个词贯穿全文后面每个环节都会围绕它们展开。安装是入口代码修改是目的Git 是保障CLAUDE.md 是让 AI 真正懂你项目的关键。把这四件事串起来你就能形成一个完整的工作闭环。2. 安装前的环境准备与依赖梳理2.1 操作系统与终端环境的选择Claude Code 官方支持 macOS、Linux 和 Windows通过 WSL。如果你用的是 Windows我强烈建议走 WSL 这条路而不是直接在 PowerShell 或 CMD 里跑。原因很简单Claude Code 在执行命令时依赖大量 Unix 风格的 shell 工具比如grep、sed、find这些在原生 Windows 环境下要么没有要么行为不一致。WSL 给你一个完整的 Linux 子系统所有命令行为和 macOS/Linux 保持一致省去大量兼容性排查的时间。macOS 用户直接用系统自带的 Terminal 或者 iTerm2 就行Linux 用户用默认终端即可。有一个细节需要注意确保你的终端支持 256 色和 UTF-8 编码否则 Claude Code 的输出可能会出现乱码或者颜色显示异常。可以在终端里执行echo $TERM确认正常应该输出xterm-256color或类似值。如果不是在 shell 配置文件里加上export TERMxterm-256color即可。2.2 Node.js 与 npm 的安装配置Claude Code 是通过 npm 分发的所以 Node.js 是必须的前置依赖。官方要求 Node.js 18 或更高版本。我实测下来Node.js 20 LTS 是最稳的选择既不会太新导致某些包不兼容也不会太旧缺少必要的 API。安装 Node.js 有几种方式我推荐用版本管理工具而不是直接下载安装包。macOS 和 Linux 用户可以用nvmWindows WSL 用户同样可以用nvm。这样做的好处是以后切换 Node 版本只需要一行命令不会污染系统环境。# 安装 nvmmacOS/Linux/WSL 通用 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 如果你用 zsh改成 source ~/.zshrc # 安装 Node.js 20 LTS nvm install 20 nvm use 20 nvm alias default 20 # 验证安装 node -v # 应该输出 v20.x.x npm -v # 应该输出 10.x.x 或更高如果你不想用 nvm也可以直接从 Node.js 官网下载安装包。Windows 用户注意如果你选择在 WSL 里开发Node.js 也要装在 WSL 里而不是 Windows 侧。我见过有人 Windows 装了 NodeWSL 里跑 Claude Code 找不到 npm排查半天才发现是两套环境。2.3 Git 的安装与基础配置Git 是 Claude Code 工作流里不可或缺的一环。Claude Code 在修改代码后会通过 Git diff 来展示变更内容你也可以让它直接帮你执行git add和git commit。更重要的是Git 给了你一个安全网——如果 AI 改错了一条git checkout .就能回滚所有变更。# Ubuntu/Debian/WSL sudo apt update sudo apt install git -y # macOS如果没装过 brew install git # 验证 git --version安装完 Git 之后必须配置用户名和邮箱否则后续提交会报错git config --global user.name 你的名字 git config --global user.email 你的邮箱example.com还有一个容易被忽略的配置换行符处理。Windows 和 Unix 的换行符不同如果不配置Git 可能会在提交时自动转换导致 diff 里出现大量无意义的变更。建议加上# macOS/Linux/WSL git config --global core.autocrlf input # 纯 Windows 环境如果你坚持不用 WSL git config --global core.autocrlf true2.4 安装 Claude Code 本体前置依赖搞定后安装 Claude Code 本身只需要一条命令npm install -g anthropic-ai/claude-code安装完成后执行claude --version确认安装成功。如果提示找不到命令检查一下 npm 的全局 bin 目录是否在 PATH 里。可以用npm config get prefix查看全局安装路径然后确认这个路径下的bin目录已经加入 PATH。注意不要用sudo npm install -g这会导致权限问题后续升级也会很麻烦。如果遇到权限报错正确做法是配置 npm 的全局目录到用户目录下而不是加 sudo。首次运行claude命令时它会引导你完成认证。按照提示在浏览器里登录你的账号即可。认证信息会保存在本地后续使用不需要重复登录。3. 第一次启动与项目初始化3.1 在项目目录中启动 Claude Code安装完成后cd到你的项目根目录然后直接输入claude回车。Claude Code 会自动读取当前目录的文件结构建立一个初步的项目上下文。第一次启动时它会扫描目录下的文件但不会读取所有文件内容——那样太慢也没必要。它只会在你需要的时候按需读取相关文件。启动后你会看到一个交互式界面底部有输入框可以直接用自然语言描述你的需求。比如你可以输入“这个项目是做什么的”它会读取 README 和主要源码文件后给你一个总结。这一步的目的是确认 Claude Code 能正确识别你的项目结构。如果你在一个 Git 仓库里启动Claude Code 会自动感知 Git 状态包括当前分支、未提交的变更等。如果不在 Git 仓库里它会提示你初始化一个。我建议所有项目都用 Git 管理哪怕只是本地临时项目因为 Claude Code 的很多能力都依赖 Git 来提供上下文和安全保障。3.2 CLAUDE.md 文件的作用与创建CLAUDE.md 是 Claude Code 的“项目说明书”。每次启动时它会自动读取项目根目录下的 CLAUDE.md 文件把里面的内容作为系统提示的一部分。这意味着你可以在里面写项目规范、技术栈说明、代码风格要求、常用命令等Claude Code 会在整个会话中遵守这些约定。举个例子如果你在 CLAUDE.md 里写“所有函数必须用 JSDoc 注释”那么 Claude Code 在帮你写新函数时就会自动加上 JSDoc。如果你写“测试用 vitest 跑命令是npm run test”它就会用这个命令来验证修改。创建 CLAUDE.md 很简单在项目根目录新建一个文件即可# 项目说明 ## 技术栈 - 语言TypeScript 5.x - 框架React 18 Vite - 测试Vitest - 包管理pnpm ## 代码规范 - 使用 2 空格缩进 - 组件文件用 PascalCase 命名 - 工具函数用 camelCase 命名 - 所有导出函数必须有 JSDoc 注释 ## 常用命令 - 开发pnpm dev - 测试pnpm test - 构建pnpm build - 类型检查pnpm typecheck ## 注意事项 - 不要修改 src/config/ 目录下的文件 - 所有 API 请求必须经过 src/utils/request.ts 封装这个文件不需要一次写完美可以在使用过程中逐步补充。我自己的习惯是每次发现 Claude Code 做了不符合预期的行为就把对应的规范补进 CLAUDE.md下次它就不会再犯同样的错。3.3 用 /init 命令快速生成初始配置如果你不想手动写 CLAUDE.mdClaude Code 提供了一个/init命令它会自动分析你的项目结构、依赖文件、现有代码风格然后生成一份初始的 CLAUDE.md。我试过几个不同类型的项目生成的配置质量还不错尤其是技术栈和常用命令部分基本准确。不过自动生成的内容偏通用缺少项目特有的约束。我的做法是先用/init生成一版然后在此基础上手动补充项目特有的规范和注意事项。这样既省去了从零开始的时间又能保证关键约束不遗漏。提示CLAUDE.md 可以放在子目录里Claude Code 在处理该目录下的文件时会额外读取子目录的 CLAUDE.md。这个特性适合 monorepo 项目可以为每个子包定义不同的规范。4. 完成第一次代码修改的完整流程4.1 选择一个合适的练手任务第一次用 Claude Code 改代码不要上来就让它重构核心模块。选一个边界清晰、影响范围小、容易验证的任务。比如给某个工具函数加一个参数、修复一个明显的拼写错误、给一个组件加一行日志、或者补一个缺失的类型定义。我自己的第一次尝试是给一个日期格式化函数加一个timezone参数。这个任务足够简单但涉及函数签名修改、调用处更新、测试用例调整能完整体验 Claude Code 的读、改、验流程。选好任务后在 Claude Code 的输入框里用自然语言描述需求即可不需要特定的命令格式。4.2 描述需求与确认修改方案描述需求时尽量把上下文说清楚。比如不要只说“加一个 timezone 参数”而是说“在 src/utils/date.ts 的 formatDate 函数里加一个可选的 timezone 参数默认值为 UTC使用 Intl.DateTimeFormat 的 timeZone 选项来实现”。这样 Claude Code 不需要猜测你的意图直接进入实现阶段。Claude Code 收到需求后会先读取相关文件然后给出一个修改方案。它可能会问你几个澄清问题比如“是否需要同时更新测试文件”。这时候你可以直接回答它会继续。确认方案后它会展示具体的代码变更以 diff 的形式呈现新增行绿色删除行红色。这里有一个关键点Claude Code 默认不会直接修改文件而是先展示变更让你确认。你可以选择接受、拒绝或者要求它调整。这个确认机制很重要给了你一个审查的机会。我建议前几次使用时仔细看每一处变更确认没有问题再接受。熟悉之后可以开启自动接受模式提高效率。4.3 审查变更与运行验证接受变更后Claude Code 会把修改写入文件。接下来你可以让它运行测试来验证修改是否正确。直接输入“跑一下相关测试”即可它会根据 CLAUDE.md 里配置的测试命令来执行。如果测试通过恭喜你完成了第一次代码修改。如果测试失败Claude Code 会读取错误信息尝试自动修复。我遇到过几次它第一次改得不对、但看到测试报错后自己修正的情况。这个自动修复循环是 Claude Code 比较实用的一个能力省去了手动复制错误信息再贴回去的步骤。验证通过后你可以用git diff查看所有变更确认没有意外修改。然后就可以正常提交了。你也可以直接让 Claude Code 帮你提交输入“提交这些变更commit message 写清楚改了什么”即可。4.4 用 Git 管理 AI 修改的安全策略用 Claude Code 改代码Git 是你的安全网。我的习惯是在让 Claude Code 做任何修改之前先确保当前工作区是干净的所有已完成的修改都已经提交。这样如果 AI 改出来的结果不满意一条git checkout .就能回到修改前的状态。如果任务比较复杂我会先开一个新分支让 Claude Code 在这个分支上操作。改完验证通过后再合并回主分支。这样做的好处是主分支始终保持稳定不会因为 AI 的中间状态受到影响。还有一个技巧在让 Claude Code 修改之前先用git stash把当前未提交的变更暂存起来。这样 AI 看到的是一个干净的代码库不会把你的临时修改和它的修改混在一起。等 AI 改完确认没问题后再git stash pop恢复你的临时修改。5. 常见问题与排查技巧实录5.1 安装与认证阶段的典型问题问题一npm install -g报权限错误。这是最常见的问题尤其是在 macOS 和 Linux 上。根本原因是 npm 的全局目录默认在系统目录下普通用户没有写权限。解决方案不是加sudo而是把 npm 全局目录改到用户目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global # 然后把 ~/.npm-global/bin 加入 PATH export PATH~/.npm-global/bin:$PATH问题二认证后仍然提示未授权。这种情况通常是本地缓存的认证信息过期了。可以尝试删除~/.claude目录下的认证缓存文件然后重新运行claude触发认证流程。如果问题依旧检查一下系统时间是否准确时间偏差过大会导致认证令牌验证失败。问题三WSL 里安装成功但 Windows 终端里找不到命令。这是因为 WSL 和 Windows 是两套独立的环境。如果你在 WSL 里安装的 Claude Code就必须在 WSL 终端里使用。想在 Windows 终端里用需要在 Windows 侧也安装一份或者配置 WSL 的 PATH 共享。5.2 代码修改过程中的异常处理问题一Claude Code 读取了错误的文件。如果你的项目里有多个同名文件或者文件路径比较深Claude Code 可能会找错文件。解决办法是在描述需求时给出完整路径或者在 CLAUDE.md 里写明关键文件的路径映射。问题二修改后测试跑不起来。先确认 CLAUDE.md 里的测试命令是否正确。如果命令没问题但测试仍然失败让 Claude Code 读取完整的错误输出它通常能定位到问题。如果它连续几次修复都失败建议手动介入把错误信息贴给它并给出更具体的指示。问题三变更范围超出预期。有时候你只让它改一个函数它却顺手改了其他文件。这通常是因为它在读取上下文时发现了“看起来相关”的代码。解决办法是在描述需求时加上明确的边界比如“只修改 src/utils/date.ts不要动其他文件”。5.3 提升 Claude Code 使用效率的独家技巧技巧一用/clear清理上下文。当一个任务完成后如果接下来要做一个完全不相关的任务先执行/clear清空对话历史。这样可以避免之前的上下文干扰新的任务也能减少 token 消耗。技巧二善用引用文件。在输入框里输入会触发文件搜索可以直接引用特定文件作为上下文。比如src/utils/date.ts 这个函数需要加一个参数这样 Claude Code 会优先读取你指定的文件而不是自己猜。技巧三把常用操作写成自定义命令。Claude Code 支持在.claude/commands/目录下定义自定义命令。比如你可以创建一个review.md里面写好代码审查的提示词之后只需要输入/review就能触发。这个功能适合团队统一操作规范。技巧四定期更新 CLAUDE.md。每次发现 Claude Code 做了不符合预期的行为就把对应的规范补进去。这个文件越完善Claude Code 的表现越稳定。我自己的 CLAUDE.md 从最初的十几行扩展到了现在的上百行覆盖了代码风格、目录结构、测试要求、提交规范等各个方面。技巧五用 Git 分支隔离实验性修改。如果想让 Claude Code 尝试一个不确定的方案先开一个新分支。改完如果效果好就合并效果不好直接删分支主分支完全不受影响。这个习惯让我在尝试激进重构时心里踏实很多。5.4 常见问题速查表问题现象可能原因解决方法安装时报权限错误npm 全局目录在系统路径下修改 npm prefix 到用户目录启动后提示未认证认证缓存过期或系统时间偏差清除缓存重新认证校准系统时间找不到 claude 命令全局 bin 目录不在 PATH 中将 npm 全局 bin 目录加入 PATH修改后测试失败测试命令配置错误或代码逻辑问题检查 CLAUDE.md 中的测试命令让 AI 读取完整错误输出变更范围超出预期上下文读取范围过大在需求中明确指定文件路径和修改边界Git 提交时换行符报错autocrlf 配置不当根据系统设置 core.autocrlfWSL 和 Windows 命令不互通两套独立环境在使用的环境中分别安装6. 把 Claude Code 融入日常开发流的几点体会用了一段时间之后我最大的感受是Claude Code 的价值不在于它一次能改多少代码而在于它把“读代码、改代码、验证代码”这个循环压缩到了一个对话里。以前改一个跨文件的函数签名需要手动搜索所有调用处、逐个修改、跑测试、看报错、再修现在只需要描述需求、审查 diff、确认测试通过。省下来的时间可以花在真正需要思考的地方比如架构设计和边界情况处理。CLAUDE.md 这个文件值得持续投入。我现在的习惯是每完成一个任务如果发现 Claude Code 有哪里做得不够好就花一分钟把对应的规范补进 CLAUDE.md。这个投入的回报率很高因为下一次它就会自动遵守不需要重复提醒。时间长了这个文件就成了项目的“开发规范文档”对新加入的团队成员也很有参考价值。Git 的使用习惯也需要相应调整。以前可能一天提交几次现在用 Claude Code 做修改时我会更频繁地提交——每完成一个小任务就提交一次。这样万一后续的修改出了问题回滚的粒度更细不会牵连已经完成的工作。分支策略上我倾向于给每个稍大的任务开一个独立分支让 Claude Code 在分支上自由发挥验证通过后再合并。最后分享一个小技巧如果你在团队里推广 Claude Code可以先让每个人在自己的分支上试用把各自遇到的坑和总结的技巧汇总起来形成团队共享的 CLAUDE.md 模板和自定义命令集。这样新成员上手时不需要从零摸索直接站在前人的经验上开始。