claude-code-guide：一份面向 Claude Code 的社区综合参考

Claude Code 自带官方文档，但那份文档是按概念组织的，不是按"下午两点 API key 轮换把你构建搞挂了"这种真实问题组织的。zebbern/claude-code-guide 是一份社区策展的参考文档，结构恰好按你真实查询时翻文档的方式排：安装路径、环境变量、slash 命令、设置优先级、Plan/Auto 模式、hooks、MCP、安全、自动化 recipe、排错、第三方集成。

为什么这个 skill 重要

这份指南分成 9 个一级章节，正好对应一个 Claude Code 用户排查问题的路径：Getting Started、Configuration & Environment、Commands & Usage、Interface & Input、Advanced Features、Security & Permissions、Automation & Integration、Help & Troubleshooting、Third-Party Integrations。每一节都是密集的 cheat-sheet 表格与具体例子，而不是叙述性段落。

具体覆盖：官方原生安装（curl -fsSL https://claude.ai/install.sh | bash）、Homebrew、npm 以及包管理器变体；完整的环境变量面（auth、routing、model alias、Bedrock/Vertex/Foundry provider、timeout、session control、network routing、privacy flag）；配置文件优先级（managed > CLI > local > project > user）；slash 命令、键盘快捷键、vim 模式、Plan Mode、Auto Mode、Background Tasks；hooks；sub-agent（.claude/agents/<name>.md）；Skills（SKILL.md 结构）；PR review 与 issue triage 的自动化 recipe；MCP server scope 与推荐；排错（常见错误、debugging 技巧、路径、代理）；DeepSeek 集成与 provider setup 例子。

这是一份参考文档，不是可安装的 skill。README 明确写：命令与 provider model mapping 变化很快，链接的官方文档才是权威。License 是 MIT。4.6k 星、462 fork。

安装

没东西要装。打开 README，按目录翻，用顶部的 fast-path 链接（Install、Commands、Config、MCP、Agents、Troubleshoot）：

git clone https://github.com/zebbern/claude-code-guide

把它当作长 cheat sheet 用。

真实工作流：审计一个卡住的 Claude Code 会话

你卡住了，因为某样东西突然不工作。指南的 troubleshooting section 是最快的入口。

第一步。打开 README，跳到 Help & Troubleshooting。

第二步。Common Errors and Solutions 表格覆盖最常见的失败（auth rotation、sandbox 权限、MCP server 崩溃）。找最接近你症状的，按它给的修法试。

第三步。如果表格里没有，Debugging Techniques section 走一遍分层 debug 流程：开 verbose 日志、看 MCP server 日志、检查环境变量优先级（managed > CLI > local > project > user）、确认 model alias 解析到你有权限的 provider。

第四步。如果涉及代理或防火墙，Paths and Proxies section 列了 Claude Code 在每个 OS 上读的目录，以及路由网络流量的环境变量。

第五步。如果问题是某个 provider 特定的（DeepSeek、Bedrock、Vertex、Foundry），Third-Party Integrations section 有该 provider 的 setup 例子和已知坑。

真实工作流：从零到 GitHub 自动 PR Review 的完整搭建

你在给一个新项目配置 Claude Code，想要一张清单从零走到能跑的自动 PR review。指南按章节给你铺好。

第一步。Getting Started → 跑原生安装（curl -fsSL https://claude.ai/install.sh | bash）。通过 /config 配置完成提醒，挑一个通知渠道。

第二步。Configuration & Environment → 给你的 provider 设好 auth 和 routing 变量。对照 cheat sheet 的 Config essentials 块，确认优先级和你预期一致。

第三步。Commands & Usage → 挑你日常会用的 slash 命令。把它们写在项目级 AGENTS.md 里，让每次会话都继承这些约定。

第四步。Advanced Features → 多文件改动开 Plan Mode，单文件编辑开 Auto Mode，长跑的 shell 任务开 Background Tasks。每个你一周重复三次以上的工作流，配一个 Sub-Agent（.claude/agents/<name>.md）。

第五步。Automation & Integration → 抄 PR review recipe，指向你的 repo 的 CI trigger，验证自动建议的 label 和严重度等级匹配你们团队的约定。

第六步。Security & Permissions → 显式关掉 dangerous-mode 标志，为你的 agent 用的所有工具（特别是 MCP server 和 Bash）配置权限范围，安装任何 agent skill 文件前先 review。

第七步。Help & Troubleshooting → 收藏 Paths and Proxies 表格——企业防火墙第一次把安装搞挂的时候你会需要它。

真实工作流：评审一个你正在考虑装的 skill

你在评估一个第三方 skill（比如你在本站上找到的某个），想知道装机前要核查什么。指南的 Security & Permissions 和 Skills 两节合起来正好覆盖。

第一步。读 Skills section，确认这份指南文档的 SKILL.md 结构与候选 skill 的结构一致。结构对不上是红旗——skill 大概率是手写的，没遵循 Agent Skills 开放标准。

第二步。确认 skill 在 frontmatter（description 字段）和正文里的 When to use / When not to use 小节里声明了触发条件。没有这些就无法限定使用范围。

第三步。对照指南记录的安装路径检查候选 skill 的安装路径。对不上意味着 skill 不在标准 npx skills 或 /plugin marketplace 生态里，大概率不能干净卸载。

第四步。如果 skill 用了 hooks（指南在 Advanced Features section 里有讲），装机前审计 hook 的任何文件重写或网络调用副作用。hooks 是第三方 skill 最常见的踩坑来源。

第五步。在沙箱里跑这个 skill（一个临时分支或者 worktree）。指南在 Automation section 讲了基于 worktree 的隔离。把临时跑当作安全关卡，不只是冒烟测试。

技巧

• 冷启动 README 时用目录里的 fast path（Install、Commands、Config、MCP、Agents、Troubleshoot）。
• 把这份指南当查询工具，不是教程——官方 Claude Code 文档仍是权威，尤其是命令和 provider mapping 变化很快。
• 把能跑通的 .claude/agents/<name>.md 和 AGENTS.md 钉到 repo，让你在指南里读到的约定跨会话保留下来。
• 涉及安全的装机，先在隔离 worktree 里跑一遍 skill；批准任何自动重写行为前先看 hooks section。
• Provider 集成（Bedrock、Vertex、Foundry、DeepSeek）在 Third-Party Integrations section 各有 setup 例子，照着走而不是临时凑。

何时不要用

如果你要的是可安装的运行时 skill，这份文档不是。挑一个具体的 skill 装（比如 antfu/skills、heilcheng/awesome-agent-skills，或本站覆盖的项目级 skill）。还有，因为命令与 provider mapping 变化很快，链接的官方 Claude Code 文档仍是事实来源——把这份指南当作快速查询，不是终极参考。

在 leaderboard 查看更多指南与参考。