# Claude Code 完全指南

> **相关文章**: [The Longform Guide to Everything Claude Code](The-Longform-Guide-to-Everything-Claude-Code.md) | [详细版指南（中文）](The-Longform-Guide-to-Everything-Claude-Code-zh.md)

> **原文地址**: [https://x.com/affaanmustafa/status/2012378465664745795](https://x.com/affaanmustafa/status/2012378465664745795)
>
> **作者配置仓库**: [https://github.com/affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code)

---

我从2025年2月份实验性发布以来就是 Claude Code 的忠实用户，并且和 [@DRodriguezFX](https://x.com/@DRodriguezFX) 一起完全使用 Claude Code 开发了 [Zenith](https://zenith.chat)，赢得了 Anthropic x Forum Ventures 黑客松比赛。

这是我日常使用10个月后的完整配置：技能(skills)、钩子(hooks)、子代理(subagents)、MCP、插件(plugins)，以及真正有效的方法。

---

## 技能和命令 (Skills and Commands)

技能就像规则一样运作，限定在特定的范围和工作流程中。当你需要执行特定工作流程时，它们是提示词的简写形式。

在使用 Opus 4.5 进行长时间编码后，你想清理死代码和多余的 .md 文件？

运行 **/refactor-clean**。需要测试？**/tdd**、**/e2e**、**/test-coverage**。技能和命令可以在单个提示中链接使用。

![链接命令示例](images/chaining-commands.jpg)

我可以创建一个在检查点更新代码地图的技能——这是让 Claude 快速导航你的代码库而不消耗上下文的方法。

**~/.claude/skills/codemap-updater.md**

命令是通过斜杠命令执行的技能。它们有重叠但存储方式不同：

- **Skills（技能）:** ~/.claude/skills - 更广泛的工作流程定义
- **Commands（命令）:** ~/.claude/commands - 快速可执行的提示

```bash
# 技能结构示例
~/.claude/skills/
  pmx-guidelines.md      # 项目特定模式
  coding-standards.md    # 语言最佳实践
  tdd-workflow/          # 带有 README.md 的多文件技能
  security-review/       # 基于清单的技能
```

---

## 钩子 (Hooks)

钩子是基于触发器的自动化，在特定事件发生时触发。与技能不同，它们限定于工具调用和生命周期事件。

**钩子类型**

1. **PreToolUse** - 工具执行前（验证、提醒）
2. **PostToolUse** - 工具完成后（格式化、反馈循环）
3. **UserPromptSubmit** - 当你发送消息时
4. **Stop** - 当 Claude 完成响应时
5. **PreCompact** - 上下文压缩前
6. **Notification** - 权限请求

**示例：长时间运行命令前的 tmux 提醒**

```json
{
  "PreToolUse": [
    {
      "matcher": "tool == \"Bash\" && tool_input.command matches \"(npm|pnpm|yarn|cargo|pytest)\"",
      "hooks": [
        {
          "type": "command",
          "command": "if [ -z \"$TMUX\" ]; then echo '[Hook] Consider tmux for session persistence' >&2; fi"
        }
      ]
    }
  ]
}
```

![运行 PostToolUse 钩子时在 Claude Code 中获得的反馈示例](images/post-tool-use-hook.png)

**专业提示：** 使用 `hookify` 插件通过对话方式创建钩子，而不是手动编写 JSON。运行 **/hookify** 并描述你想要的内容。

---

## 子代理 (Subagents)

子代理是你的编排器（主 Claude）可以委派任务的进程，具有有限的范围。它们可以在后台或前台运行，为主代理释放上下文。

子代理与技能配合良好——能够执行部分技能的子代理可以被委派任务并自主使用这些技能。它们也可以使用特定的工具权限进行沙盒化。

```bash
# 子代理结构示例
~/.claude/agents/
  planner.md           # 功能实现规划
  architect.md         # 系统设计决策
  tdd-guide.md         # 测试驱动开发
  code-reviewer.md     # 质量/安全审查
  security-reviewer.md # 漏洞分析
  build-error-resolver.md
  e2e-runner.md
  refactor-cleaner.md
```

为每个子代理配置允许的工具、MCP 和权限以实现适当的范围控制。

---

## 规则和记忆 (Rules and Memory)

你的 `.rules` 文件夹包含 Claude 应该**始终**遵循的最佳实践 `.md` 文件。两种方法：

1. **单个 CLAUDE.md** - 所有内容放在一个文件中（用户或项目级别）
2. **Rules 文件夹** - 按关注点分组的模块化 `.md` 文件

```bash
~/.claude/rules/
  security.md      # 不硬编码密钥，验证输入
  coding-style.md  # 不可变性，文件组织
  testing.md       # TDD 工作流程，80% 覆盖率
  git-workflow.md  # 提交格式，PR 流程
  agents.md        # 何时委派给子代理
  performance.md   # 模型选择，上下文管理
```

**规则示例：**

- 代码库中不使用表情符号
- 前端避免使用紫色调
- 部署前始终测试代码
- 优先使用模块化代码而非巨型文件
- 永远不要提交 console.logs

---

## MCP（模型上下文协议）

MCP 直接将 Claude 连接到外部服务。它不是 API 的替代品——它是围绕 API 的提示驱动包装器，允许更灵活地导航信息。

**示例**：Supabase MCP 让 Claude 可以拉取特定数据，直接在上游运行 SQL，无需复制粘贴。数据库、部署平台等也是如此。

![Supabase MCP 列出公共 schema 中表的示例](images/supabase-mcp.jpg)

**Chrome in Claude：** 是一个内置的插件 MCP，让 Claude 可以自主控制你的浏览器——点击查看事物如何工作。

***关键：上下文窗口管理***

对 MCP 要挑剔。我在用户配置中保留所有 MCP，但**禁用所有未使用的**。导航到 **/plugins** 向下滚动或运行 **/mcp**。

启用太多工具后，你压缩前的 200k 上下文窗口可能只有 70k。性能会显著下降。

![使用 /plugins 导航到 MCP 查看当前安装的 MCP 及其状态](images/plugins-mcps.jpg)

**经验法则：** 配置中有 20-30 个 MCP，但保持少于 10 个启用 / 少于 80 个活动工具。

---

## 插件 (Plugins)

插件将工具打包以便于安装，而不是繁琐的手动设置。插件可以是技能 + MCP 的组合，或者钩子/工具的捆绑包。

**安装插件：**

```bash
# 添加市场
claude plugin marketplace add https://github.com/mixedbread-ai/mgrep

# 打开 Claude，运行 /plugins，找到新市场，从那里安装
```

![显示新安装的 Mixedbread-Grep 市场](images/mgrep-marketplace.jpg)

**LSP 插件：** 如果你经常在编辑器外运行 Claude Code，特别有用。语言服务器协议为 Claude 提供实时类型检查、跳转到定义和智能补全，无需打开 IDE。

```bash
# 启用的插件示例
typescript-lsp@claude-plugins-official  # TypeScript 智能
pyright-lsp@claude-plugins-official     # Python 类型检查
hookify@claude-plugins-official         # 通过对话创建钩子
mgrep@Mixedbread-Grep                   # 比 ripgrep 更好的搜索
```

与 MCP 相同的警告——注意你的上下文窗口。

---

## 技巧和窍门

**键盘快捷键**

- **Ctrl+U** - 删除整行（比狂按退格键更快）
- **!** - 快速 bash 命令前缀
- **@** - 搜索文件
- **/** - 启动斜杠命令
- **Shift+Enter** - 多行输入
- **Tab** - 切换思考显示
- **Esc Esc** - 中断 Claude / 恢复代码

**并行工作流程**

**/fork** - 分叉对话以并行执行非重叠任务，而不是排队发送消息

**Git Worktrees** - 用于有重叠的并行 Claude 而不产生冲突。每个 worktree 是一个独立的检出

```bash
git worktree add ../feature-branch feature-branch
# 现在在每个 worktree 中运行独立的 Claude 实例
```

**tmux 用于长时间运行的命令：** 流式传输和观看 Claude 运行的日志/bash 进程。

```bash
tmux new -s dev
# Claude 在这里运行命令，你可以分离并重新连接
tmux attach -t dev
```

**mgrep > grep：** `mgrep` 是对 ripgrep/grep 的重大改进。通过插件市场安装，然后使用 **/mgrep** 技能。支持本地搜索和网络搜索。

```bash
mgrep "function handleSubmit"  # 本地搜索
mgrep --web "Next.js 15 app router changes"  # 网络搜索
```

**其他有用的命令**

- **/rewind** - 回到之前的状态
- **/statusline** - 使用分支、上下文百分比、待办事项自定义
- **/checkpoints** - 文件级别的撤销点
- **/compact** - 手动触发上下文压缩

**GitHub Actions CI/CD**

使用 GitHub Actions 在你的 PR 上设置代码审查。配置后 Claude 可以自动审查 PR。

![Claude 批准一个 bug 修复 PR](images/github-actions-pr.jpg)

**沙盒化**

使用沙盒模式进行风险操作——Claude 在受限环境中运行，不会影响你的实际系统。（使用 --dangerously-skip-permissions 做相反的操作，让 claude 自由漫游，如果不小心这可能具有破坏性。）

---

## 关于编辑器

虽然不需要编辑器，但它可以积极或消极地影响你的 Claude Code 工作流程。虽然 Claude Code 可以从任何终端工作，但与功能强大的编辑器配合可以解锁实时文件跟踪、快速导航和集成命令执行。

**Zed（我的首选）**

我使用 [Zed](https://zed.dev)——一个基于 Rust 的编辑器，轻量、快速且高度可定制。

**为什么 Zed 与 Claude Code 配合良好：**

- **Agent Panel 集成** - Zed 的 Claude 集成让你可以在 Claude 编辑时实时跟踪文件更改。无需离开编辑器即可在 Claude 引用的文件之间跳转
- **性能** - 用 Rust 编写，即时打开，处理大型代码库没有延迟
- **CMD+Shift+R 命令面板** - 在可搜索的 UI 中快速访问所有自定义斜杠命令、调试器和工具。即使你只想运行一个快速命令而不切换到终端
- **最小资源使用** - 不会在繁重操作期间与 Claude 竞争系统资源
- **Vim 模式** - 如果你喜欢的话，完整的 vim 键位绑定

![Zed 编辑器使用 CMD+Shift+R 的自定义命令下拉菜单。右下角的靶心显示跟随模式。](images/zed-editor.jpg)

1. **分屏** - 一侧是带有 Claude Code 的终端，另一侧是编辑器
2. **Ctrl + G** - 在 Zed 中快速打开 Claude 当前正在处理的文件
3. **自动保存** - 启用自动保存，这样 Claude 的文件读取始终是最新的
4. **Git 集成** - 使用编辑器的 git 功能在提交前审查 Claude 的更改
5. **文件监视器** - 大多数编辑器会自动重新加载已更改的文件，确认这已启用

**VSCode / Cursor**

这也是一个可行的选择，与 Claude Code 配合良好。你可以使用终端格式，通过 **\ide** 启用 LSP 功能与编辑器自动同步（现在插件有些冗余）。或者你可以选择与编辑器更集成且具有匹配 UI 的扩展。

![来自文档 https://code.claude.com/docs/en/vs-code](images/vscode-extension.jpg)

---

## 我的配置

**插件**

已安装：（我通常一次只启用其中 4-5 个）

```markdown
ralph-wiggum@claude-code-plugins       # 循环自动化
frontend-design@claude-code-plugins    # UI/UX 模式
commit-commands@claude-code-plugins    # Git 工作流程
security-guidance@claude-code-plugins  # 安全检查
pr-review-toolkit@claude-code-plugins  # PR 自动化
typescript-lsp@claude-plugins-official # TS 智能
hookify@claude-plugins-official        # 钩子创建
code-simplifier@claude-plugins-official
feature-dev@claude-code-plugins
explanatory-output-style@claude-code-plugins
code-review@claude-code-plugins
context7@claude-plugins-official       # 实时文档
pyright-lsp@claude-plugins-official    # Python 类型
mgrep@Mixedbread-Grep                  # 更好的搜索
```

**MCP 服务器**

已配置（用户级别）：

```json
{
  "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
  "firecrawl": { "command": "npx", "args": ["-y", "firecrawl-mcp"] },
  "supabase": {
    "command": "npx",
    "args": ["-y", "@supabase/mcp-server-supabase@latest", "--project-ref=YOUR_REF"]
  },
  "memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] },
  "sequential-thinking": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
  },
  "vercel": { "type": "http", "url": "https://mcp.vercel.com" },
  "railway": { "command": "npx", "args": ["-y", "@railway/mcp-server"] },
  "cloudflare-docs": { "type": "http", "url": "https://docs.mcp.cloudflare.com/mcp" },
  "cloudflare-workers-bindings": {
    "type": "http",
    "url": "https://bindings.mcp.cloudflare.com/mcp"
  },
  "cloudflare-workers-builds": { "type": "http", "url": "https://builds.mcp.cloudflare.com/mcp" },
  "cloudflare-observability": {
    "type": "http",
    "url": "https://observability.mcp.cloudflare.com/mcp"
  },
  "clickhouse": { "type": "http", "url": "https://mcp.clickhouse.cloud/mcp" },
  "AbletonMCP": { "command": "uvx", "args": ["ableton-mcp"] },
  "magic": { "command": "npx", "args": ["-y", "@magicuidesign/mcp@latest"] }
}
```

按项目禁用（上下文窗口管理）：

```markdown
# 在 ~/.claude.json 的 projects.[path].disabledMcpServers 下
disabledMcpServers: [
  "playwright",
  "cloudflare-workers-builds",
  "cloudflare-workers-bindings",
  "cloudflare-observability",
  "cloudflare-docs",
  "clickhouse",
  "AbletonMCP",
  "context7",
  "magic"
]
```

这是关键——我配置了 14 个 MCP，但每个项目只启用约 5-6 个。保持上下文窗口健康。

**关键钩子**

```json
{
  "PreToolUse": [
    // 长时间运行命令的 tmux 提醒
    { "matcher": "npm|pnpm|yarn|cargo|pytest", "hooks": ["tmux reminder"] },
    // 阻止不必要的 .md 文件创建
    { "matcher": "Write && .md file", "hooks": ["block unless README/CLAUDE"] },
    // git push 前审查
    { "matcher": "git push", "hooks": ["open editor for review"] }
  ],
  "PostToolUse": [
    // 使用 Prettier 自动格式化 JS/TS
    { "matcher": "Edit && .ts/.tsx/.js/.jsx", "hooks": ["prettier --write"] },
    // 编辑后 TypeScript 检查
    { "matcher": "Edit && .ts/.tsx", "hooks": ["tsc --noEmit"] },
    // 警告 console.log
    { "matcher": "Edit", "hooks": ["grep console.log warning"] }
  ],
  "Stop": [
    // 会话结束前审计 console.logs
    { "matcher": "*", "hooks": ["check modified files for console.log"] }
  ]
}
```

**自定义状态栏**

显示用户、目录、带有脏标记的 git 分支、剩余上下文百分比、模型、时间和待办事项计数：

![我 Mac 根目录中的状态栏示例](images/statusline.jpg)

**规则结构**

```markdown
~/.claude/rules/
  security.md      # 强制安全检查
  coding-style.md  # 不可变性，文件大小限制
  testing.md       # TDD，80% 覆盖率
  git-workflow.md  # 约定式提交
  agents.md        # 子代理委派规则
  patterns.md      # API 响应格式
  performance.md   # 模型选择（Haiku vs Sonnet vs Opus）
  hooks.md         # 钩子文档
```

**子代理**

```markdown
~/.claude/agents/
  planner.md           # 分解功能
  architect.md         # 系统设计
  tdd-guide.md         # 先写测试
  code-reviewer.md     # 质量审查
  security-reviewer.md # 漏洞扫描
  build-error-resolver.md
  e2e-runner.md        # Playwright 测试
  refactor-cleaner.md  # 死代码删除
  doc-updater.md       # 保持文档同步
```

---

## 关键要点

1. 不要过度复杂化——将配置视为微调，而不是架构
2. 上下文窗口很宝贵——禁用未使用的 MCP 和插件
3. 并行执行——分叉对话，使用 git worktrees
4. 自动化重复性工作——用钩子进行格式化、检查、提醒
5. 限定子代理范围——有限的工具 = 专注的执行

---

## 参考资料

- [插件参考](https://code.claude.com/docs/en/plugins-reference)
- [钩子文档](https://code.claude.com/docs/en/hooks)
- [检查点](https://code.claude.com/docs/en/checkpointing)
- [交互模式](https://code.claude.com/docs/en/interactive-mode)
- [记忆系统](https://code.claude.com/docs/en/memory)
- [子代理](https://code.claude.com/docs/en/sub-agents)
- [MCP 概述](https://code.claude.com/docs/en/mcp-overview)

---

**注意**：这只是部分细节。如果大家有兴趣，我可能会发更多关于具体内容的帖子。