Soup's Blog

Back

Claude 使用技巧

Claude Code 配置文件详解与模型映射关系说明
}

Claude 使用技巧#

本文档介绍 Claude Code 的配置方法,特别是模型配置的相关说明。


Claude Code 工作模式#

Claude Code 支持三种工作模式,你可以根据任务需求灵活切换:

模式说明#

模式显示标识说明
Normal Mode默认(无特殊标识)正常执行模式,每次编辑需要确认
Auto-Accept Mode⏵⏵ accept edits on自动接受并应用编辑
Plan Mode⏸ plan mode on计划模式,先制定计划再执行

模式切换方法#

使用 Shift+Tab 在三种模式之间循环切换:

  1. Normal Mode(默认)→ 按 Shift+Tab → 进入 Auto-Accept Mode
  2. Auto-Accept Mode → 按 Shift+Tab → 进入 Plan Mode
  3. Plan Mode → 按 Shift+Tab → 回到 Normal Mode

各模式适用场景#

适用场景:

  • 日常对话和简单问答
  • 需要仔细审查每个修改的代码编辑
  • 不确定 Claude 会做什么,希望保持控制

特点:

  • 每个文件编辑都会询问是否应用
  • 最安全、可控性最强的模式

模型配置详解#

settings.json 中,你可以通过环境变量来配置 Claude 使用的模型。

配置示例#

{
  "env": {
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "doubao-seed-2.0-code",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "minimax-m2.5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "kimi-k2.5",
    "ANTHROPIC_MODEL": "glm-4.7"
  }
}
json

模型映射关系#

/models 选项环境变量说明
HaikuANTHROPIC_DEFAULT_HAIKU_MODEL快速、轻量级模型
SonnetANTHROPIC_DEFAULT_SONNET_MODEL平衡性能与质量
OpusANTHROPIC_DEFAULT_OPUS_MODEL最高质量的模型
默认模型ANTHROPIC_MODEL普通对话使用的模型

使用第三方 API#

你可以通过配置 ANTHROPIC_BASE_URL 来使用第三方 API 服务:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ark.cn-beijing.volces.com/api/coding"
  }
}
json

常用配置项#

配置项说明示例值
ANTHROPIC_MODEL默认使用的模型glm-4.7
ANTHROPIC_DEFAULT_HAIKU_MODELHaiku 模式使用的模型doubao-seed-2.0-code
ANTHROPIC_DEFAULT_SONNET_MODELSonnet 模式使用的模型kimi-k2.5
ANTHROPIC_DEFAULT_OPUS_MODELOpus 模式使用的模型minimax-m2.5
ANTHROPIC_BASE_URLAPI 基础 URLhttps://api.example.com
API_TIMEOUT_MSAPI 超时时间(毫秒)300000

会话管理#

Claude Code 支持会话恢复和管理,方便你在不同任务之间切换。

恢复会话#

启动 Claude Code 时,可以使用以下方式恢复会话:

命令说明
claude --continue继续当前目录中最近的对话
claude --resume打开对话选择器或按名称恢复
claude --from-pr 123恢复链接到特定拉取请求的会话

在活跃会话内切换#

在 Claude Code 交互模式中:

  • 使用 /resume 切换到不同的对话
  • 使用 /rename <name> 给当前会话起描述性名称

会话存储#

  • 会话按项目目录存储
  • /resume 选择器显示来自同一 git 存储库的会话,包括 worktrees
  • 给会话起描述性名称是处理多个任务时的最佳实践

撤销操作 (/rewind)#

Claude Code 提供了强大的 /rewind 功能,让你可以轻松撤销操作。

功能说明#

/rewind 让你可以回到之前的任意一个提示词节点,并选择:

  • 仅恢复代码 - 撤销代码修改但保留对话历史
  • 仅恢复对话 - 保留代码但回退对话状态
  • 两者同时回退 - 完全回到之前的状态

使用场景#

  • 刚让 Claude 修改代码就立刻后悔:“等等,还是撤销吧”
  • 想回到之前的某个决策点尝试不同方案
  • 批量撤销多个步骤而不需要逐个回退

使用方法#

  1. 输入 /rewind
  2. 选择要回退到的节点
  3. 选择回退范围(代码/对话/两者)
  4. 确认后即可恢复

常用快捷键#

掌握以下快捷键可以更高效地使用 Claude Code:

快捷键功能说明
Shift+Tab切换工作模式在 Normal、Auto-Accept、Plan 三种模式间循环切换
Ctrl+O切换详细输出开启/关闭详细的工具使用和执行情况显示
Ctrl+D(两次)退出 Claude Code第一次按确认,第二次按真正退出
Esc + Esc回退或总结将代码和/或对话恢复到上一个点,或从选定的消息进行总结
Alt+P(Windows/Linux)切换模型在不清除提示的情况下切换模型
自定义快捷键切换扩展思考启用或禁用扩展思考模式。首先运行 /terminal-setup 以启用此快捷键
Ctrl+K删除到行尾存储已删除的文本以供粘贴
Ctrl+U删除整行存储已删除的文本以供粘贴
Ctrl+Y粘贴已删除的文本粘贴用 Ctrl+KCtrl+U 删除的文本
Ctrl+R反向搜索历史提示词循环匹配历史提示词,按 Enter 运行,按 Tab 编辑后运行

快速命令#

快捷键功能说明
/(在开始输入)命令或 skill触发内置命令和 skills 的自动补全
!(在开始输入)Bash 模式直接运行命令并将执行输出添加到会话
@文件路径提及触发文件路径自动完成

常用命令#

命令功能说明
/cost查看成本统计显示当前会话的 API 调用成本统计信息

已弃用命令#

命令状态替代方案
review已弃用安装 code-review 插件:claude plugin install code-review@claude-code-marketplace

Hooks(钩子)功能#

Hooks 是在特定事件触发时自动执行的脚本,用于自定义工作流、拦截危险操作、自动格式化代码等。

核心工作流程#

事件触发 → Hook 拦截 → 执行自定义脚本 → 返回结果 → 继续/阻止操作
plaintext

Hook 事件类型#

事件类型触发时机典型用途
user-prompt-submit用户提交提示词前验证、修改提示词
tool-use工具使用前权限检查、参数验证
after-tool-use工具使用后日志记录、结果处理
permission-request权限请求时拦截危险操作
notification通知时发送告警、更新状态

配置方式#

方式一:通过 /hooks 命令#

# 在 Claude Code 中
/hooks
bash

方式二:通过配置文件#

~/.claude/settings.json 或项目 .claude/settings.json 中配置:

实战示例#

拦截危险命令#

发送通知#

{
  "hooks": {
    "task-complete-hook": {
      "command": "notify-send 'Claude Code' '任务已完成'",
      "enabled": true
    }
  }
}
json

自动格式化代码(PostToolUse Hook)#

来自创始人的实战经验 - 彻底消灭 CI 里的格式报错:

{
  "hooks": {
    "after-tool-use-hook": {
      "command": "bun run format || true",
      "enabled": true,
      "blocking": false
    }
  }
}
json

工作原理:

  1. 每次 Claude 使用 WriteEdit 工具后自动触发
  2. 运行格式化命令(这里是 bun run format
  3. || true 确保即使格式化失败也不阻塞流程
  4. 虽然 Claude 已经写得很规范,但这最后 10% 的自动化处理能彻底解决格式问题

效果:

  • ✅ CI 中不再有格式报错
  • ✅ 代码风格始终一致
  • ✅ 无需手动运行格式化
  • ✅ Git diff 更清晰

Plugin(插件)安装与使用#

什么是 Plugin?#

Plugins 是打包在一起的扩展集合,可以包含:

  • 5 个 Skills - 可复用的技能和工作流
  • 10 个斜杠命令 - 自定义命令
  • 3 个 MCP 服务器配置 - 外部服务集成
  • 2 个 SubAgent 定义 - 专用子代理
  • 若干 Hooks - 自动化钩子脚本

Plugins vs Skills#

特性SkillsPlugins
复杂度简单工作流完整功能套件
内容单一技能多种资源的集合
安装独立安装一次性安装多个资源
适用场景单一任务完整解决方案

插件市场来源#

来源地址说明
Anthropic Skillshttps://github.com/anthropics/skills官方 Skills 库,包含多个插件
Claude Code Marketplacehttps://claudecodemarketplaces.com插件市场目录
Awesome Claude Codehttps://awesomeclaude.ai/plugins社区插件精选

添加插件市场#

# 添加官方 Anthropic 插件市场
claude /plugin marketplace add anthropics/skills

# 添加本地插件市场
claude /plugin marketplace add ~/my-marketplace

# 浏览可用插件
claude /plugin
# 选择 "Browse Plugins" 查看完整列表
bash

常用官方插件#

# 文档处理插件套件
claude /plugin marketplace add anthropics/skills
claude /plugin install document-skills

# 前端开发插件
claude /plugin install frontend-design

# Git 工作流插件
claude /plugin install git-workflow
bash

安装 Plugin#

从市场安装#

claude plugin install <plugin-name>
bash

从本地安装#

# 安装本地插件
claude plugin install ./my-plugin

# 或使用完整路径
claude plugin install /path/to/my-plugin
bash

从 GitHub 安装#

# 直接从 GitHub 仓库安装
claude plugin install github:user/repo
bash

管理 Plugins#

查看已安装的插件#

claude /plugin
bash

浏览可用插件#

# 在 Claude Code 中输入
/plugin
# 选择 "Browse Plugins"
bash

卸载插件#

claude plugin uninstall <plugin-name>
bash

创建自定义 Plugin#

插件目录结构#

my-plugin/
├── plugin.json           # Plugin 配置
├── skills/              # Skills 目录
│   ├── skill1/
│   └── skill2/
├── commands/            # 自定义斜杠命令
│   └── my-command.md
├── mcp/                 # MCP 配置
│   └── mcp-config.json
├── agents/              # SubAgent 定义
│   └── agent1.json
└── hooks/               # Hook 脚本
    └── hook1.sh
plaintext

plugin.json 示例#


MCP Servers(模型上下文协议服务器)#

什么是 MCP?#

MCP (Model Context Protocol) 是 AI 的扩展接口标准,通过添加 MCP 服务器可以扩展 Claude Code 获取外部工具、资源、服务的能力。

核心架构#

Claude Code

MCP Client

MCP Server 1 ──┐
MCP Server 2 ───┼── 各种外部服务(GitHub API、Database、Browser 等)
MCP Server N ───┘
plaintext

常用 MCP 服务器#

MCP Server功能Star 数
chrome-devtools-mcp浏览器自动化,26 个工具18.5k
github-mcpGitHub API 集成10k+
postgres-mcpPostgreSQL 数据库操作5k+
filesystem-mcp增强文件系统操作3k+
web-search-mcp网络搜索功能2k+

MCP 安装方式#

方式一:命令行安装#

claude mcp add chrome-devtools npx chrome-devtools-mcp@latest
bash

方式二:配置文件安装#

编辑 ~/.claude/mcp.json

验证安装#

# 在 Claude Code 中
/mcp

# 或通过命令行
claude mcp list
claude mcp test chrome-devtools
bash

Chrome DevTools MCP 实战#

安装#

claude mcp add chrome-devtools npx chrome-devtools-mcp@latest
bash

使用示例#

在 Claude Code 中输入:

用 Chrome 浏览器打开 https://example.com,然后通过 chrome devtools mcp 完成以下任务:
1. 截取页面截图
2. 提取所有链接
3. 分析页面结构
4. 获取页面性能数据
plaintext

Subagents(子代理)#

什么是 Subagents?#

Subagents 是可以并行处理任务的独立 AI 代理,每个子代理拥有独立的 200K 上下文窗口,可以分配不同任务以提高效率。

核心理念#

把常用工作流看作自动化运行的”子智能体”,就像圣诞老人分派任务给精灵一样,每个子智能体专注于特定领域。

核心优势#

主代理 Claude Code

    ├─ 子代理1:代码审查
    ├─ 子代理2:测试编写
    ├─ 子代理3:文档生成
    └─ 子代理4:性能优化

并行处理 → 结果汇总
plaintext

Subagent 配置#

方式一:通过 /agents 命令#

claude /agents
bash

方式二:配置文件#

~/.claude/agents.json 或项目 .claude/agents.json 中配置:

Subagent 使用示例#

场景:完成一个功能开发#

# 主任务
我需要完成用户认证功能,请帮我:

1. 使用 code-reviewer agent 审查现有认证代码
2. 使用 test-writer agent 编写测试用例
3. 使用 doc-generator agent 更新 API 文档

这三个任务并行执行
bash

Claude Code 会自动:

  1. 创建三个独立的子代理
  2. 分配各自的上下文(200K × 3)
  3. 并行执行任务
  4. 汇总结果返回

实战子代理案例#

来自 Claude Code 创始人 Boris Cherny 的实际使用。

code-simplifier#

# .claude/agents/code-simplifier.md

你是一个代码精简专家。在 Claude 完成工作后,你的任务是:
1. 分析代码的复杂度和可读性
2. 识别可以简化的逻辑
3. 提供优化建议但保持功能不变
4. 优先考虑性能和可维护性
markdown

verify-app#

# .claude/agents/verify-app.md

你是一个端到端测试专家。你的任务是验证应用功能:
1. 运行完整的测试套件
2. 检查所有关键路径
3. 验证边界情况
4. 确保用户体验"感觉对劲"
5. 如果发现问题,提供详细的修复步骤
markdown

使用方式#

# 在 Claude Code 中
使用 code-simplifier agent 优化刚才写的代码

使用 verify-app agent 验证应用是否正常工作
bash

CLAUDE.md(项目记忆文件)#

什么是 CLAUDE.md?#

CLAUDE.md 是 Claude Code 的”项目记忆文件”,记录项目结构、构建命令、代码规范、架构决策等信息,让 Claude Code 快速理解项目上下文。

CLAUDE.md 的作用#

作用说明
📚 项目知识库记录项目架构、技术栈、依赖关系
🚀 快速启动自动读取,无需重复解释项目背景
🤝 团队协作共享项目规范,确保团队理解一致
🔄 持续迭代随项目演进自动更新

CLAUDE.md 最佳位置#

项目根目录/_CLAUDE.md          ← 全局项目配置
src/.claude/_CLAUDE.md        ← 模块级配置
.claude/_rules/auth.md        ← 特定规则
~/.claude/_CLAUDE.md          ← 用户级配置

优先级:特定规则 > 模块配置 > 项目配置 > 用户配置
plaintext

CLAUDE.md 示例#

完整示例#

# 项目名称: E-Commerce Platform

## 项目概述
这是一个基于 Node.js + React 的电商平台,支持商品管理、订单处理、支付集成等功能。

## 技术栈
- **前端:** React 18, TypeScript, Tailwind CSS, Redux Toolkit
- **后端:** Node.js 20, Express, TypeScript
- **数据库:** PostgreSQL 15, Redis 7
- **认证:** JWT, OAuth 2.0
- **测试:** Jest, Playwright
- **部署:** Docker, Kubernetes

## 项目结构
markdown

src/ ├── frontend/ # React 前端 │ ├── components/ # 可复用组件 │ ├── pages/ # 页面组件 │ ├── store/ # Redux store │ └── utils/ # 工具函数 ├── backend/ # Node.js 后端 │ ├── controllers/ # 控制器 │ ├── services/ # 业务逻辑 │ ├── models/ # 数据模型 │ └── routes/ # API 路由 └── shared/ # 共享代码 └── types/ # TypeScript 类型定义

构建与部署#

# 构建前端
npm run build:frontend

# 构建后端
npm run build:backend

# 构建所有
npm run build

# Docker 构建
docker-compose build
docker-compose up
bash

测试#

# 运行所有测试
npm test

# 前端单元测试
npm run test:frontend

# 后端单元测试
npm run test:backend

# E2E 测试
npm run test:e2e

# 测试覆盖率
npm run test:coverage
bash

代码质量#

# 代码格式化
npm run format

# 代码检查
npm run lint

# 类型检查
npm run type-check
bash

代码规范#

命名规范#

  • 文件名: kebab-case (user-profile.ts)
  • 组件名: PascalCase (UserProfile)
  • 函数/变量: camelCase (getUserProfile)
  • 常量: UPPER_SNAKE_CASE (API_BASE_URL)
  • 类型/接口: PascalCase (UserProfile)

Git 提交规范#

遵循 Conventional Commits:

  • feat: 新功能
  • fix: 修复 bug
  • docs: 文档更新
  • style: 代码格式调整
  • refactor: 代码重构
  • test: 测试相关
  • chore: 构建/工具链更新

代码审查清单#

  • 代码符合项目命名规范
  • 添加了必要的注释
  • 更新了相关文档
  • 编写了/更新了测试
  • 通过了所有测试
  • 通过了 lint 检查
  • 没有引入安全漏洞

架构决策#

ADR-001: 选择 TypeScript 而非 JavaScript#

日期: 2024-01-15 状态: 已接受 理由:

  • 类型安全减少运行时错误
  • 更好的 IDE 支持
  • 代码可维护性更高

ADR-002: 采用微服务架构#

日期: 2024-02-20 状态: 已接受 理由:

  • 便于团队并行开发
  • 独立部署和扩展
  • 技术栈灵活性

环境变量#

必需变量#

DATABASE_URL=postgresql://...
REDIS_URL=redis://...
JWT_SECRET=your-secret-key
API_BASE_URL=https://api.example.com
bash

可选变量#

LOG_LEVEL=info
NODE_ENV=development
PORT=3000
bash

常见问题#

Q: 如何添加新的 API 端点?#

A:

  1. backend/routes/ 创建路由文件
  2. backend/controllers/ 创建控制器
  3. backend/services/ 实现业务逻辑
  4. 添加测试用例
  5. 更新 API 文档

Q: 如何调试前端状态管理问题?#

A:

  1. 使用 Redux DevTools 浏览器扩展
  2. src/frontend/store/ 添加日志
  3. 检查 action 和 reducer 逻辑

重要注意事项#

  1. 安全: 永远不要在代码中硬编码密钥或敏感信息
  2. 性能: 大数据查询必须使用分页
  3. 测试: 所有新功能必须包含测试
  4. 文档: API 变更必须更新文档
  5. 兼容性: 确保向后兼容,使用版本控制

相关资源#


### 生成 CLAUDE.md 的方式

####方式一:使用 `/init` 命令

```bash
# 在项目根目录
claude /init
plaintext

Claude Code 会自动扫描项目并生成初始 CLAUDE.md,包含:

  • 构建和测试命令
  • 目录结构说明
  • 代码规范和架构决策
  • 技术栈信息

方式二:手动创建#

# 创建基础文件
touch CLAUDE.md

# 让 Claude Code 帮助生成
claude "请根据当前项目结构生成 CLAUDE.md 文件"
bash

方式三:模块化规则#

# 在 .claude/rules/ 目录创建多个规则文件
.claude/rules/
├── auth.md          # 认证相关规则
├── database.md      # 数据库相关规则
├── api.md          # API 设计规范
└── testing.md      # 测试规范
bash

方式四:Memory Updates - 动态更新记忆#

# 直接告诉 Claude 更新知识
Update CLAUDE.md: always use bun instead of npm
Update CLAUDE.md: 不要使用 enum,改用 string union

# Claude 会自动把新知识写入记忆文件,无需手动编辑
bash

CLAUDE.md 的 AI 进化机制#

来自 Claude Code 创始人团队的实战经验:

核心理念#

让 Claude 在 Code Review 中自我迭代,越用越聪明

实战流程#

  1. 在 PR 中发现问题
  2. 让 Claude 记住教训
  3. Claude 自动更新
  4. 团队共同维护

示例:

# 在 GitHub PR 评论中
@claude 这里的代码使用了 enum,但我们项目规范要求使用 string union,请修复

# 在 PR 中直接告诉 Claude
@claude 请把这次的教训写入 CLAUDE.md:不要使用 enum,改用 string union

# Claude 会在 CLAUDE.md 中添加
## 代码规范更新 (2026-01-03)

### Enum vs String Union
- 不要使用 enum
- 改用 string union
- 理由:更好的类型推断和 Tree-shaking
bash

团队共同维护#

# 将 CLAUDE.md 签入 Git
git add CLAUDE.md
git commit -m "docs: 更新 CLAUDE.md 规范"

# 整个团队共享这份"行为准则"
bash

价值体现#

  • 🧠 集体智慧: 每个团队成员的反馈都让 AI 更聪明
  • 🔄 持续进化: Claude 不会重复犯同样的错误
  • 📚 知识沉淀: 项目规范自动文档化
  • 🤝 团队协作: 统一的 AI 助手理解团队偏好

实际案例#


Headless 模式(无头模式)#

什么是 Headless 模式?#

Headless 模式是非交互式运行方式,输出结果直接流向标准输出,可集成到 Shell 脚本或 CI/CD 流程中。

使用场景#

场景示例
🔄 CI/CD 集成自动化代码审查
📜 脚本自动化批量处理任务
🔍 快速分析不需要交互的代码分析
📊 报告生成自动生成文档

Headless 模式使用#

基本用法#

# 从管道输入
git diff | claude -p "解释这些更改"

# 从文件输入
cat file.txt | claude -p "总结这个文件"

# 直接指定
claude -p "检查代码质量" < src/main.js
bash

CI/CD 集成示例#

脚本自动化示例#


参考资源#

官方文档#

开发指南参考博客#