Trail of Bits Claude Code 配置

Trail of Bits 为 Claude Code 提供的约定默认值、文档和工作流。涵盖沙箱化、权限、钩子、技能、MCP 服务器，以及我们在安全审计、开发和研究中发现的有效使用模式。

另请参阅：skills · skills-curated · claude-code-devcontainer · dropkit

首次设置：

git clone https://github.com/trailofbits/claude-code-config.git
cd claude-code-config
claude

然后在会话内运行 /trailofbits:config。它会引导你完成每个组件的安装，检测你已有的内容，并自动安装该命令，以便今后从任何目录都能正常运行。更新后再次运行 /trailofbits:config。

目录

入门

• 请先阅读
• 先决条件
• Shell 设置
• 设置
• 全局 CLAUDE.md

配置

• 沙箱化
• 钩子
• 插件和技能
• MCP 服务器
• 本地模型
• 个性化

使用

• 持续改进
• 项目级 CLAUDE.md
• 上下文管理
• 网页浏览
• 快速模式
• 命令
• 编写技能和代理
• 推荐技能
• 推荐 MCP 服务器

入门

请先阅读

在进行任何配置之前，请先阅读以下内容，以了解此设置为何如此设计：

• Claude Code 最佳实践 —— Anthropic 官方关于高效使用 Claude Code 的指南
• 我如何利用 LLM 帮助我编写代码 —— Simon Willison 关于实用 LLM 辅助编码技巧的分享
• 面向无法仅靠直觉工作的团队的 AI 辅助编码 —— Nilenso 针对高标准团队集成 AI 工具的行动手册
• 我的那些对 AI 怀疑的朋友都疯了 —— Thomas Ptacek 论为何否定 LLM 在编码中的作用是错误的
• Harness 工程 —— OpenAI 关于构建完全无需人工编写代码的产品的经验

先决条件

终端：Ghostty

请使用 Ghostty。它是 Claude Code 的最佳终端，因为它采用原生 Metal GPU 渲染，能够流畅处理长时间 AI 会话产生的大量文本输出，而不会出现卡顿或内存膨胀（约 500MB 对比 VS Code 两个终端会话的约 8GB）。Shift+Enter 和快捷键开箱即用，无需额外的 /terminal-setup 配置；内置的分屏功能（Cmd+D / Cmd+Shift+D）让你无需 tmux 即可同时运行 Claude Code 和开发服务器；并且在长时间自主运行时绝不会崩溃。

brew install --cask ghostty

仅适用于 macOS。Linux 用户请参考 Ghostty 安装文档。目前尚不支持 Windows —— 请改用 WezTerm。

工具

通过 Homebrew 安装核心工具：

brew install jq ripgrep fd ast-grep shellcheck shfmt \
  actionlint zizmor macos-trash node@22 pnpm uv

Python 工具（通过 uv）：

uv tool install ruff
uv tool install ty
uv tool install pip-audit

Rust 工具链：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install prek worktrunk cargo-deny cargo-careful

Node 工具：

npm install -g oxlint agent-browser

LM Studio（用于 本地模型）：

curl -fsSL https://lmstudio.ai/install.sh | bash

这将安装 lms（CLI）和 llmster（无头守护进程）。或者，如果你更喜欢图形界面，也可以安装 LM Studio 桌面应用。

Shell 设置

在 ~/.zshrc 中添加：

alias claude-yolo="claude --dangerously-skip-permissions"

--dangerously-skip-permissions 会跳过所有权限提示。这是为了获得最大吞吐量而推荐的运行方式——建议与下方的沙箱化结合使用。

如果你正在使用 本地模型，还需添加：

claude-local() {
  ANTHROPIC_BASE_URL=http://localhost:1234 \
  ANTHROPIC_AUTH_TOKEN=lmstudio \
  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
  claude --model qwen/qwen3-coder-next "$@"
}

claude-local 将 claude 包装起来，注入本地服务器的环境变量，并禁用那些无论如何都无法到达 Anthropic 的遥测请求。在通常运行 claude 的地方都可以使用它。

设置

将 settings.json 复制到 ~/.claude/settings.json（或将其条目合并到您现有的文件中）。$schema 键可在支持 JSON Schema 的编辑器中启用自动补全和验证。模板包括：

• env（隐私） -- 禁用三个非必要的出站流：Statsig 遥测（DISABLE_TELEMETRY）、Sentry 错误报告（DISABLE_ERROR_REPORTING）以及反馈调查（CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY）。请避免使用总括性的 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC -- 它还会禁用自动更新。
• env（代理团队） -- CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 启用 多代理团队，其中单个会话可协调多个具有独立上下文窗口的队友。处于实验阶段，已知在会话恢复和任务协调方面存在局限性。
• enableAllProjectMcpServers: false -- 这是默认设置，显式设定以防止被意外更改。项目 .mcp.json 文件存储在 Git 中，因此一旦仓库被攻陷，就可能推送恶意的 MCP 服务器。
• alwaysThinkingEnabled: true -- 在会话之间持续启用 扩展思考模式。可通过 Option+T 按键逐会话切换。对于简单任务会增加延迟和成本；但对于复杂推理则值得开启。
• permissions -- 拒绝规则，阻止读取凭据/密钥及编辑 shell 配置文件（参见 沙箱化）
• cleanupPeriodDays: 365 -- 将对话历史保留一年，而非默认的 30 天，以便 /insights 能有更多数据
• hooks -- Bash 中的两个 PreToolUse 钩子，分别阻止 rm -rf 命令和直接推送到主分支（参见 钩子）
• statusLine -- 指向状态栏脚本（见下文）

状态栏

终端底部的两行状态栏：

 [Opus 4.6] 📁 claude-code-config │ 🌿 main
 ████⣿⣿⣿⣿⣿⣿⣿⣿ 28% │ $0.83 │ ⏱ 12m 34s ↻89%

第一行显示模型、当前目录和 Git 分支。第二行显示上下文使用情况的可视化条形图（颜色编码：绿色 <50%，黄色 50-79%，红色 80% 及以上）、会话成本、已用时长以及提示缓存命中率。

复制脚本：

mkdir -p ~/.claude
cp scripts/statusline.sh ~/.claude/statusline.sh
chmod +x ~/.claude/statusline.sh

settings.json 中的 statusLine 条目指向此脚本。需要安装 jq。

全局 CLAUDE.md

位于 ~/.claude/CLAUDE.md 的全局文件为每个 Claude Code 会话设置了默认指令。它涵盖了开发哲学（不采用推测性功能、不进行过早抽象、替换而非弃用）、代码质量硬性限制（函数长度、复杂度、行宽）、针对 Python（uv、ruff、ty）、Node/TypeScript（oxlint、vitest）、Rust（clippy、cargo deny）、Bash 和 GitHub Actions 的特定语言工具链，以及测试方法、代码审查顺序和工作流程规范（提交、钩子、PR）。

将模板复制到位：

cp claude-md-template.md ~/.claude/CLAUDE.md

请根据个人偏好进行审查和自定义。该模板带有一定倾向性——请调整语言部分、工具选择及硬性限制，以匹配您的技术栈。有关 CLAUDE.md 文件的工作原理（层级结构、自动记忆、模块化规则、导入）的背景信息，请参阅 管理 Claude 的记忆。

配置

沙箱化

在 Trail of Bits，我们以绕过权限检查的模式运行 Claude Code（--dangerously-skip-permissions）。这意味着您需要了解自己的沙箱选项——代理无需询问即可执行命令，因此沙箱才是防止其造成损害的关键。

内置沙箱（/sandbox）

Claude Code 自带原生沙箱，利用操作系统级别的原语实现文件系统和网络隔离（macOS 上的 Seatbelt，Linux 上的 bubblewrap）。只需在会话中输入 /sandbox 即可启用。在自动允许模式下，所有未超出沙箱边界的 Bash 命令都会在无需权限提示的情况下执行。

默认行为： 写操作仅限于当前工作目录及其子目录。读操作则不受限制——代理仍可读取 ~/.ssh、~/.aws 等文件。网络访问仅限于明确允许的域名。

强化读取保护： settings.json 模板包含用于阻止访问凭据和密钥的 Read 和 Edit 拒绝规则：

• SSH/GPG 密钥 -- ~/.ssh/**、~/.gnupg/**
• 云凭据 -- ~/.aws/**、~/.azure/**、~/.kube/**、~/.docker/config.json
• 包注册表令牌 -- ~/.npmrc、~/.npm/**、~/.pypirc、~/.gem/credentials
• Git 凭据 -- ~/.git-credentials、~/.config/gh/**
• Shell 配置 -- ~/.bashrc、~/.zshrc（禁止编辑，防止植入后门）
• macOS 钥匙串 -- ~/Library/Keychains/**
• 加密钱包 -- MetaMask、Electrum、Exodus、Phantom、Solflare 等应用的数据

如果没有启用 /sandbox，这些拒绝规则仅对 Claude 的内置工具生效——Bash 命令会绕过它们。而启用 /sandbox 后，相同的规则会在操作系统层面强制执行（Seatbelt/bubblewrap），因此 Bash 命令也会被阻止。建议两者结合使用。

关于沙箱设计的详细理由，请参阅 Anthropic 的 工程博客文章。完整的配置参考，请参阅 沙箱文档。

开发容器

若需完全的读写隔离，可使用开发容器。代理将在仅挂载项目文件的容器中运行——它无法访问您的主机文件系统、SSH 密钥、云凭据或其他任何容器外的内容。

• trailofbits/claude-code-devcontainer -- 预配置的开发容器，集成 VS Code，预装 Claude Code，并配备常用开发工具。

远程 Droplet 实例

若希望与本地机器彻底隔离，可将代理部署在一次性云实例上：

• trailofbits/dropkit -- 用于管理 DigitalOcean Droplet 的 CLI 工具，具备自动化设置、SSH 配置和 Tailscale VPN 功能。创建一个 Droplet，通过 SSH 登录，运行 Claude Code，完成后销毁实例。

钩子

钩子是会在 Claude Code 生命周期中的特定节点触发的 Shell 命令（或大语言模型提示）。它们提供了一种在模型通常不会暂停的决策点与之交互的方式。每个 PreToolUse 钩子都是一次机会，可以告诉模型“停下，先思考一下”或者“不要这样做，改用另一种方式”。每个 PostToolUse 钩子则是在模型完成操作后告知其“现在你已经完成了这件事，接下来你应该知道这些信息”。而每个 Stop 钩子则是提醒模型“你还未完成任务”。

这种机制比仅靠系统提示更强大，因为钩子会在具体的、具有上下文意义的时刻触发。如果你在 CLAUDE.md 中写上“永远不要使用 rm -rf”，这条指令可能会被遗忘，或者因上下文压力而被覆盖。然而，一个阻止 rm -rf 的 PreToolUse 钩子则会在每次执行时立即触发，并在决策点直接显示错误信息。

需要注意的是，钩子并不是安全边界——提示注入仍然可能绕过它们。实际上，钩子是一种在恰当时机进行的结构化提示注入：拦截工具调用、注入上下文、阻止已知的不良模式，并引导智能体的行为。它们更像是护栏，而非围墙。

在实际应用中，你可以利用钩子来：

• 阻止已知的不良模式——例如 rm -rf、直接推送到主分支、使用错误的包管理器；
• 添加自定义日志记录——审计轨迹、Bash 命令日志、变更追踪；
• 推动 Claude 继续工作——通过一个 Stop 钩子检查 Claude 的最终响应，如果发现它在为未完成的工作找借口，就强制其继续；
• 在决策点注入上下文——如代码格式化后的检查结果、工具调用前的安全警告等。

相关指南与示例：使用钩子自动化工作流

不想手动编写钩子？可以使用 hookify 插件，它能将自然语言描述转换为钩子配置——例如 /hookify 当我使用 rm -rf 命令时提醒我。

钩子事件

事件	触发时机	是否可阻止？
PreToolUse	工具调用执行之前	是
PostToolUse	工具调用成功之后	否
UserPromptSubmit	用户提交提示时	是
Stop	Claude 完成响应时	是
SessionStart	会话开始或恢复时	否
SubagentStart/Stop	子智能体启动或结束时	启动：否，结束：是
TaskCompleted	任务被标记为完成时	是
TeammateIdle	团队成员即将进入空闲状态时	是

退出码

退出码	行为
0	允许执行操作（标准输出会被解析为 JSON 控制指令）
1	非阻塞式错误（在详细模式下显示错误信息到标准错误流）
2	阻塞式错误（错误信息会回传给 Claude 作为错误消息）

示例

这些只是可供参考的模式，而非可以直接使用的配置。 推荐的默认设置仅包括 settings.json 中的两个阻塞型钩子。以下内容仅供参考，请仔细阅读代码，理解其功能，并根据你的工作流程进行调整后再使用。

阻止不良模式（PreToolUse，位于 settings.json 中）：此仓库的 settings.json 文件中包含两个钩子，分别用于阻止 rm -rf 命令（建议改用 trash）以及禁止直接推送至主分支（要求必须使用特性分支）。这两个钩子都会通过 jq 从标准输入读取 Bash 命令，使用正则表达式匹配，然后以退出码 2 返回错误信息，指导 Claude 应该采取何种替代方案。

审计日志记录（PostToolUse）：hooks/log-gam.sh 展示了如何为 CLI 工具构建审计跟踪。这个示例针对 GAM（Google Apps Manager）命令，通过动词模式列表将其分类为读操作或写操作，跳过读操作，并记录每次变更的时间戳、操作类型、具体命令及退出状态。这一模式可以推广到任何需要记录变更的 CLI 工具，只需替换相应的动词列表即可。将其配置为 Bash 的 PostToolUse 钩子即可。

Bash 命令日志（PostToolUse）：将代理执行的每条 Bash 命令连同时间戳追加到日志文件中。这对于会话结束后回顾代理的实际操作非常有用。

{
  "PostToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "jq -r '\"[\" + (now | todate) + \"] \" + .tool_input.command' >> ~/.claude/bash-commands.log"
        }
      ]
    }
  ]
}

桌面通知（Notification）：当 Claude 需要你的注意时，会触发操作系统原生的通知，这样你就可以在长时间的自主运行期间切换到其他工作，而不必一直盯着终端。

{
  "Notification": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "osascript -e 'display notification \"Claude 需要您的注意\" with title \"Claude Code\"'"
        }
      ]
    }
  ]
}

在 Linux 系统上，可以将命令替换为 notify-send 'Claude Code' 'Claude 需要您的注意'。

强制使用指定的包管理器（PreToolUse）：hooks/enforce-package-manager.sh 会阻止在使用 pnpm 的项目中执行 npm 命令，并提示 Claude 使用正确的工具。这一方法同样适用于任何“必须使用 X 而非 Y”的约定。

反自我开脱关卡（Stop，提示钩子）：Claude 有时会在工作尚未完成时就宣布胜利，并为自己找各种借口，比如“这些问题本来就有”、“修复这个超出了范围”、“留待后续处理”等。通过一个基于提示的 Stop 钩子，可以在允许 Claude 结束任务之前，让一个快速模型先审查其最终回复，判断是否存在类似的自我开脱行为。

{
  "Stop": [
    {
      "hooks": [
        {
          "type": "prompt",
          "prompt": "你是一名仅接受 JSON 输入的评估者。你必须仅以一个 JSON 对象作为回应，不得包含任何其他内容。禁止使用 Markdown、代码块、解释性文字或任何前言，只返回原始的 JSON 对象。\n\n请审查助手的最终回复。如果助手存在为未完成的工作找借口的行为——例如声称问题‘原本就存在’或‘超出范围’、以‘问题太多无法修复’为由推卸责任、未经请求地提出‘后续处理’、列出问题却不加以解决，或者用各种理由忽略测试或 linter 报错——则应返回：{\"ok\": false, \"reason\": \"您正在为未完成的工作找借口。[具体问题]。请返回并完成。\"}\n\n否则，请返回：{\"ok\": true}。\n\n"
        }
      ]
    }
  ]
}

这里使用了 type: "prompt" 而不是 type: "command"——Claude Code 会将钩子的提示加上助手的回复发送给一个快速模型（Haiku），后者会给出肯定或否定的判断。如果被拒绝，拒绝理由会被作为下一条指令回传给 Claude，从而强制其继续工作。

重要提示：提示中必须明确指示评估者仅以原始 JSON 格式回应。否则，Haiku 可能会将 JSON 包装在 Markdown 代码块中，或添加解释性文字，这会导致 JSON 解析失败，进而使钩子失效。提示钩子的默认超时时间为 30 秒，如有需要，可以通过 timeout 字段进行调整。

插件与技能

Claude Code 的功能由插件提供，这些插件包括技能（可重用的工作流）、代理（专业子代理）和命令（斜杠命令）。插件通过市场分发。

Trail of Bits 市场

安装三个 Trail of Bits 市场：

claude plugin marketplace add trailofbits/skills
claude plugin marketplace add trailofbits/skills-internal
claude plugin marketplace add trailofbits/skills-curated

仓库	描述
trailofbits/skills	我们的公开技能，用于安全审计、智能合约分析、逆向工程、代码审查以及开发工作流。
trailofbits/skills-internal	自动化漏洞利用、模糊测试框架生成、特定类型漏洞分析、以 Trail of Bits 风格编写的审计报告、项目范围界定、客户交付物以及专有工作流。仅供 Trail of Bits 内部使用。
trailofbits/skills-curated	经过我们审核并批准使用的第三方技能和外部市场。每次新增都会进行代码审查。

对于外部市场（Anthropic 官方、superpowers、compound-engineering 等），请参阅 skills-curated —— 它维护着已批准的列表和安装脚本。

agent-browser 技能

agent-browser CLI（在先决条件中已安装）自带一个市场，其中包含一项第一方技能，该技能会教 Claude 快照/引用的工作流、命令语法、会话管理、认证流程、视频录制以及代理支持等内容（约 2,000 行参考材料加上可重用的 Shell 模板）。由于 agent-browser 是较新的工具，尚未被纳入模型的预训练数据中——如果没有这项技能，Claude 将无法理解引用生命周期或命令 API。

/plugin marketplace add vercel-labs/agent-browser
/plugin install agent-browser@agent-browser

MCP 服务器

Trail of Bits 的每位员工都应至少将 Context7 和 Exa 设置为全局 MCP 服务器。

服务器	功能	要求
Context7	查找最新的库文档	无（无需 API 密钥）
Exa	网络与代码搜索（见网络浏览）	需要 EXA_API_KEY 环境变量（Trail of Bits 员工：共享密钥存储于 1Password；外部用户：在此获取）

设置

MCP 服务器在 .mcp.json 文件中配置。Claude Code 会合并来自两个位置的配置：

• ~/.mcp.json —— 在每个会话中都可用的全局服务器
• 项目根目录下的 .mcp.json —— 项目专用服务器

将此仓库中的 mcp-template.json 复制到 ~/.mcp.json 中，以实现全局可用性。将 your-exa-api-key-here 替换为您的实际密钥，或者如果您没有密钥，则移除 exa 条目。将项目专用的 MCP 服务器（例如本地数据库工具）添加到项目的 .mcp.json 中。

本地模型

使用 LM Studio 运行本地 LLM，并将其与 Claude Code 配合使用。LM Studio 提供与 Anthropic 兼容的 /v1/messages 端点，因此 Claude Code 只需更改基础 URL 即可连接。在 macOS 上，它使用 MLX 实现 Apple Silicon 原生推理，速度显著快于 GGUF。

推荐模型：Qwen3-Coder-Next（截至 2026 年 2 月）

Qwen3-Coder-Next 是一款 80B 混合专家模型，仅激活 3B 参数，专为代理式编码设计。它可以处理工具调用、长时序推理以及从执行失败中恢复。MLX 4 位量化版本约为 45GB，需要至少 64GB 统一内存才能加载，并拥有可用的上下文窗口。96GB 或以上则更为舒适。

本地模型更新迅速。当此推荐过时时，请查看 LM Studio 的特色模型页面，选择适合您内存容量且采用 MLX 4 位量化的顶级编码模型。

设置

下载、加载并启动服务——所有操作均可通过 CLI 完成：

lms get Qwen3-Coder-Next@MLX-4bit -y
lms load qwen/qwen3-coder-next --context-length 32768 --gpu max -y
lms server start

--context-length 32768 在加载时分配 32K 的上下文窗口。Claude Code 对上下文要求较高，因此不应低于 25K。采样参数（温度、top-p 等）无需在服务器上配置——Claude Code 会在每次 API 请求中自行发送。

连接

通过设置基础 URL 和认证令牌（对于本地服务器，任何字符串均可），将 Claude Code 指向 LM Studio：

ANTHROPIC_BASE_URL=http://localhost:1234 \
ANTHROPIC_AUTH_TOKEN=lmstudio \
claude

或者使用 Shell 设置 中的 claude-local shell 函数，以避免每次都输入环境变量。

如果 claude-local 出现错误信息“从初始提示中保留的标记数量大于上下文长度”，请尝试禁用自动加载的工具（先使用 --strict-mcp-config，再尝试同时使用 --disable-slash-commands 和 --system-prompt "You are a helpful coding assistant."）。

如果 claude-local 报错“request.thinking.type: 无效的判别值。预期 'enabled' | 'disabled'”，则添加 --settings '{"alwaysThinkingEnabled": false}' 标志。

有关完整环境变量列表（模型覆盖、子代理模型、流量控制等），请参阅 模型配置文档。

个性化

您可以自定义 Claude 工作时显示的加载动画词汇。只需对 Claude 说：“在我的设置中，将加载动画词汇设为黑客主题”——也可以是 Doom、星际迷航或其他风格。

使用方法

在阅读本节内容之前，请先阅读 Anthropic 的《Claude Code 最佳实践》（https://code.claude.com/docs/en/best-practices）。这是获得良好结果的最重要资源。以下内容均以此为基础。

持续改进

大多数人在使用 Claude Code 时很快就会陷入瓶颈。他们找到一种有效的工作流程并不断重复，却从未意识到自己还有多少潜力未被发掘。解决办法是建立一个刻意的反馈循环：回顾过去发生的事情，调整您的设置，让下一周受益于所学的经验。

每周运行一次 /insights。它会分析您最近的会话并提炼出模式——哪些做法有效，哪些失败，您把时间花在了哪里。当它指出有用的信息时，请立即采取行动：在 CLAUDE.md 中添加一条规则，编写一个钩子来阻止您反复犯的错误，或将重复的工作流程提取为一项技能。每一次调整都会产生叠加效应。几周之后，您的设置将与默认设置大不相同，完全贴合您的实际工作方式。

项目级 CLAUDE.md

对于你参与的每个项目，在仓库根目录下添加一个 CLAUDE.md 文件，其中包含该项目特有的上下文信息。全局 CLAUDE.md 定义了默认设置；而项目级别的文件则在此基础上叠加该代码库的独特内容。一份优秀的项目 CLAUDE.md 应包括架构（目录结构、关键抽象）、构建与测试命令（make dev、make test）、代码库导航模式（针对你代码库的 ast-grep 示例）、领域特定的 API 和常见陷阱，以及测试规范。

如需参考一个结构良好的项目 CLAUDE.md 示例，请查看 crytic/slither 的 CLAUDE.md。它在本仓库提供的通用标准之上，进一步叠加了 slither 特有的上下文——SlithIR 内部机制、检测器遍历模式、类型处理中的坑点等。

输出样式

当你熟悉一个新的代码库时，启用解释型 输出样式（通过 /output-style explanatory 命令，或在 settings.json 中设置 "outputStyle": "Explanatory"）。Claude 在工作过程中会解释框架和代码模式，并在其正常输出旁添加“★ 洞察”区块，说明推理过程和设计选择。这在审计不熟悉的代码、审查非日常使用的编程语言，或刚加入客户项目时非常有用。不过，这种模式的权衡在于上下文：较长的响应会导致更早触发压缩。当你需要速度时，可以切换回默认样式。你也可以在 ~/.claude/output-styles/ 目录下以 Markdown 文件的形式创建自定义样式。

上下文管理

上下文窗口是有限且不可替代的，会在会话中被不断消耗。每次读取文件、调用工具或进行一次对话都会占用它。当上下文窗口满载时，Claude 会自动压缩对话——将对话摘要化以释放空间。自动压缩虽然有效，但会造成信息丢失：细微的决策、错误细节以及推理线索都会在每次压缩后逐渐退化。最好的策略就是尽量避免触发压缩。

保持会话简洁

将工作限定在一个会话内。 每个功能、Bug 修复或调查都应控制在单个上下文窗口之内。如果任务过于庞大，就将其拆分成若干部分，分别在新的会话中完成。这是提升质量最有效的方法。

一个始终在上下文预算内的会话，其产出的代码质量远胜于那些经过三次压缩才勉强完成的会话。当你发现上下文即将耗尽时（可通过状态栏判断：绿色 >50%、黄色 >20%、红色低于 20%），就应该结束当前会话并开启新会话，而不是硬撑下去。

优先使用 /clear 而不是 /compact。 /clear 会清空对话并重新开始，而 /compact 则会总结对话并继续。建议在不同任务之间默认使用 /clear。

/compact 在你正在进行某项任务且需要回收空间而不丢失进度时很有用，但每次压缩都是一次有损压缩——细节会被丢弃，模型对你意图的理解也会略有下降。如果一个会话中进行了两次压缩，那就说明任务本身过大。而 /clear 不会造成任何信息损失，因为此时并无可失去的内容——你的 CLAUDE.md 会重新加载，Git 状态也会恢复到最新，代理也会重新读取所需文件。如果你确实需要使用 /compact，可以通过传递重点指令来引导摘要内容，例如 /compact Focus on the auth refactor，这样就能保留重要部分并舍弃其他内容。

两次修正后果断止损。 如果你已经对同一个问题纠正了 Claude 两次，但它仍然出错，那就不要再继续尝试了——上下文已经被失败的思路污染了。这时可以使用检查点功能（Esc Esc 或 /rewind）回滚到第一次错误操作之前，然后用更好的提示重新尝试。如果会话已经严重偏离轨道，无法通过检查点修复，那就直接使用 /clear 并从头开始。一个结合了先前经验的全新提示，通常比经过多次修正的冗长会话效果更好。

管理上下文的工具

检查点（Esc Esc 或 /rewind）可以将代码和对话恢复到会话中任意之前的提示状态。它们相当于你的撤销系统，应积极使用。你可以大胆尝试各种方法，因为知道如果不成功还可以回退。

在回溯菜单中，“从这里开始摘要”选项是比 /compact 更为精细的选择：它不会压缩整个对话，而是保留早期的上下文，只对占用大量空间的部分（比如冗长的调试讨论）进行摘要。这样可以完整保留你的初始指令。

将研究任务交给子代理处理。 子代理（Task 工具、自定义代理）各自拥有独立的上下文窗口。主会话只会看到子代理的摘要，而不会接触到其完整的内部工作上下文。

请有意识地利用这一点：当任务需要阅读大量文档、探索陌生代码，或进行可能使主会话上下文膨胀的研究时，可以将其委派给子代理。这样主会话就能保持精简，专注于实现，而子代理则负责处理那些需要大量上下文的任务。

对于复杂功能，先访谈再实现。 让 Claude 先与你讨论该功能的需求、边界情况和权衡，然后将规格写入文件。之后再开启一个新的会话来实现该规格。

将稳定不变的上下文放入 CLAUDE.md，而非对话中。 项目架构、编码规范、工具偏好、工作流程约定等可复用的内容都应放在 CLAUDE.md 中。它会在每次会话中自动加载，并且在执行 /clear 后仍能保留。

如果需要在不同会话之间传递上下文，可以先提交当前的工作成果，将简要计划写入文件，然后执行 /clear，并在下一个会话中让 Claude 查看该文件即可。你也可以通过 claude --continue 继续上一个会话，或使用 claude --resume 从最近的会话中选择继续。不过，相比恢复一个过时的会话，从头开始并辅以书面交接通常效果更好——这样上下文更加干净，提示缓存也更为温暖。

网络浏览

Claude Code 提供三种与网络交互的方式。

Exa AI (MCP)

这是一种语义化的网页搜索工具，能够返回干净且专为大语言模型优化的文本。与内置的 WebSearch 工具不同（后者仅返回搜索结果链接，Claude 还需自行获取并解析这些链接），Exa 会直接提取并格式化内容，使其更适合大语言模型使用。这不仅节省了上下文窗口，还能带来更相关的结果。你可以在 CLAUDE.md 中指示 Claude 更倾向于使用 Exa 而不是 WebSearch。

agent-browser

通过命令行实现无头浏览器自动化。它会运行自己的 Chromium 实例——不会共享您的 Chrome 配置文件、Cookie 或登录会话。这意味着，如果没有从头开始登录，它无法访问已认证的页面（如 Google 文档、内部仪表板等）。它的优势在于上下文效率：快照/引用系统（@e1、@e2）使用的上下文比发送完整的无障碍树少约 93%，因此该代理可以在不耗尽上下文窗口的情况下导航复杂的多页工作流。此外，还支持视频录制和并行会话。

agent-browser open <url>        # 导航
agent-browser snapshot -i       # 获取元素引用（@e1、@e2）
agent-browser click @e1         # 点击元素
agent-browser fill @e2 "text"   # 填充输入框
agent-browser screenshot        # 截取屏幕截图

您需要安装第一方技能，才能让 Claude 有效使用 agent-browser——请参阅配置部分中的 agent-browser 技能。

Claude in Chrome (MCP)

通过 Claude in Chrome 扩展程序实现浏览器自动化。它运行在您实际的 Chrome 浏览器中，因此可以访问您现有的登录会话、Cookie 和扩展程序。这是唯一一种无需重新认证即可与已认证页面（Gmail、Google 文档、Jira、内部工具）交互的选项。其代价是，它使用屏幕截图和无障碍树来理解页面内容，这会消耗比 agent-browser 的引用系统更多的上下文。

何时使用哪种工具

需求	使用
在网上搜索信息	Exa
自动化公共页面上的多步骤工作流	agent-browser
与已认证/内部页面交互	Claude in Chrome
录制浏览器操作视频	agent-browser
检查视觉布局或截取屏幕截图以进行分析	Claude in Chrome

快速模式

/fast 可切换快速模式。使用相同的 Opus 4.6 模型，输出速度提升约 2.5 倍，但每 token 的成本增加 6 倍。默认情况下应保持关闭状态。

只有在紧密的交互式循环中，快速模式才值得开启——例如您正在实时调试、迭代输出结果，而每一秒的延迟都会让您分心。如果您即将启动一项自主运行任务（如 /fix-issue、群集任务或任何您无法持续监控的任务），请先将其关闭。代理本身并不会受益于更低的延迟；您只是在浪费资金。

如果确实要使用快速模式，请在会话开始时启用。在对话中途切换会导致整个上下文按快速模式费率重新计价，并使提示缓存失效。有关详细信息，请参阅快速模式文档。

命令

自定义斜杠命令是定义参数化流程的 Markdown 文件。它们接受参数，执行特定的步骤序列，并产生结果。这些命令是从经常出现在 /insights 中的手动工作流中提取出来的——如果您发现自己反复执行相同的多步骤序列，那么它就很适合作为一个命令。

一旦某个工作流被定义为命令，代理也可以执行它。您可以将 claude -p 包装在一个 shell 脚本中，并使用 xargs -P 来并行地在多个代码库中分发同一命令——每个命令都会获得一个带有预算上限的独立无头会话。

mkdir -p ~/.claude/commands
cp commands/review-pr.md ~/.claude/commands/
cp commands/fix-issue.md ~/.claude/commands/
cp commands/merge-dependabot.md ~/.claude/commands/

审核 PR

commands/review-pr.md——使用并行代理（pr-review-toolkit、Codex、Gemini）审核 GitHub PR，修复发现的问题并推送更改。调用方式为 /review-pr 456，其中 456 是 PR 编号。

修复问题

commands/fix-issue.md——接收一个 GitHub 问题并完全自主地完成它：研究、规划、实施、测试、创建 PR、与并行代理进行自我评审、修复自身发现的问题，并在完成后在问题中留言。调用方式为 /fix-issue 123，其中 123 是问题编号。

合并 Dependabot

commands/merge-dependabot.md——评估并合并仓库中未合并的 Dependabot PR。审计 Dependabot 配置，构建传递依赖图，将重叠的 PR 分批处理，在并行环境中评估每一批（构建、测试、矩阵差距分析），然后按顺序合并通过的 PR，并在合并后再次进行测试。调用方式为 /merge-dependabot trailofbits/algo。

编写技能与代理

技能和代理编码的是专业知识，而非具体流程。命令会执行特定的步骤序列，而技能则教会 Claude 如何思考某一类工作，代理则是您交给其执行任务的专业人员。在设计结构、描述和逐步披露方面，请先阅读 Anthropic 的技能编写最佳实践。

技能会将指令加载到当前会话中。它们是规范、检查清单和决策框架，用于塑造 Claude 处理工作的方式——而不是一步一步的脚本。代理则在自己的上下文窗口中运行，并拥有专门的系统提示。当工作受益于专注的角色定位、会话上下文过于臃肿、需要受限的工具集，或者应该与其他工作并行运行时，就应使用代理。

安全工作的代理角色。“曾对数百个可重入漏洞进行分类的高级审计员”与“考虑覆盖率和崩溃分类的模糊测试工程师”的代码审查方式截然不同。系统提示不仅决定了代理遵循哪些步骤，还影响了它会注意到什么以及优先处理哪些内容。如果您在某一类漏洞或分析方法上拥有深厚的专业知识，那就将其编码为代理角色，而不仅仅是技能检查清单。

**工具。**来自 claude-plugins-official 的 plugin-dev 插件提供了相应的流程。/plugin-dev:skill-development 引导您完成技能开发的 6 步流程。/plugin-dev:agent-development 则针对代理开发提供相同的支持。对于包含多个组件的完整插件，可以使用 /plugin-dev:create-plugin 来统筹整个流程。

**质量。**对于安全相关的技能和代理，不要仅仅描述工作流程。应将使其达到专家水平的参考资料一并打包：分析检查清单、漏洞模式、示例输出以及经验丰富的审计员会采用的决策逻辑。保持 SKILL.md 简洁（不超过 2,000 字），并将详细内容移至 references/ 文件中。

发布技能

发布位置取决于目标受众：

• 面向公众和开源社区——向 trailofbits/skills 提交 PR。
• 仅限 Trail of Bits 内部使用——向 trailofbits/skills-internal 提交 PR。
• 希望获得批准的第三方技能——向 trailofbits/skills-curated 提交 PR，并注明原始来源。所有 PR 都将经过代码审查。

推荐技能

技能来自您通过 Trail of Bits 市场和其他第三方市场安装的插件。以下是每个市场中值得关注的技能。

Trail of Bits (trailofbits/skills)

用于安全审计、代码分析和开发工作流。随 Trail of Bits 市场自动安装。

技能	作用	使用场景
ask-questions-if-underspecified	在开始工作前提出1–5个有针对性的澄清问题	任何描述不明确的需求——防止构建错误的内容
modern-python	使用 uv、ruff、ty、pytest、prek 配置项目	新的 Python 项目，或从 pip/Poetry/mypy/black 迁移时
audit-context-building	使用第一性原理和“五个为什么”方法逐行分析代码	在进行审计前深入理解不熟悉的代码
differential-review	以安全性为中心的代码变更评审，并进行影响范围分析	审查对安全性有重要影响的 PR 或提交

Superpowers (obra/superpowers)

强调工作流纪律——在编码前强制规划、结构化调试，并在宣布完成前进行验证。这些技能环环相扣：头脑风暴 → 计划 → 执行 → 验证。

技能	作用	使用场景
/superpowers:brainstorm	通过苏格拉底式提问完善想法后再实施	开始任何非 trivial 功能时——及早发现需求不明确的问题
/superpowers:systematic-debugging	结构化的四阶段根本原因分析	任何难以确定原因的 bug——防止只治标不治本

Anthropic 官方 (anthropics/claude-code/plugins)

由 Claude Code 仓库维护的官方插件。可通过 claude-plugins-official 市场安装。

技能	作用	使用场景
frontend-design	在前端任务中自动调用，提供大胆设计、排版、动画和视觉润色方面的指导——避免千篇一律的 AI 风格	构建对视觉质量要求较高的 Web 组件、页面或应用时
/pr-review-toolkit:review-pr	并行运行6个专业代理：评论、测试、错误处理、类型设计、代码质量和代码简化	PR 审查——可选择全部功能，也可单独挑选特定方面（如简化、测试、错误等）

pr-review-toolkit 中的 code-simplifier 代理也可以单独使用，只需调用 /pr-review-toolkit:review-pr simplify 即可进行专注的代码简化。

Compound Engineering (EveryInc/compound-engineering-plugin)

用于规划和评审的多代理工作流。

技能	作用	使用场景
/workflows:plan	将功能描述转化为包含并行研究代理的实现计划	开始涉及多个文件或组件的功能时
/workflows:review	并行运行15个专业评审代理（安全、性能、架构、风格等）	在合并任何重要 PR 之前——能够发现单人评审遗漏的问题

推荐的 MCP 服务器

除了核心的 Context7 和 Exa 服务器（参见 MCP 服务器）之外，以下服务器也值得为特定工作流添加。

服务器	作用	要求
Granola	会议记录和转录	需要 Granola 应用程序的付费套餐
slither-mcp	Slither 静态分析工具，用于 Solidity 智能合约——检测漏洞、生成调用图、映射继承关系、提取函数元数据	Python 3.11+，Solidity 编译器（Foundry/Hardhat）
pyghidra-mcp	无头 Ghidra 反汇编工具——二进制分析、反编译、交叉引用以及基于嵌入向量的语义搜索	需要 Ghidra（设置 GHIDRA_INSTALL_DIR 环境变量）
Serena	通过 LSP 实现跨30多种语言的符号级代码导航与编辑——按符号而非行号查找符号、引用并进行编辑	需要 uv 和特定语言的 LSP 服务器

Claude Code Config 快速上手指南

本指南基于 Trail of Bits 的最佳实践，帮助中国开发者快速配置安全、高效的 Claude Code 开发环境。

环境准备

系统要求

• 推荐系统：macOS（首选）或 Linux
• 终端模拟器：强烈推荐使用 Ghostty，因其原生 GPU 渲染能高效处理 AI 长文本输出，且支持原生分屏。
  • macOS 安装：brew install --cask ghostty
  • Linux 用户请参考官方文档，Windows 用户可暂用 WezTerm。
• 注意：本配置主要针对类 Unix 系统设计。

前置依赖

请确保已安装以下核心工具链。国内用户若遇到 Homebrew 或网络下载缓慢，建议配置相应镜像源或使用代理。

1. 基础工具 (Homebrew)

brew install jq ripgrep fd ast-grep shellcheck shfmt \
  actionlint zizmor macos-trash node@22 pnpm uv

2. Python 工具链 (via uv)

uv tool install ruff
uv tool install ty
uv tool install pip-audit

3. Rust 工具链

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install prek worktrunk cargo-deny cargo-careful

4. Node.js 工具

npm install -g oxlint agent-browser

5. 本地模型支持 (可选) 如需运行本地模型，请安装 LM Studio：

curl -fsSL https://lmstudio.ai/install.sh | bash

安装步骤

1. 克隆配置仓库

获取官方配置文件并进入目录：

git clone https://github.com/trailofbits/claude-code-config.git
cd claude-code-config

2. 初始化配置

启动 Claude Code 并运行内置的配置命令。该命令会自动检测已安装的组件，引导你完成安装，并将相关命令注册到全局，以便在任何目录下使用。

claude

在弹出的会话窗口中输入以下命令：

/trailofbits:config

注：后续若配置更新，再次运行此命令即可同步。

3. 配置 Shell 别名与本地模型

编辑你的 ~/.zshrc (或 ~/.bashrc) 文件，添加以下内容以优化体验：

启用免权限确认模式（需配合沙箱使用）：

alias claude-yolo="claude --dangerously-skip-permissions"

配置本地模型调用（如使用 LM Studio）：

claude-local() {
  ANTHROPIC_BASE_URL=http://localhost:1234 \
  ANTHROPIC_AUTH_TOKEN=lmstudio \
  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
  claude --model qwen/qwen3-coder-next "$@"
}

保存后执行 source ~/.zshrc 生效。

4. 部署全局设置与规范

将推荐的配置文件复制到用户目录，以启用安全策略、状态栏显示及编码规范。

复制设置文件：

cp settings.json ~/.claude/settings.json

说明：此文件包含隐私保护（禁用遥测）、沙箱规则、钩子（Hooks）及 MCP 服务器配置。

复制状态栏脚本：

mkdir -p ~/.claude
cp scripts/statusline.sh ~/.claude/statusline.sh
chmod +x ~/.claude/statusline.sh

复制全局编码规范 (CLAUDE.md)：

cp claude-md-template.md ~/.claude/CLAUDE.md

建议：打开 ~/.claude/CLAUDE.md 根据你的技术栈（如 Python/Node/Rust 偏好）进行微调。

基本使用

启动会话

在任意项目目录下，直接使用以下命令启动增强版的 Claude Code：

claude

或者使用配置的免确认模式（推荐配合沙箱）：

claude-yolo

启用沙箱模式（关键安全步骤）

由于使用了 --dangerously-skip-permissions，务必在会话中启用沙箱以限制文件系统访问权限，防止意外修改系统文件。

在 Claude Code 会话中输入：

/sandbox

效果：此时 AI 执行的命令将被限制在当前项目目录内，且无法读取 ~/.ssh、~/.aws 等敏感凭证。

查看状态

配置完成后，终端底部将显示两行状态栏，包含当前模型、Git 分支、上下文使用率、会话成本及缓存命中率等信息，帮助你实时监控资源消耗。

本地模型测试

如果你配置了本地模型，可通过以下命令测试：

claude-local