Claude Code系列 -- Claude Code实战手记

Claude Code实战手记，持续更新实践和技巧

Posted Mar 4, 2026 Updated Apr 12, 2026

By xiaodongQ

views 29 min read

1. 引言

Claude Code实战手记，持续更新实践和技巧。

2. 安装和基本使用

基本安装和配置就不单独说了，基本步骤：通过npm install -g @anthropic-ai/claude-code安装（可设置一下国内镜像源） -> 配置API。具体步骤可见：Claude Code安装和使用。

执行claude即可执行：

╭─── Claude Code v2.1.63 ──────────────────────────────────────────────────────────────────────────────────╮
│                                      │ Tips for getting started                                          │
│             Welcome back!            │ Run /init to create a CLAUDE.md file with instructions for Claude │
│                                      │ ───────────────────────────────────────────────────────────────── │
│                ▐▛███▜▌               │ Recent activity                                                   │
│               ▝▜█████▛▘              │ No recent activity                                                │
│                 ▘▘ ▝▝                │                                                                   │
│                                      │                                                                   │
│   qwen3.5-plus · API Usage Billing   │                                                                   │
│                /home                 │                                                                   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯

  /model to try Opus 4.6

──────────────────────────────────────────────────────────────────────────────────────────
❯  

3. 快捷键和技巧

可参考（经常翻翻）：Claude Code 常用技巧

3.1. 快捷键和命令

快捷键：

Shift + Tab快捷键循环切换权限模式
↑ / ↓ 浏览命令历史
Ctrl + A 跳转到行首
Ctrl + E 跳转到行尾
\ 行尾输入\后可多行输入，回车才发送所有消息
输入! 执行命令

命令：

/init：在项目根目录生成 CLAUDE.md 文件，用于定义项目级指令和上下文。
- 会记录：常用的 bash 命令、核心代码文件、实用函数、代码风格信息
- 另外可以手动在CLAUDE.md里面，用markdown语法增加项目特定规则，用不同级别的#增加相应小结进行规则说明
/vim 切换vim模式编辑
/status：查看当前模型、API Key、Base URL 等配置状态
/clear：清除对话历史，开始全新对话
/plan：进入规划模式，仅分析和讨论方案，不修改代码
/compact：压缩对话历史，释放上下文窗口空间
/config：打开配置菜单，可设置语言、主题等

3.2. 权限模式

跟Claude Code对话时，可以用Shift + Tab快捷键来循环切换权限模式：计划模式、自动接受模式。

也可以在配置文件.claude/settings.json里永久设置为默认，这里自动开启接受编辑模式：

  
"permissions": {
    "defaultMode": "acceptEdits"
}

启用自动权限模式，则可：claude --dangerously-skip-permissions，为了方便可以在bashrc里设置一个别名：alias claudecc="claude --dangerously-skip-permissions"，但基于安全考虑，root用户下还是会提示是否接受。

精细控制权限：我不想每次人工来点击一次接受修改，所以权限进行了下述修改，并安装了开源社区的cc-safety-net插件：npm install -g cc-safety-net，然后在 .claude/settings.json 中启用。

内置数百种危险模式识别
会区分rm -rf /tmp/cache（允许）vs rm -rf /（阻止）

  
{
  "permissions": {
    "mode": "acceptEdits",
    "allow": ["Bash(*)", "Edit(*)", "Write(*)"],
    "deny": [
      "Bash(rm -rf / *)",
      "Bash(git push --force)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "npx -y cc-safety-net",
            "timeoutSec": 15
          }
        ]
      }
    ]
  }
}

3.3. 全局记忆设置

/memory设置记忆，可以选择全局级别还是当前项目级别。选择后会自动打开相应的CLAUDE.md文件，比如设置中文环境，增加：与用户交流始终使用中文。；也可以之间vim编辑相应CLAUDE.md文件。

4. MCP、Skill和插件

4.1. 基本说明

MCP (Model Context Protocol) 工具是 Claude Code 的扩展功能，可以为其添加各种第三方服务的能力。Claude Code 自带基础联网搜索功能，但通过 MCP 工具可以实现深度搜索、地图服务、天气查询等高级功能。

Claude Code 支持通过 MCP 和 Skills 扩展自身能力，例如调用联网搜索获取实时信息、使用图片理解 Skill 分析图像内容等。

MCP：安装成熟的 MCP Server，连接外部服务。例如：添加联网搜索MCP。
Skills：编写详细的 Skill 描述文案。Claude 决定是否调用该工具，取决于对该工具用途的定义。例如：添加视觉理解能力Skill。
Skills vs MCP：Skills 教会 Claude “怎么做”（工作流知识），MCP 给 Claude“做的工具”（外部接口）。两者互补，Skills 也可集成外部接口。

4.2. Skills

Agent Skills（智能体技能）是将专业知识、工作流规范固化为可复用资产的核心工具。本质上是一个模块化的 Markdown 文件，能教会 AI 工具（如 Claude、GitHub Copilot、Cursor 等）执行特定任务，且支持自动触发、团队共享与工程化管理，彻底告别重复的提示词输入。

Agent Skills 的关键是渐进式披露，分三层加载：

层级 1：技能发现 – AI 先读取所有技能的元数据（name 和 description），判断任务是否相关，这些元数据始终在系统提示中
层级 2：加载核心指令 – 如果相关，AI 自动读取 SKILL.md 的正文内容，获取详细指导
层级 3：加载资源文件 – 只在需要时读取额外文件（如脚本、示例），或通过工具执行脚本

4.2.1. 手动添加Skill示例

这里添加一份Skill，添加视觉理解能力（部分模型可能已经默认具备视觉能力了，如qwen3.5-plus，这里假设切换的模型不支持）。

1、在项目目录（按需看是否要全局目录）的.claude目录中，新建skills/image-analyzer目录，image-analyzer即Skill名
2、在该目录下创建SKILL.md文件，并写入下述内容

  
---
name: image-analyzer
description: 帮助没有视觉能力的模型进行图像理解。当需要分析图像内容、提取图片中的信息、文字、界面元素，或理解截图、图表、架构图等任何视觉内容时，使用此技能，传入图片路径即可获得描述信息。
model: qwen3.5-plus
---
qwen3.5-plus具有视觉理解能力，请直接使用qwen3.5-plus模型进行图片理解。

目录结构如下（或放全局里），claude重新进入，/skills即可看到：image-analyzer · ~26 description tokens

  
[root@xdlinux ➜ skills ]$ pwd
/root/.claude/skills
[root@xdlinux ➜ skills ]$ tree
.
└── image-analyzer
    └── SKILL.md

删除Skills：直接删除相应文件，rm -rf /root/.claude/skills/<skill-name>

参考自：百炼 – 添加视觉理解能力

4.2.2. Skills编写最佳实践

为避免上下文膨胀，推荐目录结构：

核心规则 → SKILL.md
- 在 SKILL.md 中引用其他文件或者目录，比如md里说明：
  - 查看示例 commit：./examples/good-commit.txt
  - 运行脚本：使用工具执行 ./scripts/process.py
详细资料 → 单独文件
实用逻辑 → 脚本执行（不加载）

my-skill/
├── SKILL.md
├── reference.md   # 存放参考文档，也可以增加一个 references 目录
├── examples.md    # 存放示例文件，也可以增加一个 examples 目录
└── scripts/
    └── helper.py

Skills 存放在 ~/.claude/skills/（个人全局）或项目目录下的 .claude/skills/（项目专用）。

创建Skill后，Claude执行任务就会扫描已安装的 Skills，发现你的请求有涉及就会调用。

4.3. MCP

查看当前已安装的MCP工具：claude mcp list

手动添加MCP示例：

在MCP广场找到MCP（暂时用阿里百炼里的MCP），开通并添加： claude mcp add WebSearch https://dashscope.aliyuncs.com/api/v1/mcps/WebSearch/mcp -t http -H "Authorization: Bearer sk-sp-xxxxxxxxxxxx(相应的API Key)"

  
[root@xdlinux ➜ tmpdir ]$ claude mcp add WebSearch https://dashscope.aliyuncs.com/api/v1/mcps/WebSearch/mcp -t http -H "Authorization: Bearer sk-sp-1xxxxxxxxxxxxxxxxxxxx"
Added HTTP MCP server WebSearch with URL: https://dashscope.aliyuncs.com/api/v1/mcps/WebSearch/mcp to local config
Headers: {
  "Authorization": "Bearer sk-sp-1xxxxxxxxxxxxxxxxxxxxx"
}
File modified: /root/.claude.json [project: /home/workspace/tmpdir]

/root/.claude.json文件里，可以看到：

  
    "/home/workspace/tmpdir": {
      "allowedTools": [],
      "mcpContextUris": [],
      "mcpServers": {
        "WebSearch": {
          "type": "http",
          "url": "https://dashscope.aliyuncs.com/api/v1/mcps/WebSearch/mcp",
          "headers": {
            "Authorization": "Bearer sk-sp-1xxxxxxxxxxxxxxxxxxx"
          }
        }
      },

删除MCP：claude mcp remove WebSearch

参考自：百炼 – 添加联网搜索MCP

4.4. 插件

插件（Plugin）是 Claude Code 中最高级别的扩展机制，用于将command、agent、Skills、钩子、MCP、LSP 等能力打包、版本化、共享和分发。

插件 = 一组可复用的 Claude Code 扩展能力集合

插件的核心目标只有一个：让 Claude Code 的能力像工具箱”一样被复用，而不是每个项目重复配置。实现 “一次打包，多环境使用”

什么时候用独立配置？
- 个人使用、单项目、快速实验、想要简短命令名（如 /review）
什么时候用插件？
- 团队共享、跨项目、版本化控制
最佳实践：先在 .claude/ 中迭代 → 稳定后打包为插件

可见：Claude Code插件

4.4.1. 插件管理命令

  
/plugin                # 打开插件管理器
/plugin install         # 安装插件
/plugin uninstall       # 卸载
/plugin enable/disable  # 启用 / 禁用（回车后会进入选择页面）
/plugin marketplace add # 添加市场
/plugin marketplace rm  # 移除市场

添加插件：

在线方式：/plugin marketplace add xxx，而后/plugin install xxx
离线方式：以claude-hud为例
- 1、克隆 claude-hud 仓库
  - git clone https://github.com/jarrodwatts/claude-hud.git
- 2、添加仓库：/plugin marketplace add 本地路径/claude-hud
- 3、安装：/plugin install claude-hud

下面是几个推荐插件。

4.4.2. Superpowers 插件

Superpowers 是一个 Claude Code 增强插件，安装后 AI 会自动获得一套完整的工作流技能——从需求分析、方案设计、代码编写到测试验证，全程自主完成。具体见：Superpowers 插件

  
# 1. 注册插件市场
/plugin marketplace add obra/superpowers-marketplace

# 2. 从市场安装 Superpowers
/plugin install superpowers@superpowers-marketplace

使用方式示例：

/brainstorming 描述你想做的事情

Superpowers 会自动：

分析需求 — 和你确认功能细节和技术选型
制定计划 — 拆分任务，设计实现方案
编写代码 — 逐步实现每个功能模块
测试验证 — 运行测试确保代码正确
代码审查 — 自动检查代码质量

整个过程中 AI 会在关键节点询问你的意见，你只需要回答即可。

4.4.3. claude-hud

提供实时会话状态监控（Token 用量、上下文进度、工具调用状态等）

除了在线安装，这里也补充下离线方式，见 claude-hud-offline-install

  
# 1. 添加插件市场源（首次安装）
# 作用：将 claude-hud 的 GitHub 仓库添加为插件市场源
/plugin marketplace add jarrodwatts/claude-hud

# 2. 安装插件
/plugin install claude-hud

# 3. 初始化 HUD 配置
# 自动配置状态栏，启用 HUD 显示
/claude-hud:setup
# 会自动进行配置，执行后如下：
    # 我来帮你配置 claude-hud。首先让我检测一下当前的安装状态。
    # ● Bash(CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"   CACHE_EXISTS=$(ls -d "$CLAUDE_DIR/plugins/cache/claude-hud" 2>/dev/null && echo "YES" || echo "NO")…)
    #   ⎿  (eval):4: no matches found: /root/.claude/plugins/cache/temp_local_*  
    #      Cache: /root/.claude/plugins/cache/claude-hud
    #      YES | Registry: YES | Temp: none     
    # ...
    

安装成功验证：应显示 HUD 界面（底部状态栏）

观察会话底部出现：

Token 计数器：显示当前上下文占用 Token 数
上下文进度条：直观显示上下文接近上限程度
工具调用状态：显示正在执行的工具及进度
任务进度：多步骤任务时显示完成百分比

状态显示项先都启用，效果如下：

能实时展示coding plan的进度情况，还是很方便的

此处贴一下相关配置（都开启了），也可以直接新增编辑该文件：

  
[MacOS-xd@qxd ➜ ~ ]$ cat ~/.claude/plugins/claude-hud/config.json
{
  "lineLayout": "compacted",
  "showSeparators": false,
  "language": "en",
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": false,
    "showFileStats": false
  },
  "display": {
    "showModel": true,
    "showContextBar": true,
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showProject": true,
    "showConfigCounts": true,
    "showTokenBreakdown": true,
    "showSpeed": true,
    "showUsage": true,
    "usageBarEnabled": true,
    "showDuration": true,
    "showSessionName": true,
    "showSessionTokens": true
  }
}

说到这里，Claude Code的/buddy宠物展示，要取消的话，执行：/buddy off。

5. Claude Code 几个被低估的功能

实践一下这篇文章中，涉及的其中几个功能：Claude Code 15 个被低估的功能，创建者亲述。

关于创始人Boris Cherny，可了解 Claude Code 一周年：Boris Cherny 访谈中最值得开发者深思的 5 件事。

5.1. 会话远程切换功能、Cowork Dispatch远程操控桌面端

自己用happy-coder，貌似不需要了。可见：用手机远程控制Claude Code

5.2. 定时自动化：`/loop` 和 `/schedule`

（创始人说这是 Claude Code **最强大的两个功能）

Boris 的建议：把工作流变成 skill + loop 的组合

这可能是整个帖子里最有想象力的部分，把 Claude 从“你问它答”变成了后台持续运行的自动化工人。
但有几个限制要注意：终端必须保持开启，/loop 任务最长跑三天（一周是通过桌面端的 /schedule 实现的）
另外，这种自动处理审查并推到生产的做法，前提是你有充分的测试覆盖，不建议在测试薄弱的项目里照搬。

  
 /loop 30s 随机提示                                                                                      
 我将设置一个每 30 秒执行的随机提示任务。                                                                
 根据规则，30s 需要向上取整到最近 1 分钟（cron 的最小粒度是 1 分钟）。所以我将其设置为每 1 分钟执行一次。
 CronCreate(* * * * *: 随机提示)                                                                         
 ⎿  Scheduled 58228574 (* * * * *)                                                                       
 已安排周期性任务：                                                                                      
 - Job ID: 58228574                                                         
 - Cron 表达式: * * * * *（每分钟）                                                                      
 - 说明: 原始间隔 30s 已向上取整到 1 分钟（cron 最小粒度）                                               
 - 过期时间: 7 天后自动删除                                                                              
 - 取消方式: 使用 CronDelete 并提供 Job ID 可提前取消                                                    
 现在执行提示：                                                                                          
─────────────────────────────────────────────────────────────────────────────────────────────────────────
✻ Running scheduled task (Apr 6 10:51pm)             
● 🎲 随机提示                                        
  尝试这个：重构一个你最近写过的函数，让它更简洁     
  ...

5.3. `Hooks`（钩子）：在代理生命周期中插入确定性逻辑

SessionStart：每次启动时动态加载上下文

PreToolUse：每次执行 bash 命令（工具）前记录日志

PermissionRequest：把权限请求发到IM，远程批准或拒绝

Stop：Claude 停下来时自动催它继续

5.4. 会话分叉

两种方式：在当前会话里运行 /branch，或从命令行运行 claude --resume <session-id> --fork-session

场景：探索不同方案时有用。让 Claude 做到一半，想试另一个方向，分叉出去两边互不影响。

  
❯ /branch 
  ⎿  Branched conversation. You are now in the branch.
     To resume the original: claude -r 4bc1ad63-b6e8-4835-b1a1-525247070857
❯ 你的上下文 （ =========== 说明：此处是问问题）
● 当前上下文：                                                              
  - 会话状态：已创建新分支 4bc1ad63-b6e8-4835-b1a1-525247070857             
  - 之前的工作：                                                            
    - 设置了一个每 30 秒（实际为每分钟）的随机提示循环任务                  
    - 执行了约 15 次随机提示（编码建议、重构提示、测试提示等）              
    - 你已取消该循环任务（Job ID: 58228574）                                
  - 当前目录：/root                                                         
  - 项目状态：非 git 仓库                                                   
  有什么想继续做的吗？                                                      
────────────────────────────────────────────────────────────────────────────
❯                                                                       
────────────────────────────────────────────────────────────────────────────

另外，在shell终端执行 claude -r 4bc1ad63-b6e8-4835-b1a1-525247070857，可恢复/branch之前会话的记录

5.5. `/btw`（即by the way）：边工作边问问题

（这个平时用得多些）

Claude 执行任务的过程中，用 /btw 可以插入快速问题，不打断正在进行的工作。单轮问答，不会调用工具，但能看到当前会话的完整上下文。

5.6. `Git Worktrees`：并行开发的基础设施

Git 工作树（worktrees）允许你在同一个仓库里同时检出多个分支到不同目录，互不干扰。Claude Code 对工作树有深度支持。

5.7. `/batch`：大规模并行修改

/batch 先和你沟通需求，然后把任务扇出给多个工作树代理并行执行，数量可以是几十个、几百个甚至上千个。适用于大规模代码迁移和其他可并行化的工作。

前提是你的任务确实可以并行化，而且有足够的测试来验证批量修改没出问题。

未指定指令时会交互提示：

❯ /batch                                                                      
         
● 我需要了解您想要执行的批量更改。请提供具体的指令，描述您想要进行的批量修改。
                                                                              
  例如：                                                                      
  - 将项目中所有 .forEach 循环迁移到 for...of 语法                            
  - 将所有 var 声明替换为 const 或 let                                        
  - 为所有函数添加 JSDoc 注释                                                 
  - 将所有 CommonJS require 迁移到 ES6 import                                 
                                                                              
  您想要执行什么样的批量更改？                                                
                                                                              
──────────────────────────────────────────────────────────────────────────────
❯ /batch  <instruction>                                                       

5.8. `--bare`：SDK 启动提速最多 10 倍

写自动化脚本和 CI/CD 集成的人注意这条。加上 –bare 跳过不必要的配置加载，速度提升明显。

5.9. `--add-dir`：跨仓库工作

在一个仓库启动 Claude，用 --add-dir（或 /add-dir）让它看到并操作另一个仓库。

5.10. `--agent`：自定义代理

在 .claude/agents 目录下定义代理，用 claude --agent=<名字> 启动。可以给代理设定专属的系统提示词和工具集。

自定义代理的价值在于专业化。与其让一个通用 Claude 处理所有事，不如为代码审查、写测试、写文档各创建一个专用代理，每个加载不同的上下文和工具。这和前面 skill + loop 的思路是一脉相承的。

6. agent teams（智能体团队）

协调多个 Claude Code 实例作为一个团队一起工作，具有共享任务、代理间消息传递和集中管理。

Agent teams 需要 Claude Code v2.1.32 或更高版本。使用 claude --version 检查版本。
本地版本：2.1.97 (Claude Code)

Agent teams 是实验性功能，默认禁用。通过将 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 添加到你的 settings.json 或环境变量来启用它们。

6.1. 使用场景

Agent teams最适合用于并行探索能增加真实价值的任务：

研究和审查：多个队友同时调查问题的不同方面，然后分享和质疑彼此的发现
新模块或功能：各自拥有一个独立的部分
并行测试不同的理论，更快地收敛到答案
跨层协调：跨越前端、后端和测试的更改，每个由不同的队友负责

注意：Agent teams 增加了协调开销，使用的token数量明显多于单个会话。

建议场景：当队友可以独立运作时，它们效果最好。
不建议场景：对于顺序任务、同一文件编辑或有许多依赖关系的工作，单个会话或 subagents 更有效。

Agent teams 和 subagents的对比可见：协调 Claude Code 会话团队

Subagents 仅向主代理报告结果，彼此不交谈
在 agent teams 中，队友共享任务列表、认领工作并直接相互通信

6.2. 使用方式

配置文件~/.claude/settings.json中，设置环境变量。

  
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

对话直接让Claude Code创建团队即可，比如：帮我创建一个团队各自分析当前仓库下的不同目录内容，比顺序分析速度快很多

6.3. 多agent各自显示窗格

这个功能比较酷炫，见上面参考链接的“选择显示模式”章节。

Agent teams 支持两种显示模式：

in-process：所有队友在你的主终端内运行。使用 Shift+Down 循环浏览队友并输入以直接向他们发送消息。（试了笔记本上，用上下键即可，不用shift，状态栏会提示按键作用）
split panes，每个队友获得自己的窗格。可以同时看到每个人的输出，并点击窗格直接交互。可以设置tmux 或 iTerm2。默认值是 “auto”，如果已经在 tmux 会话中运行，则使用分割窗格，否则使用 in-process。

配置文件里，注意是~/.claude.json，这里设置tmux（系统先安装）：

  
{
  "teammateMode": "tmux"
}

主窗口会提示： view teammates: tmux -L claude-swarm-1001179 a

开一个新终端执行tmux -L claude-swarm-1001179 a，效果如下：

7. 参考

AI, Claude Code系列

AI Claude Code

This post is licensed under CC BY 4.0 by the author.