mirror of https://github.com/claude-code-best/claude-code.git synced 2026-06-22 16:25:51 +00:00

Files

claude-code-best 178868175e docs: 添加文档大纲及 superpowers/outline 目录

Co-Authored-By: deepseek-v4-pro <deepseek-ai@claude-code-best.win>

2026-06-15 16:51:29 +08:00

13 KiB

Raw Blame History

第九章：省钱、提速、定制 -- 穷鬼模式、缓存、Hooks、配置文件

token 账单太高、响应太慢、想让 Claude 自动响应特定事件 -- 这章帮你解决。

穷鬼模式：关掉不需要的自动任务，直接省钱

如果你用 Anthropic 官方 API 按量计费，可能会注意到每次对话结束时 Claude 会在后台做一些额外工作 -- 提取记忆、生成下一步建议。这些功能有用，但不是每次都需要。穷鬼模式 (/poor) 就是用来一键关掉它们的。

在 REPL 里输入 /poor 即可切换。你会看到类似这样的反馈：

Poor mode ON — extract_memories and prompt_suggestion are disabled

再次输入 /poor 则关闭：

Poor mode OFF — extract_memories and prompt_suggestion are restored

穷鬼模式关掉的核心功能有三个：extract_memories（每次 turn 结束后提取长期记忆）、prompt_suggestion（生成下一步操作建议）、以及 verification_agent（任务完成后自动验证结果）。这三个功能会额外消耗 API 调用和 token，关掉后只保留核心对话能力。

这个开关是持久化的 -- 它会写入 settings.json 的 poorMode 字段，下次启动 Claude 仍然生效。你可以用 /config 命令在设置界面中确认状态，也可以直接编辑 ~/.claude/settings.json：

{
  "poorMode": true
}

穷鬼模式对所有 Provider 都生效，包括 OpenAI 兼容层、Gemini 和 Grok，因为跳过的是对话流程中的额外步骤，跟具体 API 后端无关。

Prompt 缓存：为什么第二次回答更快

Anthropic API 有 prompt 缓存机制 -- 如果连续请求之间系统提示和对话历史没有变化，API 可以复用之前的结果，响应更快、费用更低。Claude Code 在构建过程中默认利用了这个缓存。

当对话变长、需要压缩（compact）时，缓存可能会被"打断"，因为压缩后的上下文和之前不同了。PROMPT_CACHE_BREAK_DETECTION 功能（构建时默认启用）会在压缩操作前后检测缓存是否仍然命中，帮助理解为什么某次请求变慢了。

对于普通用户来说，你不需要做任何特殊配置。只需要知道：保持对话的连贯性（不要频繁 /compact）有助于维持缓存命中，从而获得更快的响应速度。

Token 预算：控制每次请求的 token 上限

TOKEN_BUDGET 功能（构建时默认启用）会在系统提示中注入当前会话的 token 使用情况，让 Claude 感知到 token 预算的存在。它和 /cost 命令联动 -- 当你查看费用时，看到的 token 数据就是预算追踪系统收集的。

这个功能对使用按量计费 API 的用户特别有用。它不会硬性限制你的使用，而是让模型在生成回复时"心中有数"，更倾向于给出精简而非冗长的回答。

Hooks：让 Claude 在特定事件发生时自动执行操作

Hooks 是 Claude Code 的自动化基础设施。你可以在设置文件里定义"当 X 发生时，执行 Y"，比如"每次文件修改后自动跑测试"或"每次会话结束时自动提交 git 日志"。

Hook 的四种类型

Claude Code 支持 4 种 hook 类型：

command -- 执行 shell 命令
prompt -- 发送一个 LLM 提示请求
agent -- 启动一个代理来验证结果
http -- 向某个 URL 发送 POST 请求

可用的事件

Hook 可以绑定到以下事件上（在 settings.json 中作为 key）：

事件	触发时机
`PreToolUse`	工具调用前
`PostToolUse`	工具调用完成后
`PostToolUseFailure`	工具调用失败时
`SessionStart`	会话开始时
`SessionEnd`	会话结束时
`Stop`	Claude 停止生成时
`UserPromptSubmit`	用户提交输入时
`PreCompact`	上下文压缩前
`PostCompact`	上下文压缩后
`Notification`	收到通知时
`SubagentStart` / `SubagentStop`	子代理启停时
`FileChanged`	文件发生变化时

配置示例

在 settings.json 的 hooks 字段中添加 hook。下面是一个实际场景：每次 Claude 调用 Bash 工具执行 git push 之前，自动检查是否有未提交的更改：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "git status --short",
            "if": "Bash(git push *)",
            "shell": "bash"
          }
        ]
      }
    ]
  }
}

if 字段使用权限规则语法来过滤 -- 只有匹配 Bash(git push *) 模式的工具调用才会触发这个 hook，避免每次用 Bash 都执行。

再举一个会话启动时的例子，自动在日志中记录工作环境：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date): Claude session started in $(pwd)\" >> ~/.claude/session-log.txt"
          }
        ]
      }
    ]
  }
}

管理 Hooks

在 REPL 中输入 /hooks 会打开一个交互式配置界面，你可以浏览、添加、编辑和删除 hook。你也可以直接编辑 settings.json。

Hook 的高级选项

command 类型 hook 支持这些额外字段：

shell -- 指定 shell 解释器（bash 或 powershell），默认用 bash
timeout -- 超时时间（秒）
async -- 设为 true 则在后台运行，不阻塞主流程
asyncRewake -- 后台运行，如果退出码为 2 则唤醒模型（阻塞式错误）
once -- 设为 true 则只执行一次，之后自动删除
statusMessage -- 执行时显示的状态栏消息

http 类型 hook 支持通过 headers 字段添加自定义 HTTP 头，可以用 $VAR_NAME 或 ${VAR_NAME} 语法引用环境变量（需配合 allowedEnvVars 字段声明允许的变量名列表）。

settings.json 与 settings.local.json：团队共享 vs 个人覆盖

Claude Code 的配置文件分多个层级，支持组织统一管理和个人定制。

四个配置来源

来源	文件位置	用途	是否提交到 git
managed-settings	`/etc/claude-code/managed-settings.json`（Linux）或对应系统目录	组织管理员强制策略，优先级最高	不适用
userSettings	`~/.claude/settings.json`	个人全局配置，所有项目共享	不适用
projectSettings	项目根目录下 `.claude/settings.json`	项目级配置，团队共享	应提交
localSettings	项目根目录下 `.claude/settings.local.json`	个人项目级覆盖	应 gitignore

优先级从高到低：managed > local > project > user。后面的配置会合并（不是覆盖）前面的。比如 projectSettings 里设了 hooks，localSettings 里设了 permissions，两者都会生效。

实际用法

团队协作场景：在项目的 .claude/settings.json 中放入团队共享的权限规则和 hook 配置，提交到 git。团队成员各自可以在 .claude/settings.local.json 中添加个人偏好。

个人偏好场景：在 ~/.claude/settings.json 中设置 poorMode、defaultMode 等全局偏好，对所有项目生效。

用 /config 命令管理

在 REPL 中输入 /config 会打开一个交互式设置界面，包含 Config、Hooks、Permissions 等标签页，可以直接修改各项配置。

CLAUDE.md 四层层级：给 Claude 的项目指令

CLAUDE.md 是告诉 Claude "怎么理解这个项目"的文件，但它不是一个文件，而是四层层级：

Managed（如 /etc/claude-code/CLAUDE.md）-- 组织全局指令，所有用户、所有项目生效
User（~/.claude/CLAUDE.md）-- 个人全局指令，你所有项目共享
Project（项目目录下的 CLAUDE.md、.claude/CLAUDE.md、.claude/rules/*.md）-- 项目级指令，通常提交到 git 让团队共享
Local（CLAUDE.local.md）-- 个人项目级指令，不提交

加载顺序是从 Managed 到 Local，越晚加载的优先级越高（模型会更关注后加载的内容）。如果你在嵌套目录中工作，src/CLAUDE.md 的优先级高于项目根目录的 CLAUDE.md。

每个层级支持多个文件：比如 .claude/rules/ 目录下的所有 .md 文件都会被加载。还有一个特殊机制：.gitignore 的规则会被用来排除不想被加载的 CLAUDE.md 文件。

@include 指令：引用其他文件

CLAUDE.md 支持 @include 语法来引用其他文件内容，避免把所有东西写在一个文件里。语法有四种形式：

@path/to/file          # 相对路径（等同于 @./path/to/file）
@./relative/path       # 相对路径
@~/home/path           # 用户主目录下的路径
@/absolute/path        # 绝对路径

比如你在项目的 CLAUDE.md 中写：

# 项目规范

请遵循以下代码规范：

@./docs/coding-standards.md

@~/claude-rules/my-personal-preferences.md

@include 只在文本节点中生效（不会解析代码块内的内容），支持 60 多种文本扩展名（.md、.ts、.py、.json、.yaml、.sql 等）。不存在的文件会被静默忽略，循环引用会被自动检测和阻断。

keybindings.json：自定义快捷键

Claude Code 的快捷键可以通过 ~/.claude/keybindings.json 文件自定义。在 REPL 中输入 /keybindings 会自动生成一个模板文件（如果还没有的话）并在编辑器中打开它。

生成的模板包含所有可绑定的默认快捷键。你可以修改绑定值、添加新的绑定，或者设为 null 来取消某个快捷键。每个绑定项包含 context（如 "normal" 或 "insert"）和具体的键映射。

模板文件顶部会包含 JSON Schema 引用，支持编辑器的自动补全和校验：

{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "$docs": "https://code.claude.com/docs/en/keybindings",
  "bindings": [
    {
      "context": "normal",
      "bindings": {
        "enter": "submit",
        "escape": "cancel"
      }
    }
  ]
}

注意：部分快捷键是保留的（如退出快捷键），不可重新绑定，模板中已自动过滤掉这些项。

权限规则配置：控制 Claude 能做什么

权限规则定义了 Claude 在使用工具时需要什么样的批准。你可以在 settings 的 permissions 字段中配置 allow、deny 和 ask 规则列表。

规则语法

每条规则是一个字符串，格式为 ToolName 或 ToolName(content)：

Bash              # 匹配所有 Bash 工具调用
Bash(npm test)    # 只匹配执行 "npm test" 的 Bash 调用
Bash(git *)       # 匹配所有以 "git " 开头的 Bash 调用
Read(*.ts)        # 匹配所有读取 .ts 文件的操作
Write              # 匹配所有文件写入

圆括号内的内容支持通配符 *。如果只写工具名不写内容（如 Bash），则匹配该工具的所有调用。

配置示例

在项目的 .claude/settings.json 中配置：

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(npm test *)",
      "Bash(npm run lint *)"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ],
    "defaultMode": "ask"
  }
}

这个配置的含义是：读文件、搜索、查看 git 状态和日志、跑测试和 lint 不需要确认；rm -rf 命令一律拒绝；其他操作需要手动确认。

管理

在 REPL 中输入 /permissions 会打开一个交互式权限管理界面，可以添加、编辑、删除规则，还可以重试之前被拒绝的工具调用。

权限模式

defaultMode 可以设为以下值：

ask -- 每次需要工具权限时询问（默认）
auto -- 自动批准所有工具调用
deny -- 拒绝所有工具调用
sandbox -- 在沙箱环境中执行

在 REPL 中也可以通过 /mode 命令临时切换权限模式。

Feature Flag 运行时开关

Feature flag 控制着哪些功能在运行时启用。大部分功能在构建时已经由 DEFAULT_BUILD_FEATURES 决定了默认状态，但你可以通过环境变量在运行时覆盖。

用法：设置 FEATURE_<FLAG_NAME>=1 来启用某个 flag。例如：

FEATURE_MONITOR_TOOL=1 bun run dev

已禁用的 feature flag

以下 flag 在构建中已被注释掉，意味着即使设置环境变量也不会生效（代码路径不存在）：

Flag	禁用原因
`CONTEXT_COLLAPSE`	实现是空壳 stub，启用后会抑制 auto compact 导致上下文管理失效
`HISTORY_SNIP`	snip 功能暂时关闭
`FORK_SUBAGENT`	已通过 Agent tool 的等效方式实现，无需单独功能
`UDS_INBOX`	构建后 node.js 环境卡住
`LAN_PIPES`	依赖 UDS_INBOX，同样有 node.js 兼容问题
`REVIEW_ARTIFACT`	API 请求无响应，待排查 schema 兼容性
`SKILL_LEARNING`	功能暂停
`TEAMMEM`	依赖 COORDINATOR_MODE，邮箱文件无限增长

对于这些已禁用的 flag，不要尝试启用 -- 相关代码可能不完整或不兼容。

下一步

想了解所有 slash 命令的完整分类，看第四章：slash 命令速查
想了解 token 消费和费用查看，看第三章：日常对话
想排查 Provider 报错或性能问题，看第十章：可观测性与排错

13 KiB Raw Blame History Unescape Escape

第九章：省钱、提速、定制 -- 穷鬼模式、缓存、Hooks、配置文件

穷鬼模式：关掉不需要的自动任务，直接省钱

Prompt 缓存：为什么第二次回答更快

Token 预算：控制每次请求的 token 上限

Hooks：让 Claude 在特定事件发生时自动执行操作

Hook 的四种类型

可用的事件

配置示例

管理 Hooks

Hook 的高级选项

settings.json 与 settings.local.json：团队共享 vs 个人覆盖

四个配置来源

实际用法

用 /config 命令管理

CLAUDE.md 四层层级：给 Claude 的项目指令

@include 指令：引用其他文件

keybindings.json：自定义快捷键

权限规则配置：控制 Claude 能做什么

规则语法

配置示例

管理

权限模式

Feature Flag 运行时开关

已禁用的 feature flag

下一步

13 KiB

Raw Blame History