trailofbits/claude-code-config
GitHub: trailofbits/claude-code-config
一套面向安全审计与代码研究的 Claude Code 最佳实践配置，通过沙盒隔离、Hook 拦截和专用插件将 AI 打造成安全专家。
Stars: 1741 | Forks: 132
# Trail of Bits Claude Code 配置
针对 Trail of Bits 中 Claude Code 的主观默认设置、文档和工作流。涵盖了在安全审计、开发和研究过程中，我们发现有利的沙盒、权限、Hook、技能、MCP 服务器和使用模式。
**首次设置：**
```
git clone https://github.com/trailofbits/claude-code-config.git
cd claude-code-config
claude
```
然后在会话中运行 `/trailofbits:config`。它会引导您安装每个组件，检测您已有的内容，并自动安装命令，以便以后在任何目录下都能运行。更新后请再次运行 `/trailofbits:config`。
## 目录
**[入门指南](#getting-started)**
- [先读这些](#read-these-first)
- [前置条件](#prerequisites)
- [Shell 设置](#shell-setup)
- [设置](#settings)
- [全局 CLAUDE.md](#global-claudemd)
**[配置](#configuration)**
- [沙盒](#sandboxing)
- [Hook](#hooks)
- [插件和技能](#plugins-and-skills)
- [MCP 服务器](#mcp-servers)
- [本地模型](#local-models)
- [个性化](#personalization)
**[使用方法](#usage)**
- [持续改进](#continuous-improvement)
- [项目级 CLAUDE.md](#project-level-claudemd)
- [上下文管理](#context-management)
- [Web 浏览](#web-browsing)
- [快速模式](#fast-mode)
- [命令](#commands)
- [编写技能和代理](#writing-skills-and-agents)
- [推荐的技能](#recommended-skills)
- [推荐的 MCP 服务器](#recommended-mcp-servers)
## 入门指南
### 先读这些
在配置任何内容之前，请先阅读这些资料，以了解此设置为何如此运作的背景：
- [Claude Code 的最佳实践](https://code.claude.com/docs/en/best-practices) -- Anthropic 关于高效使用 Claude Code 的官方指南
- [这是我如何使用 LLM 帮助我编写代码的](https://simonwillison.net/2025/Mar/11/using-llms-for-code/) -- Simon Willison 关于实用 LLM 辅助编码技术
- [面向不能只靠直觉的团队的 AI 辅助编码](https://blog.nilenso.com/blog/2025/05/29/ai-assisted-coding/) -- Nilenso 为具有高标准的团队集成 AI 工具的实战手册
- [我的 AI 怀疑论朋友都疯了](https://fly.io/blog/youre-all-nuts/) -- Thomas Ptacek 谈为什么 dismissing LLMs 进行编码是一个错误
- [Harness 工程](https://openai.com/index/harness-engineering/) -- OpenAI 谈在零手写代码的情况下构建产品
### 前置条件
#### 终端：Ghostty
使用 [Ghostty](https://ghostty.org)。这是最适合 Claude Code 的终端，因为它使用原生的 Metal GPU 渲染，因此能够处理长时间 AI 会话的大量文本输出，而不会出现卡顿或内存膨胀（两个 VS Code 终端会话约为 ~8GB，而它只需约 ~500MB）。Shift+Enter 和组合键开箱即用，无需 `/terminal-setup`。内置的分割面板（Cmd+D / Cmd+Shift+D）允许您在运行 Claude Code 的同时运行开发服务器，而无需使用 tmux，并且它在长时间的自主运行期间从不崩溃。
```
brew install --cask ghostty
```
仅限 macOS。在 Linux 上，请参阅 [Ghostty 安装文档](https://ghostty.org/docs/install/binary#linux-(official))。尚不支持 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（用于[本地模型](#local-models)）：
```
curl -fsSL https://lmstudio.ai/install.sh | bash
```
这将安装 `lms`（CLI）和 `llmster`（无头守护程序）。如果您偏好 GUI，可以安装 [LM Studio 桌面应用](https://lmstudio.ai/download)。
### Shell 设置
添加到 `~/.zshrc`：
```
alias claude-yolo="claude --dangerously-skip-permissions"
```
`--dangerously-skip-permissions` 会绕过所有权限提示。这是实现 Claude Code 最大吞吐量的推荐运行方式 -- 将其与沙盒配合使用（见下文）。
如果您正在使用[本地模型](#local-models)，还需添加：
```
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 的遥测 ping。在您通常会运行 `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` 启用[多代理团队](https://code.claude.com/docs/en/agent-teams)，其中一个会话协调具有独立上下文窗口的多个队友。实验性功能 -- 在会话恢复和任务协调方面存在已知限制。
- **`enableAllProjectMcpServers: false`** -- 这是默认设置，显式声明以免被意外反转。项目 `.mcp.json` 文件存在于 git 中，因此受损的仓库可能会附带恶意的 MCP 服务器。
- **`alwaysThinkingEnabled: true`** -- 在不同会话之间保持[扩展思维](https://code.claude.com/docs/en/common-workflows#use-extended-thinking-thinking-mode)。使用 `Option+T` 可针对单次会话切换。这会在简单任务上增加延迟和成本；但对于复杂推理来说非常值得。
- **`permissions`** -- 阻止读取凭据/密钥和编辑 shell 配置的拒绝规则（参见[沙盒](#sandboxing)）
- **`cleanupPeriodDays: 365`** -- 将对话历史保留一年，而不是默认的 30 天，这样 `/insights` 就有更多数据可用
- **`hooks`** -- 两个针对 Bash 的 `PreToolUse` Hook，用于阻止 `rm -rf` 和直接推送到 main 分支（参见 [Hook](#hooks)）
- **`statusLine`** -- 指向状态栏脚本（见下文）
#### 状态栏
终端底部的两行状态栏：
```
[Opus 4.6] 📁 claude-code-config │ 🌿 main
████⣿⣿⣿⣿⣿⣿⣿⣿ 28% │ $0.83 │ ⏱ 12m 34s ↻89%
```
第 1 行显示模型、当前文件夹和 git 分支。第 2 行显示可视的上下文使用条（颜色编码：绿色 <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.md` 文件为每个 Claude Code 会话设置默认指令。它涵盖了开发理念（不做推测性功能、不过早抽象、替换而不废弃）、代码质量硬限制（函数长度、复杂度、行宽）、特定语言的工具链，如 Python (`uv`, `ruff`, `ty`)、Node/TypeScript (`oxlint`, `vitest`)、Rust (`clippy`, `cargo deny`)、Bash 和 GitHub Actions，以及测试方法、代码审查顺序和工作流约定（提交、Hook、PR）。
将模板复制到指定位置：
```
cp claude-md-template.md ~/.claude/CLAUDE.md
```
根据您自己的偏好进行审查和自定义。该模板带有强烈的主观色彩 -- 请调整语言部分、工具选择和硬性限制以匹配您的技术栈。有关 CLAUDE.md 文件工作原理的背景信息（层次结构、自动记忆、模块化规则、导入），请参阅[管理 Claude 的记忆](https://code.claude.com/docs/en/memory)。
## 配置
### 沙盒
在 Trail of Bits，我们在绕过权限模式 (`--dangerously-skip-permissions`) 下运行 Claude Code。这意味着您需要了解您的沙盒选项 -- 代理将在不询问的情况下执行命令，因此沙盒是防止它造成破坏的关键。
#### 内置沙盒 (`/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 的[工程博客文章](https://www.anthropic.com/engineering/claude-code-sandboxing)。有关完整的配置参考，请参阅[沙盒文档](https://code.claude.com/docs/en/sandboxing)。
#### Devcontainer
要实现完全的读写隔离，请使用 devcontainer。代理在一个只挂载了项目文件的容器中运行 -- 它无法访问您的主机文件系统、SSH 密钥、云凭据或容器外的任何其他内容。
- [trailofbits/claude-code-devcontainer](https://github.com/trailofbits/claude-code-devcontainer) -- 预配置的 devcontainer，具有 VS Code 集成、预装的 Claude Code 和常用开发工具
#### 远程 Droplet
为了与本地机器完全隔离，请在一次性的云实例上运行代理：
- [trailofbits/dropkit](https://github.com/trailofbits/dropkit) -- 用于管理 DigitalOcean Droplet 的 CLI 工具，具有自动设置、SSH 配置和 Tailscale VPN 功能。创建一个 Droplet，SSH 登录，运行 Claude Code，完成后将其销毁。
### Hook
Hook 是在 Claude Code 生命周期中特定时刻触发的 Shell 命令（或 LLM 提示）。它们是在模型通常不会暂停的决策点与 LLM 交流的一种方式。每个 `PreToolUse` Hook 都是一个说“停下来，想一想”或“别那样做，这样做”的机会。每个 `PostToolUse` Hook 都是一个说“既然你已经这么做了，这是你应该知道的”的机会。每个 `Stop` Hook 都是一个说“你还没完成”的机会。
这比单独的系统提示指令更强大，因为 Hook 会在特定的、上下文相关的时刻触发。CLAUDE.md 中写着“绝不使用 `rm -rf`”的指令可能会被遗忘，或者被上下文压力覆盖。而一个阻止 `rm -rf` 的 `PreToolUse` Hook 每次都会触发，并在决策点显示错误消息。
Hook 并不是安全边界 -- 提示注入可以绕过它们。它们是**在适当时机进行的结构化提示注入**：拦截工具调用、注入上下文、阻止已知的错误模式并引导代理行为。它们是护栏，而不是墙壁。
在实践中，使用它们来：
- **阻止已知的错误模式** -- `rm -rf`、推送到 main、错误的包管理器
- **添加您自己的日志记录** -- 审计轨迹、Bash 命令日志、变更跟踪
- **促使 Claude 继续** -- `Stop` Hook 可以审查 Claude 的最终响应，并在其合理化未完成的工作时强制其继续
- **在决策点注入上下文** -- 写入后 lint 结果、工具前安全警告
指南和示例：[使用 Hook 自动化工作流](https://code.claude.com/docs/en/hooks-guide)
不想手动编写 Hook？[hookify 插件](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/hookify)可以从纯英文生成它们 -- `/hookify 在我使用 rm -rf 命令时警告我`。
#### Hook 事件
| 事件 | 触发时机 | 可否阻止？ |
|-------|---------------|------------|
| `PreToolUse` 在工具调用执行之前 | 是 |
| `PostToolUse` | 在工具调用成功之后 | 否（已运行） |
| `UserPromptSubmit` | 当用户提交提示时 | 是 |
| `Stop` | 当 Claude 完成响应时 | 是（强制继续） |
| `SessionStart` | 当会话开始/恢复时 | 否 |
| `SubagentStart`/`Stop` | 当子代理生成/完成时 | 开始：否，停止：是 |
| `TaskCompleted` | 当任务被标记为完成时 | 是 |
| `TeammateIdle` | 当队友即将闲置时 | 是 |
#### 退出码
| 退出码 | 行为 |
|-----------|----------|
| 0 | 允许操作（解析标准输出以获取 JSON 控制） |
| 1 | 错误，非阻塞（在详细模式下显示标准错误） |
| 2 | 阻塞错误（标准错误作为错误消息反馈给 Claude） |
#### 示例
**阻止模式**（`PreToolUse`，在 `settings.json` 中）：此仓库 `settings.json` 中的两个 Hook 阻止了 `rm -rf`（建议改用 `trash`）和直接推送到 main/master（要求使用特性分支）。两者都通过 `jq` 从标准输入读取 Bash 命令，使用正则表达式进行匹配，并以退出码 2 返回一个错误消息，告诉 Claude 应该怎么做。
**审计日志**（`PostToolUse`）：[`hooks/log-gam.sh`](hooks/log-gam.sh) 展示了如何为 CLI 工具构建审计轨迹。此示例跟踪 GAM (Google Apps Manager) 命令 -- 它使用动词模式列表将每个命令分类为读取或写入，跳过读取，并记录带有时间戳、操作、命令和退出状态的变更。该模式可推广：为任何您想记录变更的 CLI 交换动词列表。将其作为针对 `Bash` 的 `PostToolUse` Hook 接入。
**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 needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
```
在 Linux 上，将命令替换为 `notify-send 'Claude Code' 'Claude needs your attention'`。
**强制使用特定包管理器**（`PreToolUse`）：[`hooks/enforce-package-manager.sh`](hooks/enforce-package-manager.sh) 在使用 `pnpm` 的项目中阻止 `npm` 命令，并告诉 Claude 使用正确的工具。可推广至任何“用 X 不用 Y”的约定。
**反自我合理化门**（`Stop`，提示 Hook）：Claude 有一种倾向，在工作未完成时就宣布胜利。它会为跳过某些事情找借口：“这些问题是原先就有的”、“修复这个超出了范围”、“我会把这些留给后续处理”。基于提示的 `Stop` Hook 通过要求一个快速模型在 Claude 停止之前审查其最终响应是否包含托辞来捕捉这一点。
```
{
"Stop": [
{
"hooks": [
{
"type": "prompt",
"prompt": "You are a JSON-only evaluator. You MUST respond with a single JSON object and NOTHING else. No markdown, no code fences, no explanation, no preamble. Just the raw JSON object.\n\nReview the assistant's final response. Reject if the assistant is rationalizing incomplete work: claiming issues are 'pre-existing' or 'out of scope', saying 'too many issues' to fix, deferring to unrequested 'follow-ups', listing problems without fixing them, or skipping test/lint failures with excuses.\n\nIf any of those patterns apply, respond:\n{\"ok\": false, \"reason\": \"You are rationalizing incomplete work. [specific issue]. Go back and finish.\"}\n\nOtherwise respond:\n{\"ok\": true}"
}
]
}
]
}
```
这里使用的是 `type: "prompt"` 而不是 `type: "command"` -- Claude Code 将 Hook 的提示以及助手的响应发送给一个快速模型 (Haiku)，该模型返回是/否判断。如果被拒绝，`reason` 会作为 Claude 的下一条指令反馈给它，强制其继续。
**重要：** 提示必须明确指示评估器仅以原始 JSON 响应。如果没有这一点，Haiku 会将 JSON 包装在 markdown 代码围栏中或添加解释性文本，这会导致 JSON 解析失败并静默破坏 Hook。提示 Hook 默认有 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](https://github.com/trailofbits/skills) | 我们用于安全审计、智能合约分析、逆向工程、代码审查和开发工作流的公开技能。 |
| [trailofbits/skills-internal](https://github.com/trailofbits/skills-internal) | 自动化利用、Fuzz Harness 生成、特定漏洞类别的分析、Trail of Bits 风格的审计报告撰写、项目评估范围界定、客户交付物和专有工作流。对 Trail of Bits 内部保密。 |
| [trailofbits/skills-curated](https://github.com/trailofbits/skills-curated) | 我们审查并批准使用的第三方技能和外部市场。每次添加都会经过代码审查。 |
关于外部市场（Anthropic 官方、superpowers、compound-engineering 等），请参阅 [skills-curated](https://github.com/trailofbits/skills-curated) -- 它维护了已批准的列表和安装脚本。
#### agent-browser 技能
`agent-browser` CLI（在[前置条件](#tools)中安装）附带了自己的市场，其中包含一个第一方技能，教 Claude 快照/ref 工作流、命令语法、会话管理、身份验证流程、视频录制和代理支持（约 2,000 行参考材料和可重用的 shell 模板）。agent-browser 非常新，尚不在模型的预训练数据中 -- 没有此技能，Claude 将不知道 ref 生命周期或命令 API。
```
/plugin marketplace add vercel-labs/agent-browser
/plugin install agent-browser@agent-browser
```
### MCP 服务器
Trail of Bits 的每个人都应该至少设置 **Context7** 和 **Exa** 作为全局 MCP 服务器。
| 服务器 | 功能 | 要求 |
|--------|-------------|--------------|
| Context7 | 最新的库文档查找 | 无（不需要 API key） |
| Exa | 网页和代码搜索（参见 [Web 浏览](#web-browsing)） | `EXA_API_KEY` 环境变量（Trail of Bits 员工：共享密钥在 1Password 中；外部用户：[在此处获取](https://exa.ai)） |
#### 设置
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](https://lmstudio.ai) 运行本地 LLM 以配合 Claude Code。LM Studio 提供与 Anthropic 兼容的 `/v1/messages` 端点，因此 Claude Code 只需更改 base URL 即可连接。在 macOS 上，它使用 MLX 进行 Apple Silicon 原生推理，这比 GGUF 快得多。
#### 推荐模型：Qwen3-Coder-Next（截至 2026 年 2 月）
[Qwen3-Coder-Next](https://lmstudio.ai/models/qwen3-coder-next) 是一个 80B 的混合专家模型，仅有 3B 活跃参数，专为代理式编码设计。它处理工具使用、长期推理以及从执行失败中恢复。MLX 4 位量化版约为 ~45GB，需要至少 64GB 的统一内存才能在加载时提供可用的上下文窗口。96GB 或更多会比较充裕。
本地模型发展迅速。当此推荐过时时，请查看 [LM Studio 精选模型页面](https://lmstudio.ai/models)，并选择适合您内存容量的顶级编码模型的 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 请求中发送自己的参数。
#### 连接
通过设置 base URL 和身份验证令牌（对于本地服务器，任何字符串都可以）将 Claude Code 指向 LM Studio：
```
ANTHROPIC_BASE_URL=http://localhost:1234 \
ANTHROPIC_AUTH_TOKEN=lmstudio \
claude
```
或者使用 [Shell 设置](#shell-setup) 中的 `claude-local` shell 函数，以避免每次都输入环境变量。
如果 `claude-local` 失败并显示 `The number of tokens to keep from the initial prompt is greater than the context length.` 消息，请尝试禁用自动加载的工具（先尝试 `--strict-mcp-config`，然后再尝试同时使用 `--disable-slash-commands` 和 `--system-prompt "You are a helpful coding assistant."`）。
如果 `claude-local` 失败并显示 `request.thinking.type: Invalid discriminator value. Expected 'enabled' | 'disabled'"`，请添加 `--settings '{"alwaysThinkingEnabled": false}'` 标志。
有关环境变量的完整列表（模型覆盖、子代理模型、流量控制等），请参阅[模型配置文档](https://code.claude.com/docs/en/model-config)。
### 个性化
您可以自定义 Claude 工作时显示的加载动画动词。向 Claude 提问：“在我的设置中，让我的加载动画词汇以黑客为主题”——或者是毁灭战士，或者是星际迷航，或者任何其他主题。
# 使用方法
在阅读本节任何内容之前，请先阅读 Anthropic 的 [Claude Code 最佳实践](https://code.claude.com/docs/en/best-practices)。这是获得良好结果的最重要的资源。以下所有内容均建立在其之上。
## 持续改进
大多数人对 Claude Code 的使用很早就进入了停滞期。您找到了一个有效的工作流，重复它，却从未发现自己错过了什么。解决方法是一个刻意的反馈循环：回顾发生了什么，调整您的设置，让下周从您学到的东西中受益。
每周运行一次 `/insights`。它会分析您最近的会话并揭示模式 -- 什么是有效的，什么是失败的，您的时间花在了哪里。当它告诉您一些有用的东西时，请采取行动：在您的 CLAUDE.md 中添加一条规则，编写一个 Hook 来阻止您不断犯的错误，将重复的工作流提取为技能。每次调整都会产生复利。几周后，您的设置将与默认值大不相同，并针对您的实际工作方式进行了调优。
## 项目级 CLAUDE.md
对于您处理的每个项目，请在仓库根目录添加一个 `CLAUDE.md`，其中包含项目特定的上下文。[全局 CLAUDE.md](#global-claudemd) 设置默认值；项目文件在此基础上叠加该代码库的独特内容。一个好的项目 CLAUDE.md 包括架构（目录树、关键抽象）、构建和测试命令（`make dev`、`make test`）、代码库导航模式（针对您代码库的 ast-grep 示例）、特定领域的 API 和注意事项，以及测试约定。
有关结构良好的项目 CLAUDE.md 的示例，请参阅 [crytic/slither 的 CLAUDE.md](https://github.com/crytic/slither/blob/master/CLAUDE.md)。它在相同全局标准的基础上，叠加了 slither 特定的上下文 -- SlithIR 内部机制、检测器遍历模式、类型处理陷阱。
## 输出风格
在熟悉新代码库时，请启用 **解释性**[输出风格](https://code.claude.com/docs/en/output-styles)（`/output-style explanatory` 或在 `settings.json` 中设置 `"outputStyle": "Explanatory"`）。Claude 在工作时会解释框架和代码模式，在其正常输出旁添加带有推理和设计选择的“★ Insight (洞察)”块。这在审计不熟悉的代码、审查您不常编写的语言或参与客户项目时非常有用。代价是上下文消耗：更长的响应意味着更早的压缩。当您需要速度时，请切换回默认设置。您也可以在 `~/.claude/output-styles/` 中以 markdown 文件的形式[创建自定义风格](https://code.claude.com/docs/en/output-styles)。
## 上下文管理
上下文窗口在会话中是有限且不可替代的。每次文件读取、工具调用和对话轮次都会消耗它。当它填满时，Claude 会自动压缩 -- 总结对话以释放空间。自动压缩是有效的，但存在信息丢失：微妙的决策、错误细节和推理线索每次都会退化。最佳策略是避免需要它。
### 保持会话整洁
**将工作范围限制在一个会话内。** 每个功能、错误修复或调查都应该容纳在单个上下文窗口中。如果任务太大，将其分解成多个部分，并在新的会话中运行每个部分。这是提高质量您可以做的最有效的事情。
一个保持在上下文预算内的会话，比一个压缩了三次才勉强完成的会话产生更好的代码。当您注意到上下文不足时（检查状态栏 -- 绿色 >50%，黄色 >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`）将代码和对话恢复到会话中任何先前的提示处。它们是您的撤销系统 -- 积极使用它们。尝试有风险的方法，因为知道如果行不通您可以回退。
回退菜单中的“Summarize from here (从此处总结)”选项是 `/compact` 的一种更精细的替代方案：它不是压缩所有内容，而是保留早期上下文完整，仅总结占用空间的部分（例如冗长的调试发散）。这以全保真度保留了您的初始指令。
**将研究卸载给子代理。** 子代理（Task 工具、自定义代理）各自拥有自己的上下文窗口。主会话只能看到子代理的摘要，而不是其完整的工作上下文。
有目的地使用此功能：当任务需要阅读大量文档、探索不熟悉的代码或进行会使主会话膨胀的研究时，将其委托给子代理。主会话保持精简并专注于实现，而子代理处理消耗大量上下文的探索。
**对于复杂功能，先访谈，后实施。** 让 Claude 针对该功能（需求、边缘情况、权衡）对您进行访谈，然后将规范写入文件。启动一个新会话来实施该规范。
**将稳定的上下文放在 CLAUDE.md 中，而不是对话中。** 项目架构、编码标准、工具偏好、工作流约定 -- 任何可重用的内容都放在 CLAUDE.md 中。它会在每次会话中自动加载并在 `/clear` 后保留。
如果您需要在会话之间传递上下文，请提交您的工作，将简短计划写入文件，使用 `/clear`，然后通过让 Claude 指向该文件来开始下一个会话。您也可以使用 `claude --continue`（接续上一次会话）或 `claude --resume`（让您从最近的会话中选择）来恢复以前的会话。但是，带有书面交接的全新会话通常比恢复一个陈旧的会话更好 -- 其上下文更清晰，并且提示缓存是热的。
## Web 浏览
Claude Code 有三种与 Web 交互的方式。
### Exa AI (MCP)
语义 Web 搜索，返回干净的、为 LLM 优化的文本。与内置的 `WebSearch` 工具（返回搜索结果链接，Claude 随后必须获取并解析）不同，Exa 返回预先提取并为 LLM 使用而格式化的实际内容。这节省了上下文窗口并产生了更相关的结果。您的 CLAUDE.md 可以指示 Claude 优先使用 Exa 而不是 `WebSearch`。
### agent-browser
通过 CLI 实现无头浏览器自动化。运行自己的 Chromium 实例 -- 它**不**共享您的 Chrome 配置文件、Cookie 或登录会话。这意味着它无法在不从头登录的情况下访问经过身份验证的页面（Google Docs、内部仪表板等）。它的优势在于上下文效率：快照/ref 系统（`@e1`、`@e2`）使用的上下文比发送完整的可访问性树少约 ~93%，因此代理可以导航复杂的多页工作流而不会耗尽其上下文窗口。还支持视频录制和并行会话。
```
agent-browser open # Navigate
agent-browser snapshot -i # Get element refs (@e1, @e2)
agent-browser click @e1 # Click element
agent-browser fill @e2 "text" # Fill input
agent-browser screenshot # Capture screenshot
```
您需要安装第一方技能才能让 Claude 有效地使用 agent-browser -- 请参阅配置中的 [agent-browser 技能](#agent-browser-skill)。
### Chrome 中的 Claude (MCP)
通过 [Chrome 中的 Claude](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) 扩展进行浏览器自动化。在您实际的 Chrome 浏览器内运行，因此它可以访问您现有的登录会话、Cookie 和扩展程序。这是唯一无需重新认证即可与经过身份验证的页面（Gmail、Google Docs、Jira、内部工具）交互的选项。权衡在于它使用屏幕截图和可访问性树来理解页面，这比 agent-browser 的 ref 系统消耗更多的上下文。
### 何时使用哪种方式
| 需求 | 使用工具 |
|------|-----|
| 搜索网络信息 | Exa |
| 在公共页面上自动化多步骤工作流 | agent-browser |
| 与经过身份验证的/内部页面交互 | Chrome 中的 Claude |
| 录制浏览器操作的视频 | agent-browser |
| 检查视觉布局或截图进行分析 | Chrome 中的 Claude |
## 快速模式
`/fast` 切换快速模式。相同的 Opus 4.6 模型，输出速度提升约 ~2.5 倍，每 token 成本增加 6 倍。默认关闭。
快速模式唯一值得使用的时候是**紧张的交互循环** -- 您正在进行实时调试、迭代输出，每一秒的延迟都会消耗您的注意力。如果您即将启动一个自主运行（`/fix-issue`、一个 swarm、任何您会离开的任务），请先将其关闭。代理不会从更低的延迟中受益；您只是在白白烧钱。
如果您确实使用它，请在会话开始时启用。在对话中途切换它会以快速模式的费率重新计算整个上下文的价格，并使提示缓存失效。有关详细信息，请参阅[快速模式文档](https://code.claude.com/docs/en/fast-mode)。
## 命令
自定义斜杠命令是定义参数化过程的 markdown 文件。它们接受参数、运行特定的步骤序列并产生结果。这些是从不断出现在 `/insights` 中的手动工作流中提取出来的 -- 如果您注意到自己在重复相同的多步骤序列，它就是成为命令的良好候选者。
一旦工作流成为命令，代理也可以运行它。使用 `xargs -P` 围绕 `claude -p` 封装一个 shell 脚本，以跨仓库并行分派相同的命令 -- 每个命令都有自己的带有预算上限的无头会话。
```
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`](commands/review-pr.md) -- 使用并行代理（pr-review-toolkit、Codex、Gemini）审查 GitHub PR，修复发现的问题，并推送。使用 `/review-pr 456` 调用，其中 `456` 是 PR 编号。
### 修复 Issue
[`commands/fix-issue.md`](commands/fix-issue.md) -- 接管一个 GitHub issue 并完全自主地完成它 -- 研究、计划、实施、测试、创建 PR、使用并行代理进行自我审查、修复它自己发现的问题，并在完成时对 issue 进行评论。使用 `/fix-issue 123` 调用，其中 `123` 是 issue 编号。
### 合并 Dependabot
[`commands/merge-dependabot.md`](commands/merge-dependabot.md) -- 评估并合并仓库中开放的 dependabot PR。审查 dependabot 配置，构建传递依赖图，批量处理重叠的 PR，并行评估每个 PR（构建、测试、矩阵差距分析），并在合并后重新测试的情况下按顺序合并通过的 PR。使用 `/merge-dependabot trailofbits/algo` 调用。
## 编写技能和代理
技能和代理编码的是专业知识而不是过程。命令运行特定的步骤序列，而技能教导 Claude *如何思考*一类工作，代理则是您将工作交托给的专家。请首先阅读 Anthropic 的[技能编写最佳实践](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)，以获取有关结构、描述和渐进式披露的指导。
**技能**将指令加载到当前会话中。它们是塑造 Claude 处理工作方式（而非分步脚本）的约定、清单和决策框架。**代理**在拥有自己专用系统提示的独立上下文窗口中运行。当工作受益于专注的角色设定、可能会使主会话上下文膨胀、需要受限的工具集或应该与其他工作并行运行时，请使用代理。
**安全工作中的代理角色设定。** 一个“已经分诊过数百个重入漏洞的高级审计员”处理代码的方式不同于一个“思考覆盖率和崩溃分诊的模糊测试工程师”。系统提示塑造了代理注意和优先考虑的内容，而不仅仅是它遵循的步骤。当您在特定漏洞类别或分析方法上拥有深厚的专业知识时，请将其编码为代理角色设定，而不仅仅是技能清单。
**工具。** `plugin-dev` 插件（来自 `claude-plugins-official`）具有针对两者的工作流。`/plugin-dev:skill-development` 将引导您完成一个 6 步的技能创建过程。`/plugin-dev:agent-development` 对代理执行相同的操作。对于包含多个组件的完整插件，请使用 `/plugin-dev:create-plugin` 来编排整个过程。
**质量。** 对于安全技能和代理，不要仅仅描述工作流。捆绑使其达到专家级别的参考材料：分析清单、漏洞模式、示例输出以及经验丰富的审计员会应用的决策逻辑。保持 SKILL.md 精简（2,000 字以内），并将详细内容移至 `references/` 文件中。
### 发布技能
在哪里发布取决于受众：
- **公开且开源** -- 向 [trailofbits/skills](https://github.com/trailofbits/skills) 提交 PR。
- **Trail of Bits 内部** -- 向 [trailofbits/skills-internal](https://github.com/trailofbits/skills-internal) 提交 PR。
- **您希望批准的第三方技能** -- 向 [trailofbits/skills-curated](https://github.com/trailofbits/skills-curated) 提交 PR，并注明原始来源。每个 PR 都会经过代码审查。
## 推荐的技能
技能来自您通过 Trail of Bits 市场和第三方市场安装的插件。以下是每个市场中值得了解的内容。
### Trail of Bits ([trailofbits/skills](https://github.com/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` | 使用第一性原理和 5 Whys 方法进行逐行代码分析 | 在审计前建立对不熟悉代码的深入理解 |
| `differential-review` | 具有爆炸半径分析的安全聚焦代码变更审查 | 在安全影响很重要时审查 PR 或提交 |
### Superpowers ([obra/superpowers](https://github.com/obra/superpowers))
工作流纪律 -- 强制在编码前进行计划、结构化调试以及在宣布完成前进行验证。这些技能串联在一起：头脑风暴 → 计划 → 执行 → 验证。
| 技能 | 功能 | 何时使用 |
|-------|-------------|----------------|
| `/superpowers:brainstorm` | 在实施之前通过苏格拉底式提问完善想法 | 开始任何非平凡的功能时 -- 尽早发现不明确的需求 |
| `/superpowers:systematic-debugging` | 结构化的 4 阶段根本原因分析 | 任何原因不明显的错误 -- 防止只治标不治本 |
### Anthropic 官方 ([anthropics/claude-code/plugins](https://github.com/anthropics/claude-code/tree/main/plugins))
在 Claude Code 仓库中维护的官方插件。通过 `claude-plugins-official` 市场安装。
| 技能 | 功能 | 何时使用 |
|-------|-------------|----------------|
| `frontend-design` | 在前端任务上自动调用，提供关于大胆设计、排版、动画和视觉润色的指导 -- 避免通用的 AI 审美 | 在视觉质量很重要的地方构建 Web 组件、页面或应用程序 |
| `/pr-review-toolkit:review-pr` | 并行运行 6 个专门的代理：注释、测试、错误处理、类型设计、代码质量和代码简化 | PR 审查 -- 使用 `all` 运行或选择特定方面（`simplify`、`tests`、`errors` 等） |
`pr-review-toolkit` 内部的 `code-simplifier` 代理也可以使用 `/pr-review-toolkit:review-pr simplify` 单独调用，进行专注的简化处理。
### Compound Engineering ([EveryInc/compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin))
用于计划和审查的多代理工作流。
| 技能 | 功能 | 何时使用 |
|-------|-------------|----------------|
| `/workflows:plan` | 通过并行研究代理将功能描述转化为实施计划 | 启动涉及多个文件或组件的功能时 |
| `/workflows:review` | 并行运行 15 个专门的代理（安全性、性能、架构、风格） | 在合并任何重要 PR 之前 -- 能捕捉到单人审查遗漏的问题 |
## 推荐的 MCP 服务器
除了核心的 Context7 和 Exa 服务器（参见 [MCP 服务器](#mcp-servers)），这些特定工作流也值得添加。
| 服务器 | 功能 | 要求 |
|--------|-------------|--------------|
| [Granola](https://granola.ai) | 会议笔记和文字记录 | 付费计划的 Granola 应用 |
| [slither-mcp](https://github.com/trailofbits/slither-mcp) | 针对 Solidity 智能合约的 Slither 静态分析 -- 漏洞检测、调用图、继承映射、函数元数据 | Python 3.11+，Solidity 编译器 (Foundry/Hardhat) |
| [pyghidra-mcp](https://github.com/clearbluejar/pyghidra-mcp) | 无头 Ghidra 逆向工程 -- 二进制分析、反编译、交叉引用、通过嵌入进行语义搜索 | Ghidra（`GHIDRA_INSTALL_DIR` 环境变量） |
| [Serena](https://github.com/oraios/serena) | 通过 LSP 在 30 多种语言中进行符号级代码导航和编辑 -- 按符号而非行号查找符号、引用和进行编辑 | `uv`，特定语言的 LSP 服务器 |
标签：AI开发环境, AI智能体, AI编程助手, Claude Code, DevSecOps, GitHub项目, LLM配置, MCP服务器, MITM代理, Trail of Bits, WAF测试, 上下文管理, 上游代理, 个人化设置, 代码安全, 代码审查, 可视化界面, 应用安全, 提示词工程, 插件与技能, 文档与工作流, 服务枚举, 本地模型, 沙箱, 漏洞枚举, 策略决策点, 请求拦截, 逆向工具, 默认配置