Claude Code 完全指南

相关文章: The Longform Guide to Everything Claude Code | 详细版指南（中文）

原文地址: https://x.com/affaanmustafa/status/2012378465664745795 作者配置仓库:

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

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

技能和命令 (Skills and Commands)

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

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

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

链接命令示例

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

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

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

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

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

钩子 (Hooks)

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

钩子类型

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

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

{
  "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 中获得的反馈示例

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

子代理 (Subagents)

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

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

# 子代理结构示例
~/.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 文件。两种方法：

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

~/.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 中表的示例

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

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

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

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

使用 /plugins 导航到 MCP 查看当前安装的 MCP 及其状态

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

插件 (Plugins)

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

安装插件：

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

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

显示新安装的 Mixedbread-Grep 市场

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

# 启用的插件示例
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 是一个独立的检出

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

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

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

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

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

沙盒化

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

关于编辑器

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

Zed（我的首选）

我使用 Zed——一个基于 Rust 的编辑器，轻量、快速且高度可定制。

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

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

Zed 编辑器使用 CMD+Shift+R 的自定义命令下拉菜单。右下角的靶心显示跟随模式。

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

VSCode / Cursor

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

来自文档 https://code.claude.com/docs/en/vs-code

我的配置

插件

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

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 服务器

已配置（用户级别）：

{
  "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"] }
}

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

# 在 ~/.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 个。保持上下文窗口健康。

关键钩子

{
  "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 根目录中的状态栏示例

规则结构

~/.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         # 钩子文档

子代理

~/.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       # 保持文档同步

关键要点

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

参考资料

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

The Shorthand Guide To Everything Claude Code

快速接入

详细介绍