wesammustafa/Claude-Code-Everything-You-Need-to-Know 源代码：https://github.com/wesammustafa/Claude-Code-Everything-You-Need-to-Know

Claude Code：你需要知道的一切

Claude Code 的实用指南——从你的第一个提示到多代理自动化、钩子、MCP 和团队工作流。基于清晰的心智模型和真实案例，而非营销。

npm install -g @anthropic-ai/claude-code

适用人群： 正在使用（或即将使用）Claude Code 的开发者。新手可以获得指导路径；高级用户可以获得关于技能、钩子、MCP 和代理团队的深度内容。

🧭 选择你的路径

🧠 何时用什么

Claude Code 的四个扩展点，并列对比：

💡 这四者可以组合使用。大多数精良的工作流会结合 2-3 个。

📚 内容概览

基础 — 什么是 Claude Code？ · 安装 · 提示工程

工作流扩展 — 斜杠命令 · 技能 · 钩子

多代理与集成 — 子代理 · 代理团队 · MCP

生产力与框架 — 努力级别 · 快速模式 · 超级 Claude · BMAD 方法

参考 — 斜杠命令速查表 · 努力级别 · 常见问题 · 更新与弃用 · 延伸阅读

什么是 Claude Code？

Claude Code 是 Anthropic 的官方 CLI，让你在终端中与 Claude 协作。你将其指向一个项目；它读取代码、制定计划、编辑文件、运行命令并提交——全部在提示行中完成。

三件它能做到而聊天 UI 做不到的事：

• 读取你的实际仓库 — 而不是粘贴的代码片段。Claude 能看到你的文件树、运行 grep、跟踪导入，并在真实上下文中给出答案。
• 原地编辑并运行你的测试 — diff 感知的编辑，然后 pytest/vitest/go test 立即验证更改。
• 与你技术栈的其他部分组合 — 斜杠命令、钩子、子代理、MCP 服务器以及你正常的 git/shell 工作流。

如果你用过 Copilot 或 Cursor，可以把 Claude Code 视为它们在“终端中的代理”对应物——相同理念，不同界面，无编辑器锁定。

claude # 在当前仓库中启动一个会话
> explain what this codebase does
> fix the failing test in src/api.test.ts
> open a PR with the changes

Claude Opus 4.7：最新旗舰模型

Claude Opus 4.7 是 Claude 4 系列（2026 年 5 月）的当前旗舰——自适应思考能力更敏锐，长上下文推理更好，工具调用比 Opus 4.6 更可靠，价格不变。200K 上下文（通过 API 可至 1M beta），128K 最大输出。

模型选择快速指南：

→ 完整规格、能力和定价参见 docs/reference/models.md

Claude Code 安装

⏱️ 5 分钟安装。 从零到第一次 AI 辅助提交。

1. 安装

npm install -g @anthropic-ai/claude-code

需要 Node.js 18+。其他安装方式（Homebrew、curl、原生二进制）请参阅官方安装指南（https://docs.anthropic.com/en/docs/claude-code/setup）。

2. 认证

claude

首次运行时，Claude Code 会打开浏览器让你使用 Anthropic 账户登录（Pro、Max 或 API Key 均可）。之后，你可以在 Claude 中随时使用 /auth login 重新认证。

3. 运行你的第一个提示

从任意项目目录：

cd ~/your-project
claude

Claude Code 启动后，尝试以下之一：

• explain what this codebase does — Claude 读取你的仓库并总结。
• add a README section about installation — 基于你的项目生成内容。
• find and fix the failing test in src/api.test.ts — 诊断并原地编辑。

4. （可选）生成 CLAUDE.md

/init

创建一个项目级别的指令文件，Claude 在每个会话中都会读取——你的项目“家规”。更多内容见提示工程深入。

5. （进阶）查看一个真实的 Claude Code 项目配置

本仓库自己的 .claude/ 目录是一个完整配置的 Claude Code 项目的工作示例。将其作为精良配置的参考：

💡 下一步： 熟悉基础后，跳转到Claude 技能，在 3 分钟内构建可复用的斜杠命令。

提示工程深入

📖 Claude 初始化 运行 /init 命令可自动生成 CLAUDE.md 文件。 你的 CLAUDE.md 文件会成为 Claude 提示的一部分，因此应像任何频繁使用的提示一样进行优化。一个常见错误是添加大量内容而不迭代其有效性。花时间实验，确定什么能产生最好的指令遵循效果。

1. 探索 → 计划 → 编码 → 提交

适用于复杂问题的通用工作流。

• 探索： 读取相关文件/图片/URL；使用子代理进行验证。不要开始编码。
• 计划： 让 Claude 制定计划。使用 "think"、"think hard"、"think harder" 或 "ultrathink" 来提示深入思考——关于推理调节，参见努力级别。可选：保存计划以供日后参考。
• 编码： 实现解决方案；边做边验证合理性。
• 提交： 提交结果，创建拉取请求，更新 README/更新日志。
• Claude 有两个默认模式：计划模式 和 接受编辑模式。你可以使用 Shift + Tab 键切换它们。
  • 计划模式
  • 接受编辑模式

💡 专业提示： 对于复杂任务，先进行调研和计划能显著提升性能。

2. 测试驱动工作流（写测试 → 编码 → 提交）

适用于可通过单元/集成测试验证的更改。

• 编写测试： 基于预期输入/输出创建测试；标记为 TDD。
• 运行并让测试失败： 确认它们失败；尚未实现。
• 提交测试： 满意后提交。
• 编写代码： 实现代码使测试通过；通过子代理迭代验证。
• 提交代码： 所有测试通过后最终提交。

🔹 明确的目标（测试、模拟）能提高迭代效率。

3. 视觉迭代（编码 → 截图 → 迭代 → 提交）

• 提供截图或视觉模型。
• 实现代码，截图，迭代直至输出与模型匹配。
• 满意后提交。

🔹 迭代能显著提升输出质量（通常 2-3 轮足够）。

4. 努力级别——Claude 的思考深度

→ 完整指南 docs/reference/effort-levels.md

心智模型： 努力是一个行为调节旋钮，而非令牌预算——它会改变思考深度、工具调用倾向、响应长度以及 Claude 在多步骤工作中坚持的程度。更高 ≠ 更智能；上下文质量往往更重要。

存在 5 个级别（大多数用户误以为只有 4 个）：

当前默认（2026 年 5 月）： Opus 4.7 → xhigh；Opus 4.6 + Sonnet 4.6 → 每次计划使用 high。（关于“Pro/Max 用户被降级到 medium 默认”的传闻在 ~2026 年 3 月至 4 月底是真的，但在 Claude Code v2.1.117 中已修复。用 /effort 检查你的版本。）

设置方式，按持久性排序：

# 仅限当前轮次——添加上下文提示（不改变 API 努力级别）
> ultrathink — design the migration strategy

# 当前会话——不带参数显示滑块，带参数直接设置级别
/effort xhigh
/effort auto # 重置为模型默认

# 所有会话，low/medium/high/xhigh——settings.json
echo '{ "effortLevel": "high" }' > .claude/settings.json

# 所有会话，max——只有环境变量有效
export CLAUDE_CODE_EFFORT_LEVEL=max

⚠️ 三个值得注意的陷阱：

• Anthropic 对 Opus 4.7 max 的官方指导： 在常规工作上 “收益递减并容易过度思考”。不要默认使用。
• "effortLevel": "max" 在 settings.json 中会静默降级——只有 CLAUDE_CODE_EFFORT_LEVEL=max 环境变量能持久保持 max。
• 上下文质量通常比更多努力更重要。 如果你在不该需要 max 的任务上使用它，~80% 的修复在上游——更清晰的 CLAUDE.md、原子计划、指定文件。完整分析→

💡 模式：用 Opus 规划 / 用 Sonnet 执行。 用 Opus xHigh 或 Max 规划；将原子、无歧义的计划交给 Sonnet 以较低努力去执行。Sonnet 能遵循清晰计划而不漂移，因此当计划明确时，低成本执行是可靠的。

Claude 命令

Claude Code 内置约 30 个斜杠命令，同时允许你将自定义命令定义为技能（存储在 .claude/commands/ 中的 markdown 文件）。两者协同工作——内置命令用于常见操作，自定义技能用于团队的特定工作流。

首日必备命令

→ 完整斜杠命令参考见 docs/reference/commands.md（约 30 个命令，包括 /auth、/fast、/hooks、/mcp、/teleport 等）

自定义斜杠命令

将一个常用提示定义为 markdown 文件，之后用 /skill-name 永久调用：

mkdir -p .claude/commands
echo "分析这段代码的性能问题并提出优化建议：" \
> .claude/commands/optimize.md

💡 下一层级： 自定义斜杠命令和技能是同一回事。前往 Claude 技能深入——内置技能、本仓库中的 7 个自定义技能、工作流配方以及如何编写你自己的技能。

Claude 技能

~3 分钟阅读 · 完整指南参见 docs/skills.md →

心智模型： 技能将工作流打包成一个 markdown 文件。两种风格：

• 斜杠技能 — .claude/commands/<name>.md，你用 / 调用
• 代理技能 — .claude/skills/<name>/SKILL.md，带有 YAML 前言；当描述与任务匹配时，Claude 自动调用

⚠️ 安全： 技能是可执行指令，以你的 shell 权限运行。在添加任何第三方技能之前，务必阅读它——就像在 source 一个 shell 脚本之前先审查它一样。

3 分钟内创建你的第一个技能

mkdir -p .claude/commands
cat > .claude/commands/analyze.md << 'EOF'
# 代码分析
分析当前代码中：
- 潜在 bug 和边缘情况
- 性能优化
- 代码质量改进
- 安全漏洞
提供具体、可操作的推荐。
EOF

claude
# 然后输入：/analyze

完成了——一个可用的斜杠技能。之后可以通过将其移动到 .claude/skills/analyze/SKILL.md 并添加 name/description 前言，升级为代理技能。

想要更多深度？

完整的技能指南在 docs/skills.md 涵盖：

• 本仓库 .claude/commands/ 中的 7 个自定义斜杠技能：/pr、/review、/tdd、/test、/five、/ux、/todo
• 2 个内置技能（/keybindings-help、/mermaid）
• 斜杠技能 vs 代理技能——何时使用每种、前言契约、转换路径
• 工作流配方——功能开发与 TDD + PR、bug 调查、UX 优先开发
• 如何编写你自己的技能（文件格式、作用域、示例）
• 技能常见问题、故障排除和最佳实践

超越你自己的技能——生态系统

社区已经构建了数千个代理技能。三个开始浏览的地方：

值得注意的社区技能：skill-creator、skill-installer、mcp-builder、systematic-debugging、pair-programming、github-code-review、pptx、react、frontend-design、prompt-engineering-patterns、superpowers、brainstorming、market-research-reports、senior-data-engineer 以及更多——详情见 docs/skills.md 中的完整生态系统部分，包含分类表和安装路径。

钩子

心智模型： 钩子是 Claude Code 生命周期中可编程的检查点（在工具调用前后、会话启动、提示提交等时刻）。你的脚本检查提议的动作并返回 允许 / 拒绝 / 修改。

T