shanraisshan/claude-code-best-practice · 上手攻略

  • 仓库：shanraisshan/claude-code-best-practice
  • 链接：https://github.com/shanraisshan/claude-code-best-practice
  • 分类：trending / Claude Code 最佳实践
  • 作者：Jay
  • 更新：2026-07-08

这是什么

shanraisshan/claude-code-best-practice 是一个从 Vibe Coding 迈向 Agentic Engineering 的 Claude Code 实践指南库，Stars 62k+，周增 +287，MIT 许可。该仓库不只是技巧罗列，而是按功能分类（Agents、Commands、Skills、Hooks、MCP、Workflow 等）提供实战示例、最佳实践与实现细节，并标注各功能所属文档来源（code.claude.com）。覆盖从入门到高阶的完整学习路径。

解决什么问题

Claude Code 生态庞大，官方文档分散在 code.claude.com 的各个页面，实际使用时容易"知道有这功能但不知道在哪里配/怎么用"。该仓库将散落的官方能力按场景聚合：比如想用 Subagent？直接看 .claude/agents/<name>.md 示例文件；想配 MCP Server？.mcp.json 拿来即用。节省大量文档检索时间。

快速上手

无需安装任何依赖，直接阅读仓库文件或 clone 到本地作为项目模板。

git clone https://github.com/shanraisshan/claude-code-best-practice.git
cd claude-code-best-practice

仓库结构一览：

claude-code-best-practice/
├── CLAUDE.md              # 主入口说明
├── best-practice/         # 各功能最佳实践说明
│   ├── claude-subagents.md
│   ├── claude-commands.md
│   ├── claude-skills.md
│   ├── claude-mcp.md
│   ├── claude-settings.md
│   ├── claude-cli-startup-flags.md
│   └── ...
├── implementation/        # 具体实现代码/配置示例
├── orchestration-workflow/# 编排模式示例
├── reports/               # 深度分析报告
├── .claude/               # Claude Code 原生配置文件（直接复制到项目使用）
│   ├── agents/
│   ├── commands/
│   ├── skills/
│   ├── hooks/
│   └── settings.json
└── .mcp.json             # MCP Servers 配置

核心用法与可复制配置

1. Subagents（子代理）

配置位置：.claude/agents/<name>.md

在 best-practice/claude-subagents.md 有完整说明。核心思路： - 每个 .claude/agents/*.md 文件定义一个子代理 - 主项目 CLAUDE.md 通过引用这些文件激活子代理

2. Slash Commands（斜杠命令）

配置位置：.claude/commands/<name>.md

注册后输入 /命令名 触发。在 best-practice/claude-commands.md 详解。

3. Skills（技能）

配置位置：.claude/skills/<name>/SKILL.md

⚠️ 注意：Skill 文件名必须是 SKILL.md（全大写），否则不会被识别。

参考 best-practice/claude-skills.md + implementation/claude-skills-implementation.md。官方已打包的 Skill 列表见 anthropics/skills。

4. MCP Servers（模型上下文协议）

配置位置：.mcp.json 或 .claude/settings.json

仓库自带 .mcp.json 示例，直接复制到项目根目录即可启用对应 MCP Server。详细说明见 best-practice/claude-mcp.md。

// .mcp.json 示例结构
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
    }
  }
}

5. Hooks（钩子）

配置位置：.claude/hooks/（需配合 shanraisshan/claude-code-hooks 使用）

详见官方 Hooks Guide。

6. Workflows（编排模式）

仓库的 orchestration-workflow/ 目录实现了 Command → Agent → Skill 三层编排模式，参考 orchestration-workflow.md。

通用工作流：Research → Plan → Execute → Review → Ship

7. Agent Teams（多代理团队）

在 implementation/claude-agent-teams-implementation.md 中详解。注意：这是 beta 功能，通过环境变量启用。

8. Scheduled Tasks（定时任务）

/loop / /schedule + cron 工具实现。详见 implementation/claude-scheduled-tasks-implementation.md。

特色功能速查表（★=该仓库有专门文档）

功能 官方文档 仓库示例
Subagents link ★ best-practice
Commands link ★ best-practice
Skills link ★ best-practice
Hooks link ★ claude-code-hooks
MCP Servers link ★ .mcp.json
Settings link ★ settings.json
Memory link ★ claude-memory.md
Ultrareview link —
Auto Mode link —
Fast Mode link —
Advisor link —
Computer Use link —
Agent SDK link —
Git Worktrees link —
Agent View link —
Deep Research link —
Bundled Skills link /code-review, /batch
Voice Dictation link —

典型适用场景

  1. 新用户快速上手 Claude Code：直接参考 .claude/ 目录下的配置模板，copy 到自己项目，不用从零摸索。
  2. 在大型项目中配置 Subagent 团队：参考 implementation/claude-subagents-implementation.md 建立多代理分工。
  3. 搭建 Mono-repo 友好 Skill 结构：参考 reports/claude-skills-for-larger-mono-repos.md，解决大型代码库中 Skill 冲突问题。
  4. 自动化 Code Review：利用内置 /code-review skill + Ultrareview 功能，实现半自动代码审查流。
  5. 研究 Agent Teams 与编排模式：通过 orchestration-workflow/ 理解 Command→Agent→Skill 串联机制。

坑与注意

⚠️ 部分功能处于 Beta 状态

README 标注 🟡 的功能（如 Agent Teams、Auto Mode、Deep Research、Channels 等）尚未稳定，生产环境使用前请仔细测试。官方可能在小版本间变更行为。

⚠️ Skill 文件名大小写

Claude Code 对 Skill 路径有严格要求：必须是 <name>/SKILL.md（全大写），<name>/skill.md 或 <name>/Skill.md 不会被识别。常见踩坑点之一。

⚠️ Skill 与 Subagent 命名冲突

在同一项目中混用多个 Skill/Subagent 时，注意避免同名覆盖。Mono-repo 场景见 reports/claude-skills-for-larger-mono-repos.md。

⚠️ MCP Server 权限范围

.mcp.json 中定义的每个 Server 都有独立的文件系统访问权限，必须确保 command 和路径是可信的，恶意 MCP Server 可访问本地文件。

⚠️ Git Worktrees 是独立目录

开启 Worktree 后，每个 worktree 是独立工作区，其 .claude/ 配置互不影响。如果要让 Agent 感知特定 worktree 上下文，需要在对应目录初始化。

⚠️ 仓库内容多而杂

62k Stars 带来大量社区贡献，部分实现示例较为复杂。初学者建议从 CLAUDE.md + best-practice/ 目录入手，再深入 implementation/。

与同类对比

资源 定位 优势 劣势
本仓库 实践指南 + 配置模板 按场景聚合、示例可直接 copy、持续更新 文档量庞大、需筛选
awesome-claude-code 资源合集榜单 收录广、含社区工具 不提供实现细节
Everything Claude Code 导航合集 超全、含 prompt 模板 偏向汇总而非实践
官方文档 权威参考 最准确、最及时 分散在各页面、不成体系

本仓库的核心价值在于把官方文档翻译成可执行的项目模板，填补了"我知道这功能但不知道怎么落地"的空白。

一句话推荐结论

无论你是 Claude Code 新手还是想深度用好 Subagent / Skill / MCP / Hooks 等高阶功能，这个仓库都是目前最全面的实践指南 + 配置模板库；只需 clone 下来，把 .claude/ 目录的对应文件 copy 到自己的项目，就能快速落地。

来源：GitHub README（https://github.com/shanraisshan/claude-code-best-practice）、code.claude.com 官方文档链接
版本：2026-07-07 最新提交
注意：Beta 功能请以官方文档为准；Skill 文件名必须为 SKILL.md（全大写）。