Claude Code 从入门到精通指南这是一份关于 Claude Code 终端AI编程助手的实用进阶指南。文章从基础

🚀 Claude Code: 从零到一 🤖

一份实用、循序渐进的指南，教你如何从 Claude Code 中获取真正的价值。每节内容简短、可操作，且前后关联。如果你已了解基础，可以略过前面部分，直接跳转到有趣的地方——后面的章节才是大多数用户未能充分利用的价值所在。

📖 如何阅读本指南

每节末尾都有一个“立即尝试”框。在继续之前请完成练习。光看不练不会让你变快；动手实践才会。

🌱 第一部分 — 零基础

1. 🤖 Claude Code 到底是什么

Claude Code 是一个运行在终端（以及 VS Code、JetBrains 等 IDE 内部）的 AI 编程代理。它可以读取你的代码库、编写和编辑文件、运行 Shell 命令，并在任务上迭代——所有这些都需要你的许可。

三个能为你节省大量困惑时间的思维模型：

它是协作者，不是编译器。 你描述意图；它提出行动方案，并对任何有风险的操作等待你的批准。给它上下文，就像给新同事做简报一样。
它在会话之间是无状态的，但在轮次之间不是。 关闭终端，它会忘记对话。这就是为什么项目记忆文件（CLAUDE.md）存在的原因——为了让重要的内容延续下去。
每个工具调用都是显式的。 读取文件、编辑文件、运行 Shell 命令——这些都是可见的工具调用。如果它做出了你不想要的更改，你可以确切地看到是在哪里。

它不是什么： 一个聊天包装器。Claude Code 拥有丰富的配置面——权限、斜杠命令、子代理、技能、钩子、MCP 服务器——普通用户和高级用户之间的区别几乎完全取决于这些是如何设置的。

2. 📦 安装与首次运行

安装 CLI（一条命令，除了 API 访问外无需设置账户）：

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

验证安装：

claude --version

在项目目录内启动：

cd ~/projects/my-repo
claude

首次运行时，它会引导你完成身份验证。之后，你将看到一个等待输入的交互式提示符。

🔥 立即尝试 安装 Claude Code，cd 进入你拥有的任意项目，然后运行 claude。输入 /help 并阅读整个帮助输出。不要跳过这一步——人们问我的问题中有 30% 都可以通过阅读一次 /help 来解答。

3. 🎯 你的第一个真实任务

不要从“你好，世界”开始。从你真正会问队友的事情开始。

一个好的初始提示词：

为什么这样有效： 它是有边界的、只读的，并迫使 Claude 探索代码库——这也是你将了解它拥有哪些工具的方式。

观察会发生什么：

它通过“Bash”工具运行 ls
它可能会查看几个关键文件
它用文字回答

你会看到工具调用滚动而过。每一个都是具体的操作。这种透明性就是关键所在——你不是在信任一个黑盒。

现在尝试一些主动的操作：

在仓库根目录添加一个 CHANGELOG.md，包含“Keep a Changelog”模板和一个“未发布”部分。

它会请求许可来写入文件。同意。查看它产生的差异。让它做一些微不足道的修改（“在顶部添加一个指向 keepachangelog.com 的链接”）。注意它是如何原地编辑而不是重写整个文件的。

🔥 立即尝试 在真实仓库中挑选一个真实的小任务——不是玩具项目——然后让 Claude Code 从头到尾完成它。比如“写一个将所有 .jpg 重命名为 .png 的脚本”或“重构这个函数以使用 async/await”。审查每一个工具调用。拒绝一个你不喜欢的地方，然后看它如何调整。

4. ⌨️ 界面

主要命令（在提示符下输入这些）

命令	作用
`/help`	完整的命令参考
`/clear`	清除对话——在不退出的情况下重新开始
`/model`	在模型之间切换（Opus / Sonnet / Haiku）
`/init`	为当前项目引导生成一个 CLAUDE.md 文件
`/status`	显示当前模式、令牌使用情况等
`/review`	审查当前分支的更改
`/compact`	手动压缩对话上下文以释放空间
`Esc`	中断 Claude 正在执行的操作
`Shift+Tab`	循环切换权限模式（普通 → 自动接受 → 计划）

权限模式（最需要理解的一个功能）

Claude Code 有三种主要模式，你会在它们之间切换：

普通模式 — Claude 在每次未被预先批准的调用前都会询问。安全的默认设置。
自动接受模式（或称“YOLO 模式”或“接受编辑”）— Claude 运行时不询问。当你信任任务并希望速度快时使用。切勿在你关心的仓库上用于破坏性或网络化操作。
计划模式 — Claude 进行探索和推理，但在你批准计划之前无法修改任何内容。用于任何非平凡的任务。这是大多数人忽略的、最大的省时法宝。

使用 Shift+Tab 循环切换。当前模式显示在状态区域。

中断

如果 Claude 正走向错误的方向，按 Esc 键。不要等它完成后再抱怨——在半空中重定向。它能很好地处理中断。

🔥 立即尝试

🔧 第二部分 — 学徒

5. 📄 CLAUDE.md

CLAUDE.md 是一个启用了 Claude Code 的仓库中最有价值的单个文件。它是放置在仓库根目录（以及可选地在子目录中）的纯 Markdown 文件，Claude 在每个会话开始时都会阅读它。

把它看作是新工程师的入职文档，只不过这位工程师每天都读它，并且有过目不忘的记忆力。

文件中应包含的内容

架构 — 服务边界、数据流、谁调用谁
如何运行各种事情 — 确切的命令，可复制粘贴运行
代码本身无法告诉你的约定 — “我们更喜欢函数式组件”，“所有错误都必须用 fmt.Errorf 包装”等
陷阱 — 团队以前踩过的坑（“永远不要编辑已应用的迁移”）
常见任务的端到端检查清单（“添加一个功能会按顺序触及这 9 层”）

文件中应省略的内容

任何 ls 或 git log 能回答的问题
叙事性散文、历史记录、愿景
密钥
分步教程（改为链接到它们）

分层

你可以有嵌套的 CLAUDE.md 文件。当 Claude 在子目录内工作时，嵌套的文件也会被加载。在单体仓库中，将其用于特定服务的约定。

repo/
  CLAUDE.md                  # 根目录 — 跨领域上下文
  backend-go/CLAUDE.md       # Go 特定约定
  backend-python/CLAUDE.md   # Python 特定约定
  frontend/CLAUDE.md         # React/TS 特定约定

还有一个 ~/.claude/CLAUDE.md — 应用于你机器上每个项目的个人偏好（例如，“在我的个人脚本中，我更喜欢制表符而不是空格”）。

经验法则

每一行都在竞争上下文预算。像发推文一样对待它——如果删掉一行没有坏处，就删掉。
命令优于说明。 make test-integration 胜过一段关于集成测试的段落。
明确说明约束条件。 “集成测试需要 Docker。” 而不是“我们有集成测试。”
链接，不要重复。 如果你的风格指南在其他地方，就链接到它。

🔥 立即尝试 在你的项目中运行 /init。Claude 会扫描代码库并为你起草一个 CLAUDE.md。然后批判性地阅读它，并删除一半的内容。简短的版本通常更好。将其提交。

6. 🔐 权限

默认情况下，Claude 在运行任何 Shell 命令或编辑任何文件之前都会询问。这是安全的，但中断频繁。

在你的仓库中创建 .claude/settings.json：

{
  "permissions": {
    "allow": [
      "Bash(go test:*)",
      "Bash(pnpm test:*)",
      "Bash(npm run build:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)"
    ],
    "deny": [
      "Bash(sudo:*)",
      "Bash(rm -rf /:*)",
      "Bash(git push --force:*)"
    ]
  }
}

模式规则

Bash(cmd:*) — 允许 cmd 后跟任意参数
Bash(cmd arg1:*) — 允许 cmd arg1 后跟任意内容
Bash(cmd) — 仅精确匹配
deny 总是优先于 allow

个人配置与团队配置

.claude/settings.json — 提交，与团队共享
.claude/settings.local.json — 被 git 忽略，个人调整（你最喜欢的 CLI、本地环境）
~/.claude/settings.json — 全局，应用于你机器上的每个项目

黄金法则

切勿全盘允许 Bash(*)。权限提示的代价是廉价的；一条你没打算运行的破坏性命令的代价是昂贵的。保持拒绝列表严格且具有攻击性。

🔥 立即尝试 回顾你上次的 Claude Code 会话。你批准了三次或以上的命令是哪些？这些是你加入允许列表的候选命令。将它们添加到 .claude/settings.json 并提交。不要添加你只批准过一次的命令——过早地加入允许列表是人们意外地交出过多控制权的方式。

7. 🗺️ 计划模式

对于任何比“重命名这个变量”更复杂的任务，在开始之前按 Shift+Tab 直到进入计划模式。然后提示：

规划一下为 /api/login 端点添加速率限制需要做些什么。不要做任何更改——只提出计划。

Claude 将进行探索、阅读代码、思考，并产出一个具体的计划（要接触的文件、操作顺序、权衡）。你审查计划，提出后续问题，调整方法。当你满意时，退出计划模式并告诉它执行。

这个模式能捕获大量的“Claude 擅自行动并做错了事”的问题。五分钟的规划可以节省一小时的返工。

何时跳过计划模式

琐碎的编辑（修复拼写错误、单行更改）
“错误方向”没有代价的任务（探索性原型开发）
当你已经处于详细的提示-响应循环中并且已对齐时

何时始终使用计划模式

任何涉及超过 3 个文件的更改
任何迁移或重构
任何涉及外部系统（API、数据库、部署）的任务
任何你会仔细审查 PR 的事情——如果需要审查，就需要先有计划

🔥 立即尝试 从你的待办事项列表中挑一个你一直在推迟的真实任务。进入计划模式。要求一个计划。批判性地阅读它。你会发现要么 (a) 计划揭示任务比你想象的要大——这是有用的信息——要么 (b) 你现在已经准备好自信地执行。

8. 🧹 上下文卫生

最被低估的技能。长时间的对话会累积无关的上下文，这会降低 Claude 的注意力并消耗你的令牌预算。

规则

为不相关的任务开始一个新会话。 不要用同一个对话来修复 bug、添加功能，然后写发布说明。
积极使用 /clear。 当你转移焦点时，清除对话。重新解释的代价通常小于携带累积噪音的代价。
不要粘贴巨大的日志。 如果完整的堆栈跟踪有 2000 行，粘贴前 20 行，让 Claude 在需要时再要求更多。
委派搜索。 “找到每个使用 X 的地方”是子代理（在第 3 部分中介绍）的工作，而不是你的主对话。子代理可以消化大量的搜索输出并返回一个简短的摘要，保持你的主上下文清洁。
当上下文填满时使用 /compact。 它会总结历史并用更少的臃肿继续。比让自动压缩在任务中途启动要好。

上下文被污染的迹象

Claude 犯了它之前已经纠正过的同一个小错误
它引用了与当前任务完全无关的文件
它提出的解决方案与你已经设定的约束相矛盾
回答感觉笼统且含糊其辞

当你看到这些迹象时，/clear 几乎总是正确的选择。

🔥 立即尝试 下次你完成一个任务后，在开始新任务之前，运行 /clear。培养这个习惯。大多数人让对话永远持续下去，然后奇怪为什么 Claude 会随着时间的推移变得更糟。

⚡ 第三部分 — 熟练工

9. ⚡ 斜杠命令

斜杠命令是 .claude/commands/ 目录下的一个 Markdown 文件，它成为一个可调用的快捷方式。文件内容成为提示词；$ARGUMENTS 会被你在命令名称后输入的任何内容替换。

最小示例

.claude/commands/review.md：

审查此分支上未提交的更改。


- 安全问题（注入、XSS、不安全的反序列化）
- 会破坏调用方的 API 契约变更
- 新代码路径缺少测试
- 未使用的导入、死代码

不要修改文件——仅审查。输出一个要点清单。

使用 /review 调用。

带参数示例

.claude/commands/test.md：

为指定的服务运行测试套件。参数：$ARGUMENTS

规则：
- 如果参数是 "go"： `cd backend-go && go test ./... -race -count=1`
- 如果参数是 "python"： `cd backend-python && uv run pytest -v`
- 如果参数是 "frontend"： `cd frontend && pnpm test`
- 如果参数是 "all" 或为空：运行所有三个，在第一个失败时停止

使用 /test go 或 /test all 调用。

前置元数据（可选）



步骤：
1. 确保分支已推送
2. 读取从分叉出 main 分支后的提交
3. 根据提交起草 PR 标题和正文
4. 使用起草的内容运行 `gh pr create`
5. 如果存在 $ARGUMENTS，将 "Closes #$ARGUMENTS" 添加到正文

注意事项

扁平命名空间。 .claude/commands/git/commit.md 变成 /commit，而不是 /git:commit。仔细命名文件。
Markdown 文件本身不执行代码——文件内容作为提示词发送。然后 Claude 决定运行什么。
保持它们专注。 如果一个命令试图做太多事情，就拆分它。

斜杠命令 vs 技能 vs 子代理

	使用场景
斜杠命令	用户显式触发一个工作流（`/test`，`/lint`，`/pr`）
技能	Claude 应在相关时自动应用的可重用过程（用户不输入它）
子代理	你想要一个隔离的上下文/全新的对话来处理一个大的子任务

🔥 立即尝试 找出你最常输入的三个提示词。将每个转换成一个斜杠命令。你会立即感受到生产力的提升。

10. 🤝 子代理

子代理是在一个单独的对话中运行的专用 Claude 实例，拥有自己的系统提示和工具权限。主代理将工作委派给它们。

为什么这很重要：

上下文隔离。 子代理看不到你的主对话。非常适合独立审查——它不会被你之前的推理所影响。
并行性。 主代理可以同时运行多个子代理。完美适用于“独立检查 A、B 和 C”。
工具范围限定。 一个“审查者”子代理可以被赋予只读工具，这样即使被要求，它也不能写入文件。

定义子代理

创建 .claude/agents/migration-reviewer.md：



你是一个数据库迁移安全审查者。对于 `backend-go/migrations/` 下的任何迁移，检查：

1. 它是否同时有 Up 和 Down 块？
2. 是否添加了带默认值的 NOT NULL 列，或者是否有回填步骤？
3. 索引是否在大表上以 CONCURRENTLY 方式创建？
4. 是否有任何不可逆的操作（DROP COLUMN, DROP TABLE）需要回滚计划？

将发现报告为一个要点清单。不要修改文件。

现在，只要迁移发生变化，主代理就会自动调用这个子代理（因为“主动使用”这个措辞）。

内置代理类型

Claude Code 附带了一些内置代理类型，你无需自己定义即可使用：

Explore — 快速的代码库搜索，非常适合“找到每个使用 X 的地方”
general-purpose — 默认类型，用于任何研究任务

何时使用子代理

会产生大量你不想放在主上下文中的输出的研究/探索
你想要无偏见第二意见的独立审查
可并行化的工作——三个互不依赖的问题

何时不使用子代理

小型、有针对性的任务 — 产生子代理有开销；对于一个 30 秒的任务，直接自己做
你想要保持对话的任务 — 子代理返回一条消息后就消失了；你无法与其迭代

🔥 立即尝试 下次你需要了解代码库中一个不熟悉的区域时，提示主代理：“生成一个 Explore 子代理，找到所有调用 authenticate() 的地方、它返回的内容、以及谁处理了它的错误。给我一份简短的报告。”注意你的主上下文如何保持清洁。

11. 💡 技能

技能是 Claude 在相关时加载的可重用过程。与斜杠命令（用户触发）或子代理（全新上下文委派）不同，技能将过程性知识分层到你当前的对话中。

目录布局

.claude/skills/
  release-notes/
    SKILL.md          ← 必需
    template.md       ← 可选的支持文件
    scripts/
      extract.sh      ← 可选的辅助脚本

SKILL.md 格式



# 发布说明技能

当被调用时：

1. 找到最后一个标签： `git describe --tags --abbrev=0`
2. 运行 `git log <tag>..HEAD --pretty=format:'%h %s (%an)' --no-merges`
3. 按约定式前缀（feat/fix/chore/docs/refactor）分组提交
4. 使用此技能目录中的 `template.md` 进行格式化
5. 输出最终的 Markdown — 除非被要求，否则不写入文件

自动发现

Claude 在会话开始时读取每个可用技能的描述。当你的提示词与某个技能的描述匹配时，它会自动被调用。

这就是为什么描述比技能中的任何其他东西都重要。像触发器一样编写它：何时应该触发？

错误示例： “发布说明生成器。”
正确示例： “从上个 git 标签以来的提交生成发布说明。当用户要求变更日志、发布说明或自 vX.Y.Z 以来的更改摘要时调用。”

技能 vs 斜杠命令 — 快速判断法则

问：“用户会显式地输入 /技能名称 吗？”

是 → 制作成斜杠命令
否，但 Claude 应该在特定情况出现时应用它 → 制作成技能

内置技能

Claude Code 附带了几个内置技能（update-config, simplify, pr, lint, test, gen, build, migrate, review, security-review 等）。运行 /help 查看当前注册了哪些技能。

🔥 立即尝试 挑选一个你的团队例行执行的过程——发布一个版本、编写一个迁移、审计一个功能——并将其转化为一个技能。精心编写描述，以便 Claude 能自动调用它。

12. 🪝 钩子

钩子是框架（而不是 Claude）响应事件而运行的 shell 命令。它们在 Claude 的决策循环之外运行，这使得它们成为以下任务的正确工具：

强制性地执行某事（编辑后自动格式化）
注入上下文（会话开始时显示分支名称）
阻止不安全操作（拒绝写入 /etc/）

一个像“总是格式化 Go 文件”这样的记忆指令是建议性的——Claude 可能会忘记。钩子是一个硬性保证。

结构

钩子位于 .claude/settings.json 中：

{
  "hooks": {
    "<事件名称>": [
      {
        "matcher": "<匹配模式>",
        "hooks": [
          { "type": "command", "command": "<shell 命令>" }
        ]
      }
    ]
  }
}

你会实际使用的事件

事件	触发时机
`PreToolUse`	在工具运行之前。退出代码 2 会阻止它。
`PostToolUse`	在工具成功之后。适用于自动格式化。
`UserPromptSubmit`	在用户发送提示词之后。可以注入上下文。
`SessionStart`	会话启动时。
`Stop`	Claude 轮次结束时。

退出代码和 I/O

0 — 成功；stdout 成为 Claude 的上下文
2 — 阻止；stderr 会作为重试/调整的原因展示给 Claude
其他 — 非阻塞错误；记录并忽略

钩子通过 stdin 接收事件负载（JSON）。使用 jq 解析：

file=$(jq -r '.tool_input.file_path // empty')

示例 1 — 编辑后自动格式化

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "file=$(jq -r '.tool_input.file_path // empty'); [[ \"$file\" == *.go ]] && gofmt -w \"$file\"; [[ \"$file\" == *.py ]] && ruff format \"$file\"; true"
          }
        ]
      }
    ]
  }
}

示例 2 — 阻止写入生成的文件

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "file=$(jq -r '.tool_input.file_path // empty'); if [[ \"$file\" == *generated/* ]]; then echo '不要编辑生成的文件——请重新运行代码生成。' >&2; exit 2; fi"
          }
        ]
      }
    ]
  }
}

示例 3 — 会话开始时注入分支信息

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "echo \"分支: $(git branch --show-current)\"" }
        ]
      }
    ]
  }
}

何时钩子是错误的选择

“提醒 Claude 编写测试” → 把它放在 CLAUDE.md 中，而不是钩子
“只有在我说的时才运行测试” → 斜杠命令，而不是钩子
“在情况 Y 下应用过程 X” → 技能，而不是钩子

钩子用于框架必须强制执行的、无论 Claude 决定什么都不例外的事情。

🔥 立即尝试 添加一个 PostToolUse 钩子，在 Claude 编辑了你的项目语言的任何文件后自动格式化该文件。这一个具体的步骤将改善未来的每一个会话。

🏆 第四部分 — 专家

13. 🔌 MCP 服务器

模型上下文协议（MCP，Model Context Protocol）服务器通过外部工具扩展 Claude——例如 Slack、Linear、Sentry、Postgres、你的内部 API。在 .claude/settings.json 中配置它们：

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgres://dev:dev@localhost:5432/app"]
    }
  }
}

流行的服务器：postgres, github, slack, linear, sentry, puppeteer, fetch。请参阅 MCP 服务器目录。

在添加 MCP 服务器之前，先问： “一个 Shell 命令能解决问题吗？” 在你权限允许列表中的一个 psql 调用，在 90% 的情况下比一个 Postgres MCP 服务器更简单。MCP 在以下情况下是正确的选择：

该工具需要有状态的认证（OAuth 流程、会轮换的 API 密钥）
输出是结构丰富的（JSON API，Claude 需要字段级访问权限）
你希望 Claude 在许多轮次中调用该工具而无需重新建立连接

如果你添加 MCP 服务器是因为“我看到一个针对 X 的”，请检查 curl、gh、psql 或 aws 是否已经解决了问题。

14. ✍️ 为真实工作编写提示词

提示建议通常很泛泛。以下是对 Claude Code 真正重要的内容：

范围明确，上下文清晰
- 错误示例： “修复测试。”
- 正确示例： “修复 backend-go/internal/service/user_test.go 中的不稳定测试。它大约每十次运行就失败一次。最后一次失败的日志在 /tmp/test-output.log。”
- 你预先提供的上下文越多，Claude 需要花费令牌去发现的就越少。
先说明约束，再要求行动
- “不要改变公共 API。”
- “只修改 frontend/src/components/ 下的文件。”
- “如果修复需要超过 50 行更改，就停下来告诉我——不要强行完成。”
- 这些约束能防止一整类“这不是我想要的”结果。
对于任何非平凡的任务，先要求计划（参见第 7 节）。计划模式是免费的；返工是昂贵的。
诚实地对待你的知识水平。
- “我不太了解这个代码库；在我们更改 X 之前，帮我理解一下它。” 比假装知道能产生更好的结果。
对平庸的输出提出反对。
- 如果 Claude 产生了一些能用但并不好的东西，直接说出来：“这能用，但它有三个问题：(a)..., (b)..., (c)...。请修改。” 在重要的事情上不要接受初稿输出。
对于范围严格的任务，使用“一次性完成”的框架。
- “写一个执行 X 的 bash 脚本。一次性完成——不要来回交流。输出整个脚本。” 这比开放式提示能迫使 Claude 做出更彻底的首轮回应。
对于调试，先陈述假设。
- 错误示例： “为什么这个坏了？”
- 正确示例： “我认为这个坏了是因为部署步骤没有等待数据库迁移完成，但我不确定。先验证或反驳这个假设。”
- 假设优先的调试比开放式调查快 3 倍。

15. 👥 团队设置

将 Claude Code 从“每个人使用的工具”转变为“共享的团队资产”是高杠杆率的。以下是检查清单：

提交到仓库

根目录的 CLAUDE.md，在有用的情况下为每个服务也配置
.claude/settings.json — 共享的权限和钩子
.claude/commands/ — 团队的斜杠命令（/test，/lint，/pr，/review，/deploy-staging）
.claude/agents/ — 团队的子代理（审查者、探索者）
.claude/skills/ — 团队的过程（发布说明、迁移审查、值班手册）

被 .gitignore 忽略

.claude/settings.local.json — 个人覆盖设置
.env — 密钥

新工程师入职流程

每个新员工在入职第一天花前 30 分钟：

阅读 CLAUDE.md 和每个嵌套的 CLAUDE.md
浏览 .claude/commands/ — 存在哪些快捷方式
复制 .env.example → .env
运行 make dev（或等效命令）以验证堆栈能启动
将个人批准添加到 .claude/settings.local.json（而不是共享文件）

保持新鲜度

每季度审查 CLAUDE.md。过时的指导比没有指导更糟糕。
每次有人被坑了就添加一个陷阱。事故发生后：“更新 CLAUDE.md？” 应该出现在检查清单上。
修剪。 如果一个斜杠命令一个月没用过，就删除它。如果 CLAUDE.md 增长到超过约 300 行，就拆分它。

16. 🐛 调试 Claude

当事情出错时，问题几乎总是以下之一：

症状	可能的原因	修复方法
Claude 不断要求运行我想预先批准的命令	不在 `permissions.allow` 中，或模式太窄	将 `Bash(cmd:*)` 添加到 `.claude/settings.json`
我的钩子没有触发	错误的事件名称、错误的匹配器或 JSON 格式错误	验证 JSON；重新检查事件名称；单独测试命令
Claude 编辑了文件但跳过了格式化	`PostToolUse` 钩子静默崩溃	钩子命令以 `; true` 结尾
斜杠命令未找到	文件命名冲突（扁平命名空间）	重命名文件；将其直接放在 `.claude/commands/` 中
`~/.claude/CLAUDE.md` 没有被读取	它被读取了——但对于重叠的主题，每个项目的 `CLAUDE.md` 优先级更高	明确拆分：全局的放 `~/.claude`，项目的放仓库中
子代理给出了与主代理不同的答案	这是预期的——它按设计拥有隔离的上下文	如果你想要共享上下文，就不要使用子代理
Claude 在会话之间忘记了	事实只存在于聊天中，不在 `CLAUDE.md` 里	将持久事实移到 `CLAUDE.md`
钩子意外地阻止了每个命令	退出代码 2 是硬阻止	保留退出代码 2 用于真正的阻止；非阻塞使用 0
Claude 不断犯同样的错误	上下文被矛盾的信息污染了	`/clear` 并用明确的约束重新提示
回应笼统且无用	Claude 缺乏回答的上下文	给它一个文件去读取，一个命令去运行，或缩小范围

使用 --debug

使用 --debug 标志运行 Claude Code 以查看详细日志——钩子调用、工具调用、计时。当某些东西在静默地行为不端时，这是必不可少的。

“复述”技巧

当 Claude 产生你不同意的输出时，提示：“向我复述一下你对我要求的理解。” 这通常在几秒钟内就能揭示出具体的误解。比重启争论更经济。

17. 💪 习惯

区分专家和普通用户的一系列习惯。它们都不是秘密。所有这些都需要实践，而不仅仅是学习。

✅ 应做事项

在构建之前先计划。 对于任何非平凡的任务，使用计划模式或要求一个计划。
在接受之前审查每一个差异。 Claude 很快；一个快速但错误的更改仍然是错误的。
积极清除上下文。 为不相关的工作开始新会话。
当你被坑时更新 CLAUDE.md。 下一个人（或未来的你）不应该重复这个错误。
使用子代理进行探索。 保持你的主上下文清洁。
对平庸的输出提出反对。 说“这不太对，因为 X；请修改。”
提交你的 .claude/ 配置。 它是团队基础设施，不是个人配置。
保持拒绝列表具有攻击性，允许列表最小化。 sudo，rm -rf /，git push --force 应该始终被阻止。

❌ 不应做事项

不要全盘允许 Bash(*)。权限提示的代价远小于一次意外破坏性命令的代价。
不要粘贴 2000 行的日志。粘贴相关的 20 行。
不要在重要的事情上接受初稿输出。要迭代。
不要让一个会话永远运行下去。上下文腐烂是真实存在的。
永远不要把密钥放在 CLAUDE.md 或聊天中。
不要在没有特定原因的情况下跳过钩子（--no-verify）。修复真正的问题。
在你使用默认设置一周之前，不要构建精巧的配置。从简单的开始。当你感到痛点时再增加复杂度。

📈 进阶路径

你是普通用户，如果你：输入自由形式的提示，逐个批准所有内容，从不配置任何东西。
你是学徒，如果你：拥有 CLAUDE.md、权限允许列表，并定期使用计划模式。
你是熟练工，如果你：为你的常见工作流拥有斜杠命令，使用子代理进行探索，并且至少有一个钩子来强制执行保证。
你是专家，如果你：将 .claude/ 视为团队基础设施，定期修剪它，并且能意识到何时使用了错误的工具。

📚 延伸阅读

官方文档 — docs.claude.com/en/docs/cla…
MCP 服务器目录 — github.com/modelcontex…

📋 单页总结

如果你什么都不记得，请记住这些：

将持久事实放在 CLAUDE.md 中。保持它紧凑。
在 .claude/settings.json 中预先批准你常用的命令。永远不要 Bash(*)。
在任何非平凡的任务之前使用计划模式（Shift+Tab）。
在不相关的任务之间清除上下文（/clear）。
将你重复的提示词转换成斜杠命令。
为大型搜索和独立审查使用子代理。
为 Claude 应自动应用的过程使用技能。
当你需要一个硬性保证，而不是一个礼貌的建议时，使用钩子。
审查每一个差异。对平庸的输出提出反对。
当你被坑时更新配置——一次，而不是两次。

🚢 愉快交付！FINISHED