AI浪潮下，大家一定都听说过Claude Code。这玩意儿可不是什么“会写点代码的聊天机器人”，它更像是一个能跟你肩并肩干活的编程伙伴。用好了，不仅能让你自己效率翻倍，还能帮整个团队把工程规范拉整齐。本文打算从一个比较实用的角度出发，聊聊怎么用好它。

一、先统一一个心智：把 Claude Code 当“快速实习生”

先明确一个核心认知，这决定了你后续怎么跟它打交道。

1. 不要把 Claude 当“答案机”

更好的定位是什么？把它当做一个非常能干、记忆力好得吓人、但需要你给出清晰任务的实习生。

这个定位会直接影响你写指令的方式和验收结果的态度：

• 不要指望随便一问，就能得到完美答案
• 得像带新人一样：给目标、划边界、交代清楚上下文，然后让它去干具体的活

2. 你负责“要什么”，它负责“怎么做”

• 你这边要操心的是：
  • 业务目标：到底要实现什么功能、解决什么问题
  • 约束条件：比如架构怎么分层、不能跨层调用、安全方面的要求
  • 编码风格与规范：命名规则、日志怎么写、DTO字段用什么类型
• 它那边负责的是：
  • 自动去找文件、读代码、分析依赖关系
  • 在plan模式下设计出实现方案
  • 动手改代码、跑测试、甚至帮你写提交信息的草稿

3. 一定要配合 Git 使用

• 动手做大改动之前：先自己 git commit 一次，给工作区留个能回滚的“安全基线”
• Claude 改完一轮：自己再用 git diff 快速扫一眼改动
• 如果改得不好：直接 git checkout 回滚，然后重新整理指令让它再试一次

二、三步完成“从 0 到能干活”的配置

1. 安装 + 验证：两个关键点

这里有两个容易踩坑的地方，值得注意：

• Node 版本必须 ≥ 18

node --version # 确认版本号，推荐 18+ 或 20+

• 安装完成后要立刻自检

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

如果还用了 Claude Code Router（CCR），别忘了安装并登录：

npm install -g @musistudio/claude-code-router@1.0.33 ccr --version ccr login

2. 首次认证：网络环境要处理好

然后在项目根目录启动：

cd your-project-directory claude

按提示完成浏览器 OAuth 认证即可。

3. 必做的项目初始化：/init + CLAUDE.md

在每个项目第一次使用 Claude Code 时，建议由一个人执行：

cd your-project-directory claude /init

这个命令会自动完成两件事：

• 生成项目级 CLAUDE.md 文件，里面会包含：
  • 项目概述（技术栈、架构、分层）
  • 代码风格约定（lint、格式化、命名习惯）
  • 测试策略与覆盖率目标
  • 部署流程与分支策略
• 创建 .claude/ 目录，用来保存项目自定义命令和配置

之后，所有人只要在这个仓库里启动 Claude Code，它就自动按这套规则来行事。

三、日常使用的“高性价比组合拳”

1. 优先使用 plan 模式：先看计划再动手

Claude Code 提供了三种工作模式：

1. default：默认模式，每次操作前都要你确认
2. plan：先生成一份完整计划，然后你决定哪些步骤可以执行（强烈推荐）
3. acceptEdits：自动接受所有编辑，适用于非常熟悉的项目加上小范围改动

实用的启动方式：

# 在项目中启动，并默认使用 plan 模式 claude --permission-mode plan # 继续上次的会话 claude --permission-mode plan --continue

使用建议：

• 复杂的改动、涉及多个文件或多个模块的任务，一律用 plan 模式
• 你只需要做一件事：审核这份计划是否与你的想法一致。如果不对，就在计划阶段要求它调整

2. 熟悉后再启用 bypass 模式提速

对于已经十分熟悉的项目，可以大胆启用“跳过权限确认”的模式：

claude --dangerously-skip-permissions --permission-mode plan --continue

适用场景：

• 批量重构同类代码，比如统一修改接口签名、DTO字段
• 自动生成大量重复模式的样板代码

前提条件：

• 一定要有 Git 做兜底，确保工作区变更可控
• 对项目结构和影响范围足够熟悉

3. 会管理“上下文”，Claude 才能一直保持清醒

长对话中，Claude 跟人一样，会被大量历史消息拖累，回答开始跑偏。有两个命令非常关键：

/clear # 完全清空当前会话上下文 /compact # 压缩上下文，只保留关键信息

经验法则：

• 从“开发功能”切换到“排查bug”，建议先 /clear
• 同一任务聊了很久，回答开始变得奇怪，就 /compact 一下
• 当你自己都需要往上翻很多页才能想起上下文时，就该用 /compact 或 /clear 了

4. 会写指令，比会写代码还重要

糟糕的指令：

修复这个 bug

高质量的指令：

分析登录组件中的错误处理逻辑，修复用户输入无效凭据时没有显示错误消息的问题。请确保：1. 错误消息对用户友好（不暴露技术细节）2. 不暴露敏感信息（不要区分是用户名错还是密码错）3. 在后端增加合适的日志记录，方便后续排查4. 使用项目现有的日志工具类，不要新引入第三方库

跟 AI 合作，有一个简单原则：越“啰嗦”越高效。

5. 善用 @ 引用，让 Claude 精准看对地方

在 Claude Code 中，@ 就是你的“激光笔”，用来精确指定需要查看的文件或资源：

@src/modules/user/UserService.ts @frontend/src/pages/LoginPage.tsx @logs/auth-error-2025-08-01.log @docs/sequence-diagram.png

典型用法：

• 查 bug：
  请分析 @auth-error-2025-08-01.log 中的错误，并结合 @UserService.ts 找出根因并给出修复方案
• 做重构：
  请重构 @UserForm.tsx，将其拆分为更小的组件，保持对外 props 接口不变

这样一来，Claude 就不需要在整个仓库里“乱跑”了，可以快速聚焦到你真正关心的地方。

6. 模型切换策略：日常 Sonnet，大活儿 Opus

在会话中可以随时切换模型：

/model # 查看当前和可用模型 /model opus # 切到 Opus（复杂架构、深度分析） /model sonnet # 切回 Sonnet（日常开发使用）

启动时指定模型：

claude --model opus

简单策略：

• 日常开发、单文件改动、小功能实现 → Sonnet
• 复杂架构讨论、跨模块重构、性能优化专项 → Opus

四、把项目规则“喂进” CLAUDE.md，形成团队统一习惯

项目根目录下的 CLAUDE.md，就是整个团队与 Claude 协作的“宪法”。你可以在里面写明各种关键规则，然后善加利用。

1. 语言与文档规范要写在最前面

典型约定：

• 所有对话和文档都使用中文
• 文档统一使用 Markdown 格式

效果就是：任何人在这个仓库中启动 Claude Code，默认行为就是中文输出，并以 Markdown 组织内容。

2. 把“工程约束”写死在 CLAUDE.md

例如：

• Service 类不单独建接口（除非架构文档另有要求）
• 少量代码不建议过度拆成私有方法
• 除 File 操作外，通常不需要手写 try { ... } catch { ... }
• DTO 中的长数值类型字段（如登记序号、纳税人序号）使用 String

对 Claude 下指令时，直接引用这些规则：

按照本项目 CLAUDE.md 中的规范：1. 本次新增的 Service 直接使用类实现，不再单独定义接口2. 所有新增 DTO 中涉及xxx等长整型编号字段，统一使用 String 类型3. 除 File 相关操作外，不需要显式 try/catch请在工xxxx模块中，新增一个查询接口实现，并补齐必要的 DTO 与单元测试。

Claude 会自动对齐这些约定，减少偏差和返工。

3. 分层架构与技术规范：用规则“防跑偏”

CLAUDE.md 中已经指定了多个规范文件：

• architecture.mdc：分层架构、调用关系、职责分工
• channel.mdc：项目规范
• app.mdc：APP 工程规范
• spec.mdc等：特定工程规范
• dcommon.mdc：通用能力、缓存规范

给 Claude 下达任务时，可以明确提出要求：

• 架构边界：
  必须严格遵守 architecture.mdc 的分层规范，禁止跨层调用
• 缓存：
  所有缓存使用应遵守 ehcache.mdc，不缓存个人和单位敏感数据
• 数据库访问：
  涉及原生 SQL 的部分统一通过xxxx执行
• 通用组件：
  优先使用 common.mdc 中已有的工具类、常量、枚举和 DTO

这样一来，Claude 生成的代码自然就会“长得像团队原有的代码”。

五、用 MCP 把 Claude 变成“多功能瑞士军刀”

1. 本地文件系统（强烈推荐）

claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects ~/Desktop

作用：

• 让 Claude 直接访问这些目录下的文件
• 它自己就可以打开文件、修改、保存，不需要你手动复制粘贴代码

2. GitHub 集成（有云仓库就装）

claude mcp add github -s user -e GITHUB_TOKEN=your-token -- npx -y @modelcontextprotocol/server-github

典型用途：

• 让 Claude 帮你分析 PR、生成 review 意见
• 自动关联 issue 与对应的代码位置
• 批量梳理仓库中某类代码异味

3. 浏览器、数据库、Fetch 等按需开启

• Puppeteer：自动化网页操作、UI 测试、简单爬虫
• Postgres：直接连接数据库做查询分析
• Fetch 工具：让 Claude 代表你去调用各种 REST API

建议遇到实际需求再添加，并在项目 CLAUDE.md 中记录：

• MCP 服务器名称
• 使用场景（测试环境、预发环境、生产只读等）
• 安全注意事项

4. 作用域选择：local / user / project 怎么选？

• local：仅当前项目目录可用，适合项目私有的 MCP 配置
• user：当前用户所有项目可用，适合个人常用工具（文件系统、时间、搜索引擎等）
• project：写入 .mcp.json，整个团队共享，适合团队统一使用的 MCP 服务器（如统一内部服务、日志平台等）

记住一句话：团队工具用 project，个人习惯用 user，特殊项目用 local。

六、常见坑

1. 安装与权限相关问题

• Node 版本不对 → 先 node --version 检查
• 全局安装权限不足 → 给 npm 设置用户目录前缀，而不是一味用 sudo：

npm config set prefix ~/.npm-global echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc

2. MCP 名称与路径问题

• 报错中提到 tools.custom.name pattern → MCP 名称中不要包含空格和特殊符号，只用字母数字和 _、-
• Windows 路径报错 → 使用 / 或 \，避免混用 C:Users... 这种形式

3. Claude 回答开始“胡说八道”

• 立刻 /clear 或 /compact 清理上下文
• 把关键代码、日志文件用 @ 引用清楚
• 用一段简明扼要的新指令重新描述问题和目标

4. 会话成本与性能问题

• 使用 /cost 查看当前会话的耗费：

/cost

• 避免长时间在同一会话里堆叠无关话题
• 使用 /clear / /compact 减少上下文长度
• 做大型文件分析时，尽量只引用必要的片段或具体文件，而不是让它“看整个仓库”

七、团队协作视角：让整个项目都“会用 Claude”

1. 统一 /init，让 Claude 读同一本“项目说明书”

团队约定：

• 新项目创建后，指定负责人执行一次 /init
• 完整检查自动生成的 CLAUDE.md，并补充：
  • 项目背景与业务概述
  • 技术栈与分层架构说明
  • 与现有 architecture.mdc、channel.mdc 等文档的关系
  • 项目特有的命名规则、日志规范、异常处理策略
• 把 CLAUDE.md 和 .claude/ 目录提交到版本库

之后，所有人在这项目中使用 Claude Code 时，就都在同一套规则下协同了。

2. 用自定义命令固化团队工作流

在 .claude/commands 中编写团队统一的工作流，比如 feature-workflow.md：

# 新功能开发工作流（团队统一用法） 请严格按照以下步骤执行：1. 基于当前分支，创建一个新的特性分支，命名规则：feature-<模块拼音首字母>-<简短描述> 示例：feature-search2. 通读与本需求相关的 @业务文档 和 @需求文档（如存在）3. 使用 /overview 和 /tree 快速了解相关模块结构4. 先编写或完善测试用例（单元测试/集成测试），采用 TDD 流程5. 按照 CLAUDE.md 中的分层规范设计改动，避免跨层调用6. 所有 DTO 中可能为长整型的编号字段一律使用 String 表示7. 实现完成后运行项目约定的测试命令（如 npm test / mvn test 等）8. 测试通过后生成一次提交，提交信息遵循团队约定格式9. 在必要时更新相关文档（README、API 文档等）

之后只要在会话中输入：

/feature-workflow

就能让 Claude 自动按这套流程来指导开发。

3. 利用项目 ID 信息，让 Claude 更懂业务模块

如果已经在规则中明确了各中心的项目 ID，可以在 CLAUDE.md 中补充说明，并在指令中明确目标模块：

本次改动仅针对xxxx中心（项目ID 1234），请：1. 在现有架构下实现 XX 功能，不与其他中心逻辑耦合2. 严格遵守 architecture.mdc 的分层规范3. DTO 中新增的长整型编号字段一律使用 String4. 结合 common.mdc 中已有 DTO 和工具类，避免重复造轮子

这样 Claude 会自然以“模块”为单位来考虑影响范围。

八、调试 & 故障排查：把 Claude 当“日志分析助手”

1. 标准化 bug 排查流程模版

可以将下面这段写成命令 /debug-bug，或者在需要时直接粘贴使用：

我有一个 bug 需要排查，请按以下步骤进行：1. 先通读 @错误日志 文件，概括异常信息和出现频次2. 结合 @相关代码文件，列出 2~3 个可能的原因假设3. 为每个假设设计一个最小验证步骤（如增加日志、构造特定输入、增加断言等）4. 按优先级逐一验证，并在需要额外信息时明确告诉我5. 在确认原因后，给出最小修复方案，并说明可能影响的上下游模块6. 帮我生成一段简要的 bug 修复说明，便于记录在提交信息或缺陷单中

这样每次调试都能保持相对固定的“套路”，避免遗漏关键环节。

2. 巧用 /mcp + 文件系统 / 日志服务器

执行：

/mcp

可以查看当前已配置的 MCP 服务器。如果挂载了日志目录或远程日志服务，那么可以让 Claude：

• 自动打开最近的错误日志文件
• 筛选指定时间段或关键字
• 按错误类型聚合，帮你梳理出“哪类问题最常见”

3. 三步排查 Claude 本身的异常表现

当你感觉 Claude 的表现“不太对劲”时，可以按以下顺序排查：

1. 查配置：

claude --version claude --help

2. 开调试（特别是 MCP 问题）：

claude --mcp-debug

3. 看日志：
   • macOS: ~/Library/Logs/claude-code/
   • Linux: ~/.local/share/claude-code/logs/
   • Windows: %APPDATA%claude-codelogs

九、进阶：让 Claude 参与设计与重构，而不仅仅是“写代码”

1. 先让 Claude 画出你当前的“系统地图”

当你觉得系统结构有些“模糊”时，可以先让 Claude 做一次现状分析：

请你基于本项目代码，完成一次架构现状盘点：1. 使用 /overview 和 /tree 了解项目的整体结构2. 用文字总结当前的分层架构现状（Controller / Service / Repository / DTO 等）3. 指出目前存在的明显架构违规现象（如跨层调用、大量工具类直接操作数据库等）4. 结合 CLAUDE.md 与 architecture.mdc 中的规范，列出 3 个最需要重点重构的区域，并说明理由

这一步的实质，是让 Claude 帮你生成一份“技术债清单”。

2. 用渐进重构方案，而不是“一键重构全世界”

拿到问题清单后，可以要求 Claude 设计一个可落地的重构路线：

针对你刚才列出的三个重构重点，请遵守以下约束：1. 重构必须分阶段进行，每个阶段尽量只影响有限模块2. 每个阶段结束时，项目必须可编译、测试可通过3. 优先处理技术债高且变更频率高的模块4. 每个阶段写出清晰的变更说明和风险点，便于代码评审和回滚请设计一个最多 3 个阶段的重构方案，每个阶段分别说明：- 目标- 主要改动点- 风险与回滚策略

确认方案后，再让它用 plan 模式逐步实施每个阶段。

3. 性能优化：让 Claude 当“性能顾问”，别一上来就乱改

性能问题最忌讳“头脑一热就动手改”。可以先让 Claude 从代码角度做“假设 + 验证”：

目前在以下场景存在性能问题（简单描述场景和接口）：请按以下步骤协助我：1. 结合 @Controller.ts, @Service.ts, @Repository.ts 等相关代码，从代码结构上猜测可能的性能瓶颈（列出 2~3 个）2. 对每个瓶颈给出验证方式（需要哪些日志、监控指标或压测）3. 推荐应该增加哪些监控点（响应时间、错误率等）4. 在不改变业务逻辑的前提下，列出 2~3 个低风险、高收益的优化建议

然后再选择其中一两个建议，交给它具体实现并补充测试。

十、把这些“技巧”固化进项目：一个简单落地动作

最后，建议在你当前仓库的 CLAUDE.md 末尾增加一个小节，把这些核心原则都写进去：

## Claude Code 使用建议（项目内约定）1. 所有开发、调试、重构对话默认使用 plan 模式，重要改动前务必先 review 计划。2. 涉及本项目代码的所有对话，必须遵守本文件及相关 *.mdc 架构与规范文档，禁止跨层调用。3. DTO 中所有涉及长整型编号的字段一律使用 String 类型表示。4. 除 File 操作外，不额外引入 try/catch，异常处理遵循既有架构规范。5. 使用 /clear 和 /compact 管理对话上下文，避免长会话导致回答偏移。6. 优先复用 common.mdc 中的工具类、常量、枚举和 DTO，避免重复造轮子。7. 所有大改动必须在 Git 干净工作区基础上进行，改动完成后由人工使用 git diff 做最终审核。8. 建议通过 .claude/commands 维护团队统一工作流命令（如 /feature-workflow, /review-me, /debug-bug）。