Claude Code 最佳实践：怎么让它少走弯路

这篇适合谁、读完能做到什么

用过一段时间 Claude Code、觉得它有时做偏了、或者「说完成了」其实没完成、又或者花的时间和 token 超出预期的人。读完你应该能判断一条信息该写进 CLAUDE.md、写成 skill、还是做成 hook，并知道怎样给它一个能判断对错的检查。^[1]

哪些该交给模型，哪些该写成配置

文档把 Claude Code 的指令分成两类。一类是非确定性的：你写的提示词、CLAUDE.md、skill，模型读了以后自己决定怎么执行。另一类是确定性的：hook、拒绝规则、托管设置，由 Claude Code 这个程序每次都执行。^[1]

大多数情况下，应该让模型自己判断。但如果某件事必须每次都发生或者绝不能发生，就不能只靠一行 CLAUDE.md。文档的提示很实用：如果你在 CLAUDE.md 某一行上一再加强语气，Claude 仍然漏掉，这条规则就该改成 hook。反过来，只是偏好的 hook 也可以删掉，让模型自己权衡。^[1]

怎么告诉 Claude 它看不见的东西

Claude 开始任务时会读代码，所以代码里已经有的东西（目录结构、测试框架、现有组件怎么写）不用特意写下来。文档给的判断方法是问自己两个问题：它能不能从代码里找到这条信息？它会不会真的去找？两个都是「是」，就别写。^[1]

真正该写的是代码里没有的东西：团队在会议上做的决定、只存在某个人脑子里的发布流程、集成测试需要的环境变量。^[1]

CLAUDE.md 每次会话都会加载，每一行都会在每个任务上占用它的注意力，所以要保持简短。文档给的一个例子是这样的：^[1]

# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit
# Conventions
- Use the error helpers in src/lib/errors.ts, never throw raw strings
- src/legacy/ is still live but don't copy its patterns into new code
# Gotchas
- Integration tests need DATABASE_URL set, see .env.example

个人偏好则放进 CLAUDE.local.md，并加入 .gitignore。^[1]

只在某个目录下才有用的规则，可以放进 .claude/rules/，用 paths: 限定，只有在处理匹配的文件时才加载。团队的固定流程（比如发版）适合写成 skill，保存为 .claude/skills/<name>/SKILL.md。如果这个流程有副作用，就在 frontmatter 里加上 disable-model-invocation: true，Claude 就不会自己启动它，只有你输入命令时才运行。^[1]

对于存在别的系统里的信息，比如 issue 或错误看板，有 CLI 的话优先用 CLI，比如 gh。没有 CLI 的就通过 MCP 接入，例如 claude mcp add --transport http notion https://mcp.notion.com/mcp。连接的服务器会把工具名放进上下文，所以要关掉用不上的。^[1]

怎么给 Claude 一个能跑的检查

Claude 觉得做完了就会停下。如果没有任何能给出通过或失败结果的东西，它就只能靠「看起来做完了」来判断。文档建议给它一个检查，比如测试文件、构建的退出码、linter、对比输出和固定样本的脚本，或者和设计稿并排的浏览器截图。拿到通过或失败的结果，它就能自己改、自己跑，直到通过。^[1]

检查可以从松到严地组织：在提示词里写「run the auth tests after, and keep going until they pass」，用 /goal 设一个由另一个模型逐轮核对的条件，用 Stop hook 强制执行，或者用 /code-review 让一个没有看过对话的子代理审改动。^[1]

无论用哪种，都要让它给出证据，比如它跑了什么命令、输出是什么。只说一句「测试都通过了」信息量很小。^[1]

Stop hook 的例子是在 .claude/settings.json 里写 pnpm tsc --noEmit 1>&2 || exit 2。命令返回退出码 2 时，Claude 会被送回去继续干活，stderr 的内容会作为它不能结束的理由交给它，所以类型检查没通过，这一轮就不会结束。^[1]

不能破例的规则怎么强制执行

hook 会在固定的时机运行你的程序，比如工具调用前后、Claude 想结束时、会话开始时。它可以是 shell 命令、向 HTTP 地址发送 POST、调用 MCP 工具，也可以是 prompt 或 agent 类型，但后两种由模型判断，本身也不是确定性的。想真正强制执行，要用 command 或 http 类型。^[1]

把「改完文件要格式化」做成 PostToolUse hook 的例子是：matcher 写 Edit|Write，命令是 f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown "$f"。这样格式化就不再取决于 Claude 记不记得这条规则。^[1]

权限规则也能兜底。deny 规则在任何权限模式下都有效，包括自动模式和 bypassPermissions。文档的例子是 "deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]。但要注意，规则匹配的是工具调用，不是意图：Read 拒绝规则能拦住 cat .env，却拦不住一个自己打开文件的脚本；对某个域名的 WebFetch 拒绝规则，在沙箱没开时也拦不住同一域名的 curl。想在操作系统层面限制文件和网络访问，可以在会话里用 /sandbox 开启沙箱。^[1]

规则写在哪里，决定它管谁：.claude/settings.local.json 和 ~/.claude/settings.json 只属于你自己，.claude/settings.json 和里面的 hook 属于仓库，提交之后所有人都会受其约束。组织的托管设置则不能被个人设置覆盖。^[1]

权限、思考强度和子代理怎么调

任务花的时间、token 或打扰次数超出预期时，才值得调默认设置。文档列出了几个主要旋钮。^[1]

权限方面，手动模式下，每个编辑和命令都要你批准；bypassPermissions 则批准拒绝规则和询问规则没有覆盖到的一切。自动模式介于两者之间，由一个分类器模型逐个判断操作。它会拦下 curl | bash、生产环境部署和迁移、强制推送覆盖别人的工作这类动作。被拦下的动作会出现在 /permissions 的 Recently blocked 里，你可以批准后让 Claude 重试。文档还强调，分类器排在拒绝规则和 PreToolUse hook 之后，所以它们依然管用。^[1]

思考强度用 /effort 调节。/effort high 或 /effort xhigh 适合容易漏掉细节的复杂问题，/effort low 适合来回快速讨论、边看边改的场景。只想让某一条消息深入思考时，在提示里写 ultrathink。^[1]

子代理处理简单的活时，文档建议用 model: haiku。如果在 .claude/agents/ 里定义子代理时只给 tools: Read, Grep, Glob，它就只能读不能改，这个限制由 Claude Code 强制执行。^[1]

无人值守地跑，要先想清楚什么

人不在场时，任何小问题都可能被放大。文档建议在放手之前，把五个问题想清楚：它知道什么叫做完成吗？它能检查自己的结果吗？它被允许改动哪些东西？什么会让它停下？结果送到哪里，谁来签收？^[1]

用脚本调用时，claude -p 运行一次就退出。文档推荐加上 --bare、--allowedTools、--permission-mode dontAsk 和 --max-turns 等参数。一个批量迁移文件的循环大致是这样：claude --bare -p "Migrate $file to the new logger API and commit. Reply OK or FAIL." --allowedTools "Read,Edit,Bash(git add *),Bash(git commit *)" --permission-mode dontAsk --max-turns 20。^[1] 并行任务用 claude -w feature-auth 在新的 worktree 里开会话，避免改动互相干扰。worktree 是全新的检出，.env 这类被 git 忽略的文件不会自动带过去，需要列进 .worktreeinclude。^[1]