Claude Code 最佳实践

• 为了让命令安全运行而无需您逐一批准，新的终端和 VS Code 会话以自动模式启动，由分类器在任何有风险的操作运行之前进行审查。
• 为了在独立工作并行进行时保持主对话的专注，Claude 会将工作委派给子代理，并且只在必要时与您确认。
• 为了让长会话持续进行而无需您管理，对话会在上下文窗口填满之前自动压缩。

• 只存在于某个人脑子里的部署流程
• 绝不能被读取的文件
• 必须通过才算完成的检查
• 您需要控制在其内的预算

• Claude 构建的东西与您设想的不同，或者它每次会话开始时都要重新发现同一个事实。它缺少无法通过阅读仓库获得的信息。请参阅告诉 Claude 它看不到的信息。
• Claude 说已经完成了，但其实还差一点，这通常是因为它没有办法检查自己的工作。请参阅给 Claude 一个可以运行的检查。
• Claude 做了在这个仓库中绝不应该发生的事，或者跳过了必须始终执行的步骤。仅靠提示词无法保证这两者。请参阅强制执行不允许例外的规则。
• Claude 做对了，但花费的时间、token 或权限提示超出了任务本身的价值。请参阅更改默认设置。

​

确定性指令与非确定性指令

1. 非确定性：您编写指令，由 Claude（模型）读取。这可以是您的提示词、CLAUDE.md 或 skill。然后由模型决定如何处理这些信息。它通常会遵循您的命令，当前模型也很擅长在没有太多上下文的情况下理解您的意图，但并不保证它会遵循您的指令。它仍然可能决定不做某些事，或者做其他事。
2. 确定性：您配置指令，由 Claude Code（harness）必须执行。这可以是 hook、拒绝规则或托管设置。无论模型决定做什么，Claude Code 每次都会应用它。

• 永远不要编辑 src/gen/ 中生成的客户端
• 创建文件后始终运行 license-header 脚本

​

告诉 Claude 它看不到的信息

• 您的团队在会议上做出的决定
• 只存在于某一个人脑子里的部署流程
• 集成测试所需的环境变量

1. 它能通过阅读代码找到这个吗？
2. 它真的会去查找吗？

​

编写具体的提示词

• 文件：输入 @ 和路径，即可在消息中包含文件内容。
• 图像：将设计或错误的屏幕截图粘贴到提示词中。
• 命令输出：从 shell 中通过管道传入，例如 cat error.log | claude -p "what's going on here"。

build the settings page from the mockup. be ambitious: empty and error states, the save flow wired up, keyboard navigation, not just the layout

​

先与 Claude 进行头脑风暴

I want to add rate limiting to the public API but haven't thought it through yet. Interview me until you could write the spec, then write it to SPEC.md.

​

保持 CLAUDE.md 简短

• 如何在这个仓库中确认工作：确切的测试、类型检查和 lint 命令，以及如何运行单个测试文件
• 代码具有误导性的地方：随处可见但新代码不得照搬的旧模式，或者看起来没有被使用但实际在用的目录
• 不在仓库中的决定：团队选定了哪个错误辅助函数、部署如何进行、什么需要迁移审查
• 任何您已经更正过两次的事情

# 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

• /init 会根据您的代码库生成一个初始版本。之后的工作主要是删减行。记忆指南建议保持在 200 行以内。
• /doctor 会针对 Claude 已能从代码中推断出的内容建议删减。
• /doctor prompt-audit 会标记为旧模型编写的指令、指向已不存在文件的指令，或相互矛盾的指令。

​

将规则限定到代码库的某一部分

---
paths:
  - "src/api/**/*.ts"
---
- Validate request bodies with the zod schemas in src/api/schemas/, don't hand-roll checks
- Every new endpoint needs an entry in openapi.yaml, CI fails without it

​

将团队流程放进 skill

---
name: release
description: Cut a new release. Bumps the version, writes the changelog entry, tags it and pushes the tag so CI can publish.
disable-model-invocation: true
---
1. Make sure you're on main with a clean tree. If not, stop and ask.
2. Run `pnpm changeset version` and commit the result.
3. Summarize the PRs merged since the last tag into CHANGELOG.md, one line each, user-facing changes only.
4. Tag `v<new version>` and push the tag. CI publishes from there, never publish from your machine.

​

连接 Claude 需要的工具

claude mcp add --transport http notion https://mcp.notion.com/mcp

​

给 Claude 一个可以运行的检查

• 测试文件
• 构建的退出码
• linter
• 将输出与固定数据进行 diff 对比的脚本
• 放在设计稿旁边的浏览器屏幕截图

• 在提示词中：run the auth tests after, and keep going until they pass。由 Claude 自行决定何时满意。这适用于任何任务，今天就能用，无需设置。
• 作为目标：/goal all tests in tests/auth pass and lint is clean 会设置一个条件，由一个单独的模型在每个轮次之后对照对话进行检查，Claude 会一直工作直到条件满足。您在会话中很少需要亲自使用它。它对长时间的后台运行很重要，在这类运行中，Claude 有时会在仍有未完成事项时以进度总结结束一个轮次，而目标会把它送回去继续工作。
• 作为 Stop hook：Stop hook 会在 Claude 每次尝试结束其轮次时运行您的脚本，如果脚本以退出码 2 退出，就让 Claude 回去继续工作。这一种由 Claude Code（harness）强制执行，因此在类型检查通过或达到阻止上限之前，轮次不会结束。下文有一个示例。
• 由没有编写代码的人检查：在终端中，/code-review 会在一个从未见过您对话的新子代理中审查 diff。它不会被产生代码的推理过程所左右。

​

对照您的规范进行审查

use a subagent to review the rate limiter diff against SPEC.md, check every requirement is implemented and the listed edge cases have tests, report gaps that affect correctness and skip style

​

用 Stop hook 强制执行检查

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
        ]
      }
    ]
  }
}

​

强制执行不允许例外的规则

​

用 hook 强制执行步骤

• shell 命令（常见情况）
• 向 HTTP 端点发送 POST 请求
• 对您某个 MCP 服务器的工具调用
• prompt 或 agent hook，让模型来决定

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\"" }
        ]
      }
    ]
  }
}

​

用权限规则和沙箱限制访问

{
  "permissions": {
    "allow": ["Bash(pnpm tsc --noEmit)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
  }
}

• Read 规则确实能拦截 cat .env，因为 Claude Code 能识别常见的文件读取命令。
• 它无法拦截打开该文件的脚本。
• 针对某个域名的 WebFetch 拒绝规则对指向同一域名的 curl 不起作用，除非启用了沙箱。

​

选择规则适用于谁

• .claude/settings.local.json 和 ~/.claude/settings.json 只属于您自己。当您为某个命令选择 Yes, and don’t ask again 时，Claude Code 会将该规则保存到本地文件中。
• .claude/settings.json 及其中的 hook 属于仓库。一旦您提交它们，它们就会适用于在该仓库中工作的每个人。其中的拒绝规则立即生效。其中的 allow 规则要等到每个人接受该文件夹的信任对话框后才生效，工作区信任也决定了其中的 hook 何时开始在他们的机器上运行。
• 托管设置属于组织。它们来自管理控制台、MDM 或 managed-settings.json 文件，任何个人设置文件都无法覆盖它们，这使它们成为安全团队策略的唯一归宿。如果您是负责设置它们的人，请参阅为您的组织设置 Claude Code。

​

更改默认设置

• 交互式终端和 VS Code 会话以自动模式启动。
• 在大多数套餐和提供商上，它运行 medium effort 的 Claude Opus 5.5。
• 当它认为有理由时，会将工作委派给子代理。
• 随着对话增长，它会压缩对话。

​

更改权限模式

• 手动模式：您需要亲自批准每次编辑和每个非只读命令。安全，但到第十次提示之后，您就开始不看内容直接批准了，而且当您离开键盘时，一切都会停滞。
• bypassPermissions：批准所有未被您的拒绝规则和询问规则覆盖的操作，这只在一次性容器中才有意义。

• curl | bash
• 生产部署和迁移
• 强制推送覆盖他人的工作
• 将敏感数据发送到外部端点
• 看起来是由 Claude 读取的内容而不是由您驱动的操作

{
  "autoMode": {
    "environment": [
      "$defaults",
      "Source control: github.com/example-org and every repo under it",
      "Trusted internal domains: *.internal.example.com"
    ],
    "allow": [
      "$defaults",
      "Deploying to the staging namespace is fine, it's isolated from production and resets nightly"
    ]
  }
}

​

更改模型和 effort

• 当做对事情取决于容易被忽略的情况时，使用 /effort high 或 /effort xhigh 调高。比如您没写过的代码中的错误、不稳定的测试，或者 Claude 必须找到旧 schema 的每一个读取方的 schema 变更。Claude 随后会在回答前检查更多边界情况并验证更多工作，额外的时间和 token 就花在这里。
• 当您快速来回交流并且无论如何都会审查每个结果时，使用 /effort low 调低：头脑风暴、初步草图、跨几个文件的重命名。Claude 会更快地给您一个起点，而且由于您在引导每一步，额外的深思熟虑除了让您多等之外不会改变太多。
• 将 max 留给您希望 Claude 在没有您参与的情况下攻克的难题，比如寻找安全漏洞。在普通任务上它往往会过度思考，所以您付出更多，得到的答案却可能并不比 high 更好。
• 当只有下一条消息需要它时，比如在一系列常规工作中间出现一个棘手的问题，请在那条提示词中加入 ultrathink，而不是更改设置。

​

了解子代理的成本

• 广泛的代码库搜索交给内置的 Explore Agent。
• 在 fork 模式开启时（默认），附带任务会被分叉。
• 它启动的子代理默认在后台运行，因此您的主对话可以继续推进。

• 同时运行相互独立的工作，让整个任务更快完成
• 将长输出（比如完整的测试运行或大范围搜索）排除在主对话之外，否则它会在会话的剩余部分一直伴随着您
• 获得一个没有看到代码编写过程的审查者
• 给某个任务提供比主会话更少的工具，比如一个能读取但不能编辑的审查者

• 如果子代理的工作很简单，比如收集导入某个模块的文件或检查文档中的链接，请在其定义中设置 model: haiku。这类工作不需要更大的模型，而 Haiku 每次请求的成本要低得多。
• 要求返回简短的总结，这样二十个结果就不会反而填满您的上下文。
• 查看 /usage，了解每种子代理类型占您用量的多少，从而判断哪些物有所值。
• 给 .claude/agents/ 中的自定义子代理只配置 tools: Read, Grep, Glob。这样它就是一个无法编辑任何内容的审查者，而且这一限制由 Claude Code 强制执行，而不是在提示词中请求。

---
name: reviewer
description: Reviews changed files against the spec they were built from. Use after implementing a feature, before opening the PR.
tools: Read, Grep, Glob
---
You're reviewing code you didn't write. Compare the changed files against the spec you're given,
check that every requirement is implemented and the listed edge cases have tests,
and report only the gaps that affect correctness. Skip style.

​

控制成本和上下文

• 在不相关的任务之间使用 /clear。它不花任何成本，并且意味着下一个任务不必继续为上一个任务的历史付费。/clear oauth-migration 会为您离开的会话命名，以便您之后回到它。
• 带焦点地使用 /compact，比如 /compact keep the API changes and the test commands。在长会话中，/compact 本身就是一个大请求，因为它要读取整个对话来进行总结，缓存过期后更是如此。
• 留意后台工作：/loop、目标在每个轮次之后的检查，以及 Claude 自己的子代理，都会在您没有输入时持续发送请求。

​

引导会话

• Esc 会在 Claude 执行过程中停止它，并保留到那时为止的所有内容，因此您可以重新引导而不丢失工作。
• /rewind，或在空提示词上按两次 Esc，会打开 rewind 菜单，您可以在其中将代码、对话或两者回滚到更早的提示词。这让先尝试更大胆的方法、行不通再回滚变得风险很低。当对话的某部分已经过时，同一个菜单还可以对其进行总结。
• /clear 会重新开始。如果您已经两次更正同一件事而它仍然是错的，第三次更正多半只是往一个已经包含两次失败尝试的对话中添加内容，而 Claude 会不断重读这些内容。/clear 加上一个融合了您所学内容的新提示词，几乎每次效果都更好。

​

让 Claude 在无人值守时运行

1. 它知道完成是什么样子吗？一个目标条件、一个规范文件，或一个它必须让其通过的失败测试。
2. 它能检查自己的工作吗？测试套件、Stop hook、某种审查步骤。
3. 它被允许触及什么？权限规则、dontAsk、沙箱、worktree、它可以推送的那一个分支。
4. 什么会让它停下来？--max-turns、--max-budget-usd、支出限额。
5. 结果去哪里，谁来签核？一个 PR、一条评论或一份总结，然后由一个人批准合并、部署或任何其他无法撤回的操作。

​

从脚本运行 Claude

• --bare 会跳过 hook、skill、插件、MCP 服务器和 CLAUDE.md 文件（包括仓库的和机器的），因此无论在哪里运行，结果都一样。它也从不触及您的 claude.ai 登录：身份验证来自 ANTHROPIC_API_KEY、您通过 --settings 传入的文件中的 apiKeyHelper，或您的云提供商的凭据。
• --append-system-prompt、--mcp-config 和 --settings 会显式传入运行确实需要的内容。通过 --settings 传入的 hook 在 --bare 下不会运行，因此对于需要这些 hook 的运行，不要使用 --bare。
• --allowedTools 会预先批准其工具，而 --permission-mode dontAsk 会拒绝其他任何原本会触发提示的操作。
• --output-format json 会为您提供一个可供解析的单一结果对象，而搭配 --verbose 的 stream-json 会在事件发生时流式输出。

for file in $(cat files.txt); do
  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
done

​

按计划或事件启动运行

/loop 15m check CI on this branch, and if it's red pull the failing job's log, fix it and push

​

并行运行会话

.env
.env.local
config/dev-credentials.json

• 当您退出一个未命名的 worktree 会话时，如果其中没有任何内容，Claude Code 会删除该 worktree。对于已命名的会话或有更改的会话，它会询问如何处理。
• 子代理的 worktree 会在子代理无更改地完成时消失。
• 确实被遗留下来的子代理和后台会话 worktree，一旦超过 cleanupPeriodDays 且不包含任何工作，就会被清理掉。

​

您可以不再做的事

​

相关资源

• Claude Code 如何工作：循环、工具以及启动时加载的内容
• 探索上下文窗口：会话中哪些内容占用空间以及何时加载
• 扩展 Claude Code：在 skill、hook、MCP、子代理和插件之间进行选择
• 选择权限模式和配置权限
• 有效管理成本
• 以编程方式运行 Claude Code和使用云端定时任务自动化工作
• 面向团队负责人和管理员：为您的组织设置 Claude Code