Claude Code 使用技巧整理

这篇文档主要记录我在使用 Claude Code 过程中的一些稳定工作流、提问方式和插件使用经验。目标不是把所有功能列一遍，而是整理出真正能提高交付效率的做法。

Claude Code 适合做什么

如果从游戏开发、工具链开发和内容工程的视角来看，Claude Code 更适合以下几类任务：

理解已有工程结构
批量重构脚本或工具代码
补测试、补文档、补脚手架
对接第三方 SDK、服务接口或命令行工具
做中等复杂度的多文件改动

它的优势不是“直接无脑一把梭”，而是：

长上下文理解能力比较稳定
对代码解释、重构、归纳总结表现较好
适合先分析、再执行的工作流

如果任务非常碎、非常即时，比如一边写一边需要行级补全，那还是 IDE 内补全工具更直接。

Claude配置文件位置

	`项目根/CLAUDE.md`	`~/.claude/settings.json`	`~/.claude.json`
语义	给 Claude 的指令	用户配置	系统内部状态
谁写	用户手写	用户手动编辑	Claude Code 自动维护
内容	项目规范、编码风格、工作流约定	API 密钥、模型配置、权限规则、MCP 服务器	启动次数、工具使用统计、项目级会话记录
类比	`.editorconfig` / `.eslintrc`	VS Code 的 `settings.json`	VS Code 的 `state.vscdb`
版本控制	应提交到 git	不提交（含密钥）	不提交（含用户 ID）
`env`	—	API 地址、模型名	—
`permissions`	—	工具白名单	—
`mcpServers`	—	全局 MCP 服务器	—
`enabledPlugins`	—	插件开关	—
`numStartups`	—	—	启动总次数
`projects`	—	—	每个项目的 MCP、信任状态、会话统计
`toolUsage`	—	—	每个工具的调用次数和最后使用时间
`tipsHistory`	—	—	已展示过的提示信息
备注	这个文件一直存在于上下文中。

我比较稳定的使用流程

先要求它说明影响面

在改公共模块、基础类库、构建脚本之前，可以先问：

1 2	如果修改这个函数签名，会影响哪些调用方？请按文件列出来，并说明高风险点。

这一步对避免误改很有价值。

让它顺手补验证步骤

除了改代码，我还会顺带要求：

修改完成后，请补充：
1. 如何验证
2. 建议执行的命令
3. 可能失败的边界情况

这样最后产出更接近可交付状态。

把“不要做什么”写明

例如：

不要改 public API
不要引入新依赖
不要动 UI 样式
不要修改数据库结构

这类负向约束非常重要，尤其是在已有项目里。

另外，Claude Sonnot会有比较严重的上下文焦虑。所以它只适合用于来做短暂的快速完成的小功能。

ClaudeCode底层实现讨论

模型自带的搜索能力WebSearch如何实现的

Claude Code 内置了两个独立的联网工具，经常被混为一谈：

工具	职责	输入	输出
WebSearch	搜索引擎入口	关键词 query	标题 + 链接列表
WebFetch	页面内容读取	具体 URL	页面正文

两者配合使用：先用 WebSearch 找到相关链接，再用 WebFetch 读取具体内容。

底层调用链路

这里有个比较有意思的实现细节，是社区通过逆向 Claude Code 流量发现的：

主对话触发：当 Claude 判断需要搜索时，主会话调用 WebSearch，传入 query 参数
派生子对话：Anthropic 服务端会为这次搜索单独起一个 Claude Opus 子会话，调用 Anthropic 内部的 web_search 服务端工具
结果回传：子会话处理完后，结果作为工具返回值传回主对话
可能多轮：整个过程可能在单次请求中重复多次（比如先搜一次，根据结果决定再搜一次）

这个设计的意图是让主 Agent 保持轻量，并限制注入面（injection surface），搜索逻辑在隔离的子会话里运行。

版本与收费说明

目前最新工具版本是 web_search_20260209，支持动态过滤（Dynamic Filtering，正式”进入 Claude 上下文之前”，先让代码过滤一遍，只保留有用的部分**）
API 用户：WebSearch 是单独计费的附加功能，每次搜索额外收费
Max 套餐用户：已经包含在套餐里，不单独扣费，可以直接用
这也是为什么有人反馈”用 Claude 订阅账号跑 Claude Code 时 WebSearch 显示 Rate limit，但用 API Key 却正常”——两者走的是不同的配额通道

和 MCP 搜索插件的区别

如果你已经用 Max 套餐，内置的 WebSearch + WebFetch 对日常搜索够用，不需要额外装 Tavily、Brave 这类 MCP 搜索插件。MCP 搜索插件更适合需要更高频次搜索、或者需要自定义搜索行为的 API 用户。

Plugin /其他工具/工作流

插件或者外部工具接入，真正的价值不是“功能变多”，而是让 Claude Code 可以从“只会说”变成“能查、能跑、能验证”。

我的判断标准通常是三条：

能不能减少手动切换上下文
能不能把分析结果落到真实工程上
能不能形成稳定工作流，而不是偶尔演示一次

ralph-loop （循环插件）

ralph-loop 这类插件我更倾向把它看成“循环执行框架”或者“任务闭环增强器”。

它比较适合下面这些场景：

一个任务需要多轮分析、执行、检查
需要让 AI 按固定节奏反复迭代
需要把大任务拆成可观察的小回合

自动化同意问题

如果你的目标只是“允许它直接修改当前工作区里的文件，不要每次都弹确认”，优先用 Claude Code 自带的权限模式，而不是指望插件本身绕过确认。

我建议分两档理解：

方案 1：只自动同意编辑文件

这是更稳的做法。

Claude Code 有一个 acceptEdits 模式，核心效果是：

工作区内的文件编辑可以批量接受
但执行命令、联网请求、其他有副作用的操作，仍然会继续询问

如果你主要烦的是“改这个文件能不能同意”这种提示，那应该优先用这一档。

可以通过 /config 或 /permissions 检查当前模式，也可以在设置文件里显式写上：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

常见放置位置：

全局生效：~/.claude/settings.json
当前仓库本地生效：.claude/settings.local.json
团队共享配置：.claude/settings.json

如果你只是想在自己机器上对当前项目放开，最适合放到 .claude/settings.local.json。这样不会提交进仓库，也不会影响别的项目。

方案 2：连命令确认也一起跳过

如果你希望 Claude Code 连命令执行、工具调用这些确认也尽量别问，可以直接用启动参数：

1	claude --dangerously-skip-permissions

这个模式相当于直接跳过权限确认，适合你完全信任当前仓库、并且明确知道它可能会自动执行改文件、跑命令、调用工具等操作的场景。

但这一档风险明显更高，不建议默认长期打开。更适合：

自己的个人仓库
隔离良好的测试环境
临时做高频迭代任务

不太建议直接用于：

来路不明的仓库
混有敏感配置的工程
会执行部署、发布、数据库操作的项目

实战建议

如果你的诉求只是“ralph-loop 在多轮执行时别一直问我能不能改文件”，那优先级应该是：

先把默认权限模式切到 acceptEdits
用 .claude/settings.local.json 只对当前仓库生效
只有在你连命令确认都嫌打断流程时，才改用 --dangerously-skip-permissions

简单说：

只想免掉文件编辑确认，用 acceptEdits
想把所有确认基本都跳过，用 --dangerously-skip-permissions

前者适合日常主力使用，后者适合你明确接受风险时再开。

简单说，ralph-loop 不是让 Claude Code “更聪明”，而是让你的任务编排更稳定。

Oh My Claude Code（OMC，Claude智能体集合）

主打一个零成本学习Claude的一个工具。提供一个预设好的agent合集。

安装方式

我使用npm包管理。在terminal里执行：
npm i -g oh-my-claude-sisyphus@latest
然后omc setup,完成设置。
项目网站

提供了5种模式

🔸 Autopilot（完全自主） - 从规划、实施到测试的全流程自动化
🔸 Ultra Pilot（并行加速） - 最多5个并行工作者同时处理，速度提升5倍
🔸 Swarm（协作团队） - 多个智能体像开发团队一样协作，从共享任务池领取工作
🔸 Pipeline（流水线） - 按固定顺序串联智能体，适合必须按步骤推进的工作流
🔸 EcoCode（经济模式） - 在保持效率的前提下最大化节省 token 消耗

新版本claude命令行下的标识

[OMC#4.11.2] | session:33m | ctx:32% | T:17 A:1
● 这是 OMC 状态栏的显示，各项含义：

[OMC#4.11.2] — OMC 插件版本号
session:33m — 当前会话已持续 33 分钟
ctx:32% — 上下文窗口已使用 32%
T:17 — Tool calls，本次会话已执行的工具新调用次数（17 次）
A:1 — Agents，当前活跃的子代理数量（1 个）

在运行命令的时候，遇到一个报错：

● Ran 4 stop hooks (ctrl+o to expand)
  ⎿  Stop hook error: Failed with non-blocking status code: /usr/bin/bash: line 1: node: command not found
  ⎿  Stop hook error: Failed with non-blocking status code: /usr/bin/bash: line 1: node: command not found
  ⎿  Stop hook error: Failed with non-blocking status code: /usr/bin/bash: line 1: node: command not found

首先建议全局安装 OMC，这样在全局的命令行里都能调用到这个，比在plugin里面管理会好些：

1 2	npm install -g oh-my-claude-sisyphus omc setup

上面提到的这个问题可能是因为没有安装tmux，

1	winget install psmux

claude-tap（API 流量追踪器）

一个本地代理工具，用来拦截并可视化 Claude Code、Codex CLI、Gemini CLI 等编程代理的真实 API 流量。

核心用途：调试 AI 行为时，能直接看到底层发生了什么——

查看完整的系统提示词、对话历史、工具定义与工具调用结果
比较相邻两次请求的差异，精确定位是哪条提示、哪个参数发生了变化
每次运行生成 JSONL 日志 + 自包含 HTML 查看器，方便留存和分享
数据全留本地，无需任何托管仪表盘，常见 auth header 会自动脱敏

安装（需 Python 3.11+）：

1
2
3

uv tool install claude-tap
# 或
pip install claude-tap

GitHub 项目地址
第一次使用

1	claude-tap --tap-live

工具在当前时间点不支持 Python 3.14 这个版本，所以为了适用这工具，我还特地降级为 3.13.

常用命令

这里有一个小区别：claude --resume 是在终端里执行的启动参数，/xxx 则是在 Claude Code 会话里直接输入的命令。

claude --resume：恢复最近一次或指定会话。终端意外关闭，或者你想接着上次上下文继续做时很好用。
/rewind：把当前会话回退到前面的某个节点。刚刚几轮思路跑偏、想撤回一段操作时非常方便。
/resume / /continue：在会话里恢复已有 session，或者直接打开会话选择器继续之前的任务。
/remote-control / /rc：把当前本地会话开放给远程控制，可以在 claude.ai/code 或移动端继续接手当前任务。这个功能很适合临时离开电脑但又不想断掉上下文的场景。
claude --dangerously-skip-permissions：启动时直接跳过权限确认，不再逐次询问用户同意。适合你完全信任当前仓库、并且希望 Claude Code 自主连续执行改文件、跑命令、调用工具的场景，但风险也最高，最好只在个人项目或隔离环境里临时使用。
/compact：把当前上下文压缩成摘要后继续同一会话。上下文快满、但你又不想重新解释项目背景时特别省事。（这个OMC不支持）
/doctor：检查 Claude Code 的安装、权限和配置问题。命令失效、插件不工作、环境异常时，先跑它通常能省掉不少排查时间。

报错及Debug

PreToolUse / PostToolUse Hooks 报错

报错示例：

Read 1 file (ctrl+o to expand)
  ⎿  PreToolUse:Read hook error    ⎿  ECONNREFUSED
  ⎿  PreToolUse:Read hook error    ⎿  ECONNREFUSED
  ⎿  PostToolUse:Read hook error   ⎿  ECONNREFUSED
  ⎿  PostToolUse:Read hook error   ⎿  ECONNREFUSED

原因分析：
一些公司会通过 Hooks 的方式监控 Claude 的使用情况，它同时还是 Claude Code 的 LLM 网关 —— ANTHROPIC_BASE_URL 也指向同一个端口。

“内网AI网关工具们”监听的 Endpoint：

Endpoint	触发时机	用途（推断）
`/hook/claude`	`UserPromptSubmit` / `Stop` / `StopFailure` / `Subagent*` / `PostToolUseFailure`	通用事件流 —— 把”用户提交了 prompt”、”会话结束”、”子 agent 启停”这类生命周期事件喂给“内网AI网关工具们”
`/hook/claude/pre-tool`	`PreToolUse`	工具调用前拦截 —— “内网AI网关工具们”能在这里看到你要调什么工具、什么参数
`/hook/claude/post-tool`	`PostToolUse`	工具调用后回执 —— “内网AI网关工具们”能看到工具返回了什么

“内网AI网关工具们”拿这些数据干嘛：

会话观测 / 录制 —— “内网AI网关工具们”是 GUI，需要实时知道 Claude Code 当前在做什么，才能在它的界面里展示”当前会话、调了哪些工具、用了多少 token”。
多 agent 编排 —— 看它的扩展代码（gateway-dispatch.ts），“内网AI网关工具们”内部跑了一个 daemon，可以在 Codex / Claude / Gemini / CodeMaker 之间分发任务、做后台任务卡片。Hooks 是它统一观察这些 agent 的入口。
可能的策略干预 —— PreToolUse hook 在 Claude Code 里是有能力 block / 改写工具调用的（这是规范的能力），但具体“内网AI网关工具们”用没用没看到证据。用空 {} 打 pre-tool 它回 422，说明它确实在解析 payload。

小结：

这些 hooks 是“内网AI网关工具们”把自己 UI 接到 Claude Code 上的观测 + 控制通道，不是必需。如果你不用“内网AI网关工具们”的 GUI 看会话状态、不用它编排多 agent，可以删；但因为 ANTHROPIC_BASE_URL 也走“内网AI网关工具们”，“内网AI网关工具们”进程本身仍然必须活着。

Windows 中文环境 PowerShell 乱码

报错示例：

● Bash(powershell.exe -NoProfile -Command "...")
  ⎿  Error: Exit code 1
     ����λ�� ��:1 �ַ��: 169
     + ... ref])|Out-Null;if(.Count -eq 0){'OK: no syntax errors'}else{|%{extglo ...
     +                                                                 ~
     ������ʹ�ÿչ��Ԫ��
         + CategoryInfo          : ParserError: (:) [], ParentContainsErrorRecordException
         + FullyQualifiedErrorId : EmptyPipeElement

原因分析：

Windows 简体中文版默认 code page 是 936 (GBK/GB2312)，但 Claude Code 内部按 UTF-8 处理字符串。PowerShell 输出中文错误信息时用 GBK 编码，Claude Code 按 UTF-8 解读 → 乱码。

这是一个非常常见的问题，几乎所有 CJK（中日韩）Windows 用户都会遇到。英文 Windows 不会触发，因为 code page 437 与 UTF-8 在 ASCII 范围内兼容。
修复方案：在 Claude Code settings 里设置环境变量

在项目级 .claude/settings.local.json 中添加：

{
  "env": {
    "CHCP": "65001"
  }
}

或全局生效，写入 ~/.claude/settings.json。

为什么不推荐改系统区域设置：

Windows 提供”Beta: 使用 Unicode UTF-8 提供全球语言支持”选项，会把系统 code page 从 936 改成 65001，效果最彻底，但属于全局不可逆改动，可能导致少数旧中文软件（GBK 硬编码的安装程序、老版压缩工具等）乱码。env CHCP=65001 只在 Claude Code 的 shell 进程里生效，系统其他部分完全不受影响。

修改后需要重启 Claude Code 会话才能生效。

参考资料

一个B站博主的学习视频