Claude Code 最佳实践：一个开发者的完整修炼手册

这可能是全网最全面、最权威的 Claude Code 使用指南。 GitHub Trending 排名第一，Star 数 13 万+，作者 shanraisshan。

AI Coding 的开发者有福了，GitHub 上有个叫 claude-code-best-practice 的仓库，把 Claude Code 团队（Boris Cherny、Thariq 等人）在 Twitter/X 上散落的几百条实战技巧、播客访谈、技术报告，以及社区贡献的最佳实践，全部整理到了一起。

还有 11 份报告，从 Agent SDK vs CLI 系统提示对比、到 LLM 退化的真相、到浏览器自动化 MCP 工具选型。又整理了 8 个官方和社区的高质量视频/播客，列出了 87 条分类整理的技巧和窍门。

作者说："把本仓库当作课程来读，而不是工作流或技能。首先是参考资料，之后才运行。"

这篇文章按照"从入门到精通"的顺序，把仓库里的内容帮捋一遍，遇到问题时，可以到仓库中按图索骥的查找相应的教程、经验、别人的解决方案/思路。

五大核心

Claude Code 的本质是一个可编程的 AI 开发环境。

真正理解它，要从五个核心原语开始：子代理、命令、技能、钩子、记忆。

它们不是"换个方式写提示词"，而是脚手架层面的架构能力，是提示词无法替代的。

子代理 (Subagents)

子代理是放在 .claude/agents/<name>.md 文件里的独立执行者。

它有自己的上下文窗口。主对话遇到复杂任务时，把子代理派出去干活，它不会污染主对话的上下文。

子代理可以配置自己的工具权限、模型、记忆范围，甚至可以在后台运行、跑在独立的 git worktree 里。

推荐子代理的用法："当问题复杂时，说'使用子代理'。卸载任务到子代理，保持主上下文清洁和专注。"

更关键的洞察是"测试时计算"这个概念。

一个代理可能导致 bug，另一个相同模型的代理可以发现它们，因为独立的上下文窗口让模型看到不同的东西。

可以避免一直使用一个对话，导致上下文太长，模型能力下降。也可以避免一个模型偏向评价自己的任务时给出更好的分数。

命令 (Commands)

命令是放在 .claude/commands/<name>.md 文件里的提示模板。

你通过 /命令名 手动触发它。比如你写一个 /deploy 命令，每次执行部署时直接调用，不用重复输入一大段指令。

对每天多次做的'内循环'工作流使用斜杠命令。命令存放在 .claude/commands/ 并提交到 git，团队共享。如果你每天做某事超过一次，将其转换为技能或命令。

命令的一个特殊之处：它永远不会被 Claude 自动调用。

命令是纯用户触发的入口点。这也是它的优势：不需要的内容不会自动注入上下文。

命令还支持参数传递（ARGUMENTS、0、

技能 (Skills)

技能是放在 .claude/skills/<name>/SKILL.md 文件里的知识模块。

和命令最大的区别：技能可以被 Claude 根据你的意图自动发现和调用。

技能描述字段会被注入到会话上下文中，Claude 根据语义匹配自动决定是否调用。命令必须你手动 /。

技能描述字段是触发器，不是摘要。

为模型编写它，告诉模型'我什么时候应该触发？'"

另外，技能可以用 context: fork 在隔离的子代理中运行，主对话只看到最终结果，看不到中间的工具调用。这对保护上下文特别重要。

技能的另一个关键能力：可以被代理预加载。

在子代理的 frontmatter 里用 skills: 字段指定要预加载的技能，子代理启动时自动获得这些知识。

在技能的使用上，还可以参考昨天的文章：北大论文中给出的SSL结构化写法提升AI使用技能的效率。

钩子 (Hooks)

钩子是放在 .claude/hooks/ 目录里的处理器，在代理循环事件发生时执行。

它跟技能和命令的本质区别：钩子运行在代理循环之外，是确定性的代码执行。即使模型"不想"执行钩子，钩子照样会跑。

几个最实用的钩子用法：

PostToolUse 钩子在每次文件编辑后自动格式化代码。Claude 生成格式良好的代码，钩子自动处理最后 10% 的格式化细节，避免 CI 失败。

Stop 钩子在回合结束时推动 Claude 继续工作或验证自己的输出。

PreToolUse 钩子可以拦截破坏性命令，/careful 阻止危险操作，/freeze 阻止目录外的编辑。

还有一个高级玩法：通过钩子把权限请求路由到更强的模型，让它扫描攻击并自动批准安全的请求。

钩子Hook 功能可以帮助提升工程实践的遵从率：万字深研 ｜Harness 工程实践：指令遵从率 20%，Hook 执行率 100%

以前只有Claude Code 实现了钩子，最近发现 Codex 也增加了 Hook 的支持。

记忆 (Memory)

记忆通过 CLAUDE.md 文件和 .claude/rules/ 目录实现持久化。

项目级的 CLAUDE.md 被自动加载到每次对话的上下文中。

个人级的 ~/.claude/CLAUDE.md 跨项目生效。规则文件可以通过 paths: frontmatter 实现延迟加载，Claude 只在实际读取相关文件时才加载对应的规则。

此外还有代理记忆（v2.1.33 引入）。

子代理可以有自己的持久知识存储，分为三个范围：user（跨项目）、project（团队共享）、local（个人）。

和自动记忆的区别：自动记忆是主 Claude 自动写的，只给主 Claude 看。

代理记忆是子代理自己写的，只给那个特定代理看。

CLAUDE.md 是你手动写的，给主 Claude 和所有代理看。

Command → Agent → Skill 架构

这五个原语不是孤立的，一个经典的编排模式如下：

用户输入 /命令名，命令作为入口点编排工作流。 命令调用代理，代理在独立上下文中自主执行任务。 代理使用预加载的技能（领域知识），获得更精准的上下文。 命令再调用技能（内联），生成最终输出。

这个"命令编排 → 代理执行 → 技能注入知识"的模式，可以套用到几乎所有开发工作流上。

八条使用核心原则

Boris Cherny 是 Claude Code 的创建者。从 2026 年 1 月到 4 月，他在 X 上发了六组技巧系列（13 条、10 条、12 条、2 条、15 条、6 条），加上几次播客访谈。

仓库把这些内容全部整理成了详细的 Markdown 文件：

原则一：总是从计划模式开始

他在多个场合说过：不要一上来就让 Claude 写代码。

先进入 Plan 模式，让它分析需求、制定方案，你确认后再执行。这一个习惯就能避免 80% 的返工。

具体操作：在 /config 中设置默认权限模式为 Plan，或者在会话中按 Shift+Tab 切换到 Plan 模式。

计划阶段用 Opus（更聪明），编码阶段用 Sonnet（更快更便宜）。

Thariq 补充了一个技巧：从最小规格或提示开始，让 Claude 使用 AskUserQuestion 工具采访你，把需求问清楚，然后创建新会话执行规格。

原则二：用子代理为问题投入更多计算

子代理在独立的上下文窗口中运行，不会污染主对话。一个代理可能产生 bug，另一个相同模型的代理可以发现它们。

Boris 特别强调：使用功能特定的子代理，搭配技能实现渐进式披露, 而不是通用的"QA 代理""后端工程师代理"。越具体，效果越好。

同时用 git worktrees 和代理团队并行开发，多个代理在不同分支上同时工作，互不干扰。

原则三：保持 PR 小而专注

Boris 的团队一天提交了 141 个 PR，总共变更了 45K 行代码。PR 的中位数是 118 行。

每个 PR 只做一个功能。小的 PR 更容易审查，也更容易用 git revert 和 git bisect 追溯问题。

他还有一个配套原则：总是压缩合并 PR。每个功能一个提交，保持干净的线性历史。

原则四：CLAUDE.md 控制在 200 行以内

Boris 说 CLAUDE.md 应该目标少于 200 行。超过这个长度，Claude 开始忽略里面的指令。

HumanLayer 团队测试过 60 行效果最好。

但即使写得很短，也不是 100% 保证 Claude 会遵守。

社区里有人反映，即使CLAUDE.md 里用全大写写 MUST 的指令，Claude 仍然会忽略 80% 的情况。

对此 Dex Horthy（HumanLayer 创建者）提供了一个解决方案：用 <important if="..."> 标签包裹领域特定的规则，可以显著提高遵守率。

另一个技巧：对工具强制执行的行为使用 settings.json 而不是 CLAUDE.md。

比如 attribution.commit: "" 是确定性的配置，比在 CLAUDE.md 里写"绝不添加 Co-Authored-By"可靠得多。

原则五：不要微观管理 bug 修复

粘贴 bug 描述，说"修复"，然后让 Claude 自己想办法。

你越具体地描述怎么修，它的输出越受限。反过来，给它自由度，它经常能想出你没想到的方案。

另一个相关技巧：在平庸的修复之后，说"基于你现在知道的一切，丢弃这个并实现优雅的解决方案"。Claude 会在第二次尝试中给出明显更好的代码。

原则六：用 PostToolUse 钩子自动格式化代码

Claude 生成的代码已经很好了，但最后 10% 的格式化细节可能让 CI 失败。钩子自动处理这 10%，省心。

这个技巧的深层逻辑是：不要把确定性的事情交给模型。格式化是确定性的，交给钩子做。模型应该专注于创造性的编码。

原则七：用 @claude 自动化代码审查

在同事的 PR 上标记 @claude，让它自动生成针对重复审查反馈的 lint 规则。把自己从审查循环中逐步解放出来。

更进一步的，使用 /code-review 进行多代理 PR 分析。多个代理独立审查相同的代码，在合并前捕获 bug、安全漏洞和回归问题。

原则八：每天更新 Claude Code 并阅读更新日志

Claude Code 迭代极快，几乎每天都有新版本。不看 changelog 就用 Claude Code，等于用上个月的技能面对这个月的问题。

Boris 还建议关注 r/ClaudeCode、r/ClaudeAI、r/Anthropic 三个 Reddit 社区，以及 Claude 团队核心成员的 X 账号：Boris、Thariq、Cat、Lydia、Noah、Anthony、Alex、Kenneth。

Thariq 的技能设计

Thariq 是 Claude Code 团队的核心工程师，负责技能系统的设计。

他在 3 月 17 日的文章《构建 Claude Code 的经验教训：我们如何使用技能》中，分享了 9 条设计原则。

技能是文件夹，不是文件

不要只写一个 SKILL.md 扔在 .claude/skills/ 下就完事了。

技能应该是一个文件夹，里面有 SKILL.md、references/、scripts/、examples/ 子目录。这叫"渐进式披露"，Claude 按需加载这些子目录的内容，而不是一次性全部注入上下文。

为什么重要？因为上下文窗口有限。

一股脑把几十页文档塞给模型，它会丢失关键信息。渐进式披露让模型在需要时才看到相关内容，上下文更干净，推理更精准。

在每个技能中构建 Gotchas 部分

Gotchas 是技能中信号密度最高的内容。

你每次用技能时，Claude 在哪失败了、在哪踩坑了，把这些问题记下来放进 Gotchas 里。

随时间积累，技能会越来越可靠。

这不是一次性工作。它是持续改进的过程。

一个运行了三个月的技能，Gotchas 部分可能是最有价值的内容。

技能描述是触发器，不是摘要

不要写"本技能帮助用户进行代码审查"这种给人看的摘要。

要写"当用户请求代码审查、PR review、或要求检查代码质量时使用"。

这是给模型看的触发器。模型根据这个描述决定什么时候调用你的技能。

描述的准确度直接决定了技能是被恰到好处地调用，还是从不触发，还是到处乱触发。

不要陈述显而易见的东西

不要写"使用 git 命令时要小心"、"代码应该遵循团队规范"这类废话。Claude 已经知道这些了。

聚焦在推动 Claude 脱离默认行为的内容上。

你的团队有什么特殊约定？什么坑 Claude 反复掉进去？什么场景下常规做法不适用？写这些。

不要限制 Claude，给目标和约束

不要写"第一步：打开文件 A。第二步：修改第 10 行。第三步：运行测试。"

这样写等于把 Claude 当脚本执行器用，浪费了它的推理能力。

正确做法：给出目标和约束。

"目标是重构这个模块以提高可读性。约束：不改变外部 API、所有现有测试必须通过、使用团队统一的错误处理模式。"

Claude 会自己想出你没想到的方案。

在技能中包含脚本和库

如果技能要用到某个复杂的数据处理逻辑，不要指望 Claude 每次都从零写。

把脚本放到 scripts/ 目录里，让 Claude 直接调用和组合。

Claude 擅长组合，不擅长重复造轮子。给它造好的轮子，它能跑得更快更稳。

用按需钩子保护关键操作

在技能中配置 hooks: frontmatter，加上 /careful（阻止破坏性命令）和 /freeze（阻止目录外的编辑）。

这些钩子在模型调用工具之前执行，是确定性的保护。

衡量技能使用情况

用 PreToolUse 钩子记录每次技能调用。看看哪些技能最受欢迎，哪些技能几乎不触发。

触发不足的技能需要优化描述字段，让它更好地匹配用户的意图。

投资产品验证技能

Thariq 说，值得花一整周时间完善产品验证技能，比如"注册流程驱动器"或"结账验证器"。

这些技能运行一次，等于帮你做了一整套端到端测试，发现的问题往往是你手工测不出来的。

87 条实战技巧

仓库按类别整理了 87 条技巧，覆盖提示工程、规划、CLAUDE.md、代理、命令、技能、钩子、工作流、Git/PR、调试、实用工具、日常十二个维度。

提示工程

第一条：挑战 Claude。

"对这些更改进行严格审查，在我通过你的测试之前不要创建 PR"或者"向我证明这能工作"。让 Claude 对比 main 分支和你的分支，它会发现自己忽略的问题。

第二条：在平庸的修复之后说"基于你现在知道的一切，丢弃这个并实现优雅的解决方案"。

Claude 第二次给出的代码通常比第一次好一个档次。

第三条：Claude 能自己修复大多数 bug，粘贴错误信息说"修复"即可。

不要把时间花在教它怎么修上。

规划

总是制定分阶段的门控计划，每个阶段都有多个测试（单元、自动化、集成）。

不是"写完代码再测"，而是"每完成一个阶段就验证一次"。

启动第二个 Claude 作为资深工程师审查你的计划。

或者用跨模型工作流（Claude Code + Codex）进行交叉审查。

两个模型从不同角度审视同一份计划，能发现的问题远超单模型。

还有一个反直觉的原则：原型优先于 PRD。

Boris 在播客里说过，构建 20 到 30 个版本而不是编写规格说明，构建成本低所以多尝试几次。

确实，我在使用AI编程的过程中，也发现这个问题，AI的规划写得很完美，执行起来有瑕疵。

CLAUDE.md

任何开发者都应该能够启动 Claude，说'运行测试'，第一次就能工作。

如果不行，你的 CLAUDE.md 缺少必要的设置/构建/测试命令。"

保持代码库清洁并完成迁移同样重要。

部分迁移的框架会混淆模型，让它选择错误的模式。

对单体仓库使用多个 CLAUDE.md，祖先加载加后代加载组合使用。把大型指令拆分到 .claude/rules/ 目录。

代理和技能

技能描述字段不是给人看的摘要，是给模型看的触发器。

"我什么时候应该触发？"，回答这个问题就够了。

用 context: fork 在隔离的子代理中运行技能。

主对话只看到最终结果，不看到中间的工具调用。agent 字段还可以设置子代理类型。

技能里嵌入 !`command` 语法，可以在调用时注入动态 shell 输出到提示中。

Claude 调用时运行命令，模型只看到结果，这是动态上下文注入的标准做法。

钩子和工作流

避免"代理呆滞区"：上下文使用量最多到 50% 就手动执行 /compact。

切换到新任务时用 /clear 重置上下文。

沙箱模式（/sandbox）通过文件和网络隔离减少权限提示。

Anthropic 内部测试数据：减少 84% 的权限提示。

使用通配符语法配置权限：Bash(npm run *)、Edit(/docs/**)，而不是 dangerously-skip-permissions。

前者精确、安全、可审计。

Git 和 PR

Boris 的 PR 数据：一天 141 个 PR，45K 行变更，中位数 118 行。保持 PR 小而专注，每个 PR 一个功能。

总是压缩合并 PR。

每个功能一个提交，干净的线性历史。git revert 和 git bisect 在需要时会感谢你。

在同事的 PR 上标记 @claude 自动生成针对重复审查反馈的 lint 规则。

把自己从代码审查中逐步自动化出来。

调试

养成习惯，遇到任何问题时截图并与 Claude 分享。

一张截图比 500 字的描述更准确。

用 MCP 工具让 Claude 自己查看浏览器控制台日志。

Claude in Chrome、Playwright MCP、Chrome DevTools MCP 三者互补。

总是让 Claude 把你想看日志的终端作为后台任务运行。

Claude 可以看到日志输出并帮你分析。

代理搜索（glob + grep）战胜 RAG。

Claude Code 团队尝试过向量数据库做代码搜索，但放弃了。

原因是代码会不同步，权限管理复杂。直接的文件搜索反而更可靠。

实用工具和日常

在 iTerm、Ghostty 或 tmux 终端中运行 Claude Code，而不是 VS Code 或 Cursor 的内置终端。

Boris 明确说过终端体验远好于 IDE 集成。

使用状态栏（/statusline）实时感知上下文使用量，知道什么时候该压缩。

用 /voice 或 Wispr Flow 进行语音提示。Boris 说语音提示能带来 10 倍生产力提升。

每天更新 Claude Code 并阅读 changelog。关注社区的 Reddit 和 X 账号。

热门功能详解

Claude Code 最近几个月发布的功能更新速度极快。

仓库里列出了十几项热门功能，介绍了它们是什么、怎么用、为什么重要。

自动模式 (Auto Mode)

这是 Claude Code 安全模型的一次升级。

传统的权限模式是"询问模式"：Claude 每次执行 bash 命令、编辑文件、访问网络，都要弹窗问你是否批准。

这个机制是安全的，但频繁打断工作流。

自动模式用模型本身替代了手工审批。

后台运行一个安全分类器，判断每个操作是否安全。安全的自动批准，有风险的暂停询问实际用户。

使用方式：claude --enable-auto-mode 启动，或者在会话中按 Shift+Tab 循环切换到 Auto 模式。

Boris 特别强调：用自动模式替代 dangerously-skip-permissions。前者是智能的、有判断的，后者是粗暴的、无差别的。

代码审查 (Code Review)

Claude Code 的多代理 PR 分析功能，是仓库里被反复提及的一个重要能力。

它的工作方式：启动多个子代理，每个代理独立审查同一份 PR 的不同方面。一个代理检查逻辑错误，一个检查安全漏洞，一个检查性能回归。最后汇总结果。

使用 /code-review 命令触发。也可以用 GitHub App 集成，在 PR 上直接输出审查意见。

这个功能在合并前能捕获大量人工审查遗漏的问题。

因为多个代理从不同角度审视代码，组合效果远超单代理。

计划任务 (Scheduled Tasks)

两种定时方式：/loop 和 /schedule。

/loop 在本地按定期计划运行提示，最多可以运行 7 天。适合在你工作时定期检查日志、监控状态、重新生成报告。

/schedule 在 Anthropic 的云基础设施上运行任务，即使你的机器关机了也能按时执行。

适合跨天的定期任务。

两者的区别是执行环境：/loop 依赖你的本地机器在线，/schedule 不依赖。

代理团队 (Agent Teams)

多个 Claude Code 会话在同一代码库上并行工作，共享任务协调。环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 启用。

两种运行模式：In-process 模式下所有队员在你的终端内运行。Split panes 模式每个队员获得独立的 tmux 或 iTerm2 窗格。

配合 git worktrees，每个代理在自己的隔离分支上工作，冲突大大减少。

Ralph Wiggum 自进化循环

这是一个专门为长时间运行的自主任务设计的插件。

它的逻辑是：Claude 开始一个开发任务，完成一段后自己测试，发现错误后自己修复，然后再测试，如此循环直到任务完成或达到迭代上限。

和普通代理的区别：普通代理执行到你给的指令结束就停了。Ralph Wiggum 循环有"迭代直到完成"的能力，适合那些你没法预判需要多少轮的任务。

这个功能感觉很酷，还没有试过，有用过的朋友吗？

Chrome 集成与浏览器自动化

Claude in Chrome 是一个官方扩展，让 Claude 可以直接操控浏览器。

测试 Web 应用、自动化表单、从页面提取数据，都通过浏览器完成。

仓库里有一份详细的对比报告，比较了三款浏览器自动化 MCP 工具：

Playwright MCP（推荐主力）：跨浏览器支持、token 占用最低、CI/CD 友好。用无障碍树定位元素，比 CSS 选择器更稳定，不容易因为 UI 改动而失效。

Claude in Chrome：优势是复用你的登录态，适合快速手动验证。劣势是无法在 CI/CD 中使用。

Chrome DevTools MCP：性能追踪和网络调试的最佳选择。当你要回答"这个页面为什么慢"的时候，它是唯一能给你深度性能数据的工具。

推荐安装方式：claude mcp add playwright -s user -- npx @playwright/mcp@latest 作为主力测试工具，

claude mcp add chrome-devtools -s user -- npx chrome-devtools-mcp@latest 作为性能调试补充。

其他

无闪烁模式：设置 CLAUDE_CODE_NO_FLICKER=1，启用全屏渲染，支持鼠标、稳定内存和滚动。适合长时间编码时减少视觉疲劳。

计算机使用 (Computer Use)：让 Claude 直接控制你的屏幕，在 macOS 上打开应用、点击、输入和截屏。

远程控制：从手机、平板或浏览器继续本地会话。/remote-control 或 /rc 命令启用。

简化与批处理：/simplify 简化重构代码以提高复用性和效率，/batch 在多个文件中批量运行命令。

语音听写：/voice 启用按键说话输入，支持 20 种语言。

深度报告

仓库里有 11 份深度报告，每份都是经过实际验证的研究成果。我挑了三份对我认知冲击最大的详细讲。

为什么"脚手架"比提示重要百倍

很多有经验的 Claude Code 用户会有一种简化思维："技能、命令、子代理、钩子，最终都变成模型的提示，所以一个强大的提示就够了，没必要搞那么多目录结构。"

这份报告专门针对这个观点写了完整的反驳。

在模型推理调用层面，这个说法在技术上是正确的。

模型确实只看到 token，不管这些 token 是从 CLI 的系统提示来的，还是从你手写的提示词来的。

但在真正的软件工程层面，这个简化就会全面崩溃。

关键数据：在对话型工具里，用户输入的内容（a）和模型推理时看到的内容（b）是同一件事。

但在 Claude Code 里，你输入的可能只有 6 到 60 个 token，而模型实际看到的上下文是 5000 到 50000 个 token。

多出来的 99% 来自哪里？

CLAUDE.md 的项目约定、匹配的规则文件、模块化的系统提示片段、工具定义、环境上下文（工作目录、git 状态）、之前对话的回合历史、以及模型通过 Read/Grep 工具读取的相邻文件内容。

所有这些都不是用户写的，全部由脚手架自动构建。

报告列出了脚手架独有的 10 项架构能力：

上下文隔离：N 个并行子代理提供 N 倍的有效上下文。一个提示只能填满一个窗口，脚手架可以调度多个进程并行工作。

工具限制：提示中的"不要用危险命令"是建议性的，模型可以忽略。脚手架中的 deny 规则是强制性的，模型无法绕过。

延迟加载：提示是静态的。脚手架可以做到"只有当 Claude 实际读取某个目录的文件时，才加载对应的规则和记忆"。

钩子执行：提示无法拦截自己的工具调用。钩子运行在代理循环之外，即使模型"不想"也会执行。

模型路由、并行性、跨会话持久性、技能预加载、权限分类，每一项都是提示词无法触及的层面。

报告用了一句话总结："你可以写出世界上最好的食谱。没有厨房，你无法规模化烹饪。"

对开发者的实际启示：对于原子任务（"写一个递归函数"），提示质量几乎决定一切，脚手架没有贡献。但对于真实代码库工作，脚手架在做无声的重活。用技能/命令/代理不是因为它们比手动写提示词更优雅，而是因为它们能做到提示词根本做不到的事。

LLM 的"退化"真相：你的感觉没错，但原因不是你想的那样

核心问题：模型权重发布后不会改变（所有提供商都确认了），那为什么你会在某些天觉得"Claude 今天变笨了"？

报告先用一张图说明了整个推理栈的 9 个层次，从顶层的会话上下文逐层往下，到底层的模型权重。模型权重冻结在底部没错，但它上面的 8 层都可以独立变化。

Anthropic 在 2025 年 9 月发布了一份正式事后分析，承认了三个独立的基础设施 bug：

第一个 bug：上下文窗口路由错误。Sonnet 4 的请求被意外路由到了为 100 万 token 上下文配置的服务器上（而不是标准服务器）。峰值时影响了 16% 的请求。

一旦命中坏服务器，后续请求会继续打过去。

这个 bug 从 8 月 5 日引入，到 9 月 18 日才在所有平台完全修复。

在此期间，约 30% 的 Claude Code 用户至少收到过一次降级回复。

第二个 bug：TPU 输出损坏。TPU 服务器上一个配置错误，导致 token 生成过程中把高概率分配给不该出现的 token。

症状是英语回复中突然出现泰语或中文字符，代码中冒出明显的语法错误。影响了 Opus 4.1、Opus 4 和 Sonnet 4。

第三个 bug 最隐蔽也最难排查：XLA:TPU 编译器错误编译。

团队为了修复精度问题改了一行代码，意外暴露了一个潜伏的编译器 bug。

近似 top-k 操作（用来挑选最可能的下一个 token）在特定条件下返回完全错误的结果。

这个 bug 几个月前就存在了，但被一个临时的变通方案掩盖了。变通方案被移除后，bug 才暴露出来。

为什么这些 bug 这么难发现？

一个重要原因是 Claude 运行在三种不同的硬件平台上：AWS Trainium、NVIDIA GPU、Google TPU。

每种平台有不同的编译器、不同的故障模式、不同的精度行为。

你今天的请求可能打到 TPU 上，明天可能打到 GPU 上，同一个模型，不同的硬件，不同的结果。

即使零 bug、零配置变更，模型的日间质量波动也是可测的。

Scale AI 的研究发现，同一模型在不同天的分数偏差达到 ±8 到 14%。

同一个模型，同一天，越狱抵抗测试从 77% 掉到 63%，14 个百分点的波动，纯粹来自基础设施的随机性。

这意味着：你不能区分一个真实的 5% 质量变化和噪声。

±10-15% 的日间波动是系统固有特性，个人的使用体验无法判断模型是否真的变差了。

报告给出的最实用建议是：当感觉 Claude 质量下降时，先用 /compact 或重新开始会话。

上下文污染是最常见的单会话质量退化原因，也是你唯一能直接控制的变量。

Claude Code 正在替代哪些创业公司

这份报告列出了一个现象：Claude Code 的内置功能正在直接替代一系列独立产品。

代码审查替代了 Greptile、CodeRabbit、Devin Review、OpenDiff、Cursor BugBot。

语音听写替代了 Wispr Flow、SuperWhisper。

远程控制替代了 OpenClaw。

Chrome 集成替代了 Playwright MCP、Chrome DevTools MCP（作为独立产品）。

计算机使用替代了 OpenAI CUA。

协同工作替代了 ChatGPT Agent、Perplexity Computer、Manus。

代理 SDK 替代了 LangChain、LangGraph、CrewAI、AutoGen、OpenAI Assistants API。

设计功能替代了 Figma、Framer、Sketch、v0。

技能/插件市场被社区调侃为"YC AI 包装类创业公司的终结者"。

报告陈述了一个趋势：平台型产品的功能集成，正在吃掉它的生态位里大量独立工具的生存空间。

这个趋势在技术史上反复出现，从操作系统到浏览器到 IDE，现在是 AI 编程平台。

代理、命令、技能如何选择

这是 Claude Code 用户最常见的困惑之一：做同样一件事，用代理、用命令、用技能，有什么区别？

仓库里有一份专门的报告对比了三者，而且用了一个很巧妙的方式说明，用同一个任务（"显示当前时间"）分别用三种机制实现，然后分析每种的结果。

关键区别

代理（Agent）是独立的子代理进程，有自己的上下文窗口。它可以在后台运行，可以配置不同的模型和权限，可以有持久记忆。

但它不是用户直接 / 触发的，而是被 Claude 通过 Agent 工具调用，或者通过命令/技能间接调用。

命令（Command）是用户手动触发的入口点，通过 /命令名 调用。

Claude 永远不会自动调用命令。命令的内容在触发前不会被注入上下文，所以不占用上下文空间。

技能（Skill）可以被 Claude 自动发现和调用，也可以被用户手动触发。

技能的描述始终在上下文中，但完整内容只在被调用时加载。

使用顺序

当用户说"当前时间是什么"时，三种机制如何响应？

技能（最可能）：技能的描述里写了"当用户询问当前时间时使用"，Claude 自动匹配到并调用。技能内联运行，无上下文开销，是最轻量的选择。

代理（次选）：代理的描述也是自动匹配的，但它在独立上下文中运行，比技能重。如果技能不可用或任务明显更复杂，Claude 会选择代理。

命令（不触发）：命令永远不会自动触发。用户必须手动输入 /time-command。

所以结论是：Claude 优先选择最轻量的选项来满足请求。技能 > 代理 > 命令。

什么时候用哪个

用代理的情况：任务是自主的、多步骤的，需要上下文隔离，需要持久记忆。比如代码审查代理，每次审查不同代码但积累相同模式的经验。

用命令的情况：你需要用户明确的触发入口，你想保持上下文干净（命令内容不触发不加载）。比如部署命令、测试命令、发布命令。

用技能的情况：你希望 Claude 自动感知意图并调用，任务是可复用的过程，可以被多个入口调用。比如代码格式化技能、文档生成技能。

代理记忆的补充

代理有三种记忆范围：user 跨项目共享、project 团队共享并纳入版本控制、local 个人使用不共享。

启动时，代理的 MEMORY.md 前 200 行被注入系统提示。

执行期间代理可以自由读写记忆目录。超过 200 行时，代理会将详细内容自动拆分到主题特定文件。

全局 vs 项目设置的补充

有些功能只能存在全局级别（~/.claude/）：任务、代理团队、自动记忆、凭证和 OAuth、快捷键。

这些是个人状态和跨项目协调，不应该被某个项目的配置文件控制。

其他功能可以同时存在于全局和项目级别，项目级优先：CLAUDE.md、设置、规则、代理、命令、技能、钩子、MCP 服务器。

注意两点：deny 规则有最高的安全优先级，不能被低优先级的 allow/ask 规则覆盖。

管理层可以通过 managed-settings.json 强制组织策略，本地文件无法推翻。

视频与播客推荐

仓库整理了 8 个高质量的视频/播客，最推荐的几个：

一、Boris Cherny 在 The Pragmatic Engineer 的访谈（3 小时）。

这是最全面的 Claude Code 深层解读，几乎覆盖了所有设计决策和内部使用方式。

二、Andrej Karpathy 在 AI Engineer 的"从 Vibe Coding 到代理工程"。

Karpathy 作为 OpenAI 创始成员和深度学习先驱，对这个领域的理解深度和视角完全不一样。

三、Matt Pocock 的"AI 编码工作流完整演练"，是一个实战导向的视频，展示了一个顶级 TypeScript 开发者如何把 AI 融入日常工作流。

四、Dex Horthy 在 MLOps Community 的"我们对研究-计划-实现理解错在哪里"，从反向视角审视了当前最流行的工作流范式。

五、Cat Wu 在 Every 的"Claude Code 构建工程师揭秘"，提供了一个内部工程师的视角。

六、Boris 在 Ryan Peterman 频道的职业发展访谈，这期偏人物故事，适合想了解 Claude Code 创建者思维方式的人。

社区订阅

如果你想把 Claude Code 用透，关注以下信息源：

X 上的 Claude 官方账号和核心团队成员：@claudeai、@AnthropicAI、@bcherny（Boris）、@trq212（Thariq）、@catwu（Cat）、@lydiahallie（Lydia）、@noahzweben（Noah）、@amorriscode（Anthony）、@alexalbert_（Alex）、@neilhtennek（Kenneth）。

Reddit 的三个社区：r/ClaudeAI、r/ClaudeCode、r/Anthropic。

GitHub 上的相关仓库：Boris 的 Superpowers、Affaan Mustafa 的 Everything Claude Code、Garry Tan 的 gstack、Dex Horthy 的 HumanLayer、Matt Pocock 的 Skills、Dani Avila 的 CC Templates。

作者 shanraisshan 本人还维护了 Codex CLI Best Practice、Gemini CLI Best Practice，以及这些工具的 Hooks 仓库，全部配套。

开放问题

仓库最后列出了 13 个开放问题，作者说"如果你有答案，请联系我"。

这些问题目前没有人有确定的答案，但每一个都指向 AI 编程工具未来发展中最关键的未知点。

记忆与指令

CLAUDE.md 里到底应该写什么？什么应该刻意排除在外？有了 CLAUDE.md 还需要单独的 constitution.md 吗？

CLAUDE.md 应该多久更新一次？你怎么知道它什么时候过时了？更本质的是：为什么 Claude 有时候会完全忽略 CLAUDE.md 的指令，即使是全大写写着的 MUST？

代理与工作流

什么时候该用命令、什么时候用代理、什么时候原生 Claude Code 反而更好？模型一直在变，代理和工作流应该多久更新一次？

一个全能子代理好，还是功能特定的代理好？给子代理详细的角色描述真的能提高质量吗？如果能，"完美的角色提示"到底长什么样？

内置计划模式和自己构建的规划命令/代理之间该怎么选？如果你有自己的编码风格技能（/implement），怎么和社区技能（/simplify）共存？冲突时谁优先？

代码与规格

那个终极问题：我们能把现有代码库全部转换成规格说明，删掉所有代码，然后让 AI 只从规格说明重新生成完全相同的代码吗？如果能，这意味着什么？如果不能，差在哪里？

这些问题没有标准答案，但正是这些未解的问题，定义了接下来几年 AI 编程工具会往哪个方向演进。

一个更根本的问题

仓库指向了另一个仓库 agentic-engineering，标题只有一个问题：Does code matter？

当 AI 能从规格说明生成代码时，代码本身还重要吗？

这可能是所有问题中最根本的一个。

这个仓库虽然是写的 Claude Code 的最佳实践，但是绝大多数都是讲的 AI Coding 的通用经验、技巧和方案，用在 Codex、Trae、WorkBuddy、Qoder、OpenClaw、Hermes 等编程智能体/助手智能体也是适用的。

方法也很简单：对话智能体，让它直接读相应的文档，再要求它进行解读，实施到当前环境/项目中。

GitHub 仓库：

https://github.com/shanraisshan/claude-code-best-practice/tree/main

如果你也在用 Claude Code，欢迎在评论区留言。