Claude Code 最佳实践大全：22.9k Stars 的 AI 编程指南解读

目标读者：希望系统掌握 Claude Code 最佳实践、提升 AI 编程效率的开发者 核心问题：如何用好 Claude Code 的各项功能，遵循业界最佳实践？ 难度：⭐⭐⭐⭐（专家设计） 来源：GitHub shanraisshan/claude-code-best-practice，2026-03-28

一、项目概览

1.1 为什么这个项目值得关注

Claude Code Best Practice 是 GitHub 上最全面的 Claude Code 最佳实践仓库之一，由开发者 shanraisshan 创建和维护。该项目被 Boris Cherny（Anthropic 前员工、TypeScript 专家）在 X 上多次推荐，并在 GitHub Trending 上获得 #1 Repository Of The Day。

核心数据：

1.2 项目的核心价值

这个仓库的核心价值在于系统化整理了 Claude Code 的使用方法，包括：

• 概念澄清：Subagents、Commands、Skills、Hooks 等容易混淆的概念
• 最佳实践：来自真实项目经验的配置和代码示例
• 实现代码：可以直接复制使用的 .claude/ 配置文件
• 开发工作流：对比六大主流 AI 开发方法论

1.3 适合谁使用

二、核心概念体系

Claude Code 的功能体系可以分为三个层次和若干扩展模块。

2.1 概念层次总览

┌─────────────────────────────────────────────────────┐
│                    Claude Code                        │
├─────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
│  │  Subagents  │  │  Commands   │  │   Skills    │  │
│  │  (Agent)    │  │  (Command)  │  │  (Skill)    │  │
│  └─────────────┘  └─────────────┘  └─────────────┘  │
│        ↑               ↑               ↑            │
│    独立上下文      注入现有上下文    可配置、可预加载    │
├─────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
│  │   Hooks     │  │    MCP      │  │   Plugins   │  │
│  │  (钩子)      │  │  (协议)     │  │  (插件)      │  │
│  └─────────────┘  └─────────────┘  └─────────────┘  │
│   事件触发        外部工具连接      可分发的功能包      │
└─────────────────────────────────────────────────────┘

2.2 Subagents（子代理）

概念：Subagent 是一个在全新隔离上下文中运行的自主角色，拥有自定义工具、权限、模型、记忆和持久身份。

文件位置：.claude/agents/<name>.md

核心特点：

• 独立上下文，不污染主会话
• 可自定义工具（Tools）
• 可设置权限（Permissions）
• 可指定模型（Model）
• 可配置记忆（Memory）
• 保持持久身份（Persistent Identity）

适用场景：

• 需要并行执行多个独立任务
• 需要在隔离环境中运行敏感操作
• 需要保持任务状态的独立性

2.3 Commands（命令）

概念：Command 是注入到现有上下文的知识模板，由用户主动调用，用于编排工作流。

文件位置：.claude/commands/<name>.md

核心特点：

• 简单的提示词模板
• 用户通过 /command-name 调用
• 共享当前上下文
• 适合快速执行单一操作

与 Subagent 的区别：

2.4 Skills（技能）

概念：Skill 是注入到现有上下文的高度可配置、可预加载、可自动发现的知识模块，支持上下文分叉和渐进式披露。

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

核心特点：

• 可配置（Configurable）：参数可自定义
• 可预加载（Preloadable）：可设置预加载行为
• 可自动发现（Auto-discoverable）：Claude Code 自动识别
• 上下文分叉（Context Forking）：在子上下文中运行主上下文的副本，互不影响
• 渐进式披露（Progressive Disclosure）：按需逐步提供信息，避免上下文溢出

官方 Skills：

Claude Code 官方维护了一系列预置 Skills，存放在 anthropics/skills 仓库中。

2.5 Hooks（钩子）

概念：Hook 是在智能体循环外部、特定事件触发时运行的用户定义处理器，可以是脚本、HTTP 请求、提示词或子代理。

文件位置：.claude/hooks/

事件类型：

• pre-tool-use：工具使用前触发
• post-tool-use：工具使用后触发
• on-conversation-start：对话开始时触发
• on-conversation-end：对话结束时触发

使用示例：

// .claude/hooks/pre-tool-use.js
export const preToolUse = async (tool, args) => {
  console.log(`About to use tool: ${tool}`);
  // 可以在这里添加日志、权限检查等逻辑
  return { tool, args };
};

2.6 MCP Servers（模型上下文协议服务器）

概念：MCP（Model Context Protocol）是连接外部工具、数据库和 API 的协议，通过 .mcp.json 配置。

文件位置：.claude/settings.json 或 .mcp.json

核心功能：

• 连接外部工具（GitHub、Slack 等）
• 连接数据库（PostgreSQL、MySQL 等）
• 调用外部 API（REST、GraphQL 等）

配置示例：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

2.7 Plugins（插件）

概念：Plugin 是技能、子代理、钩子和 MCP 服务器的可分发打包，可以发布到市场供他人使用。

特点：

• 可分发：可以打包分享
• 可组合：bundles of skills, subagents, hooks, MCP servers
• 有市场：支持创建和发现插件市场

相关资源：

• Discover Plugins
• Create Marketplaces

三、配置与个性化

3.1 Settings（设置系统）

Claude Code 采用分层配置系统，支持多种配置级别。

术语说明：CLI Flags（Command-Line Interface Flags）是命令行启动标志，用于在启动 Claude Code 时传递参数，如 --permission-mode auto 开启自动权限模式。

文件位置：.claude/settings.json

配置层级（从高到低）：

1. 命令行标志（CLI Flags）
2. 项目级设置（.claude/settings.json）
3. 用户级设置（~/.claude/settings.json）
4. 系统级设置

可配置项：

3.2 Status Line（状态栏）

概念：Status Line 是可自定义的状态栏，显示上下文使用量、模型、成本和会话信息。

配置方式：在 .claude/settings.json 中配置

显示信息：

• 上下文使用量（Token 计数）
• 当前模型
• 本次会话成本
• 会话时长
• 并行任务数

3.3 Memory（记忆系统）

Claude Code 的记忆系统通过多个层面实现持久上下文。

记忆存储位置：

@path 导入：

使用 @path/to/file 可以将任意文件内容导入上下文

Auto Memory：

Claude Code 自动维护记忆，包括：

• 项目结构
• 常用模式
• 历史决策

Rules（规则）：

使用 .claude/rules/ 组织规则文件，实现模块化管理。

四、新兴特性（Hot Features）

4.1 Auto Mode（自动模式）beta

概念：Auto Mode 是后台安全分类器，用 Claude 替代人工权限提示，自动判断操作是否安全。

启动方式：--permission-mode auto

安全机制：

• 阻止提示词注入（Prompt Injection）
• 阻止危险升级（Risky Escalations）
• 自动判断安全操作

适用场景：

• 信任的代码库
• 自动化工作流
• 快速原型开发

4.2 Channels（通道）beta

概念：Channels 允许将Telegram、Discord 或 Webhooks 的事件推送到运行中的 Claude Code 会话。

特点：

• 你离开时 Claude 也能响应
• 支持远程触发任务
• 基于插件架构

适用场景：

• 远程团队协作
• 自动化监控和响应
• 移动端触发任务

4.3 Code Review（代码审查）beta

概念：Code Review 是多代理 PR 分析工具，能捕捉 bug、安全漏洞和回归问题。

特点：

• 多代理并行分析
• 自动识别问题类型
• 与 GitHub 集成

效果：

• 减少人工审查时间
• 提高问题发现率
• 加速开发流程

4.4 GitHub Actions

概念：在 CI/CD 流水线中自动化 PR 审查、Issue 分类和代码生成。

适用场景：

• 自动化测试驱动审查
• Issue 自动分类和分配
• 持续集成中的代码质量检查

4.5 Chrome（浏览器自动化）beta

概念：通过 Claude 在 Chrome 中自动化浏览器操作。

功能：

• 测试 Web 应用
• 调试控制台
• 自动填写表单
• 从页面提取数据

启动方式：--chrome 或安装扩展程序

4.6 Scheduled Tasks（定时任务）

任务类型：

适用场景：

• 定时数据同步
• 定期报告生成
• 自动化监控任务

4.7 Agent Teams（代理团队）beta

概念：多个代理在同一代码库上并行工作，通过共享任务协调实现协作。

特点：

• 并行开发
• 共享任务队列
• 各自独立的上下文
• 协调执行顺序

4.8 Voice Dictation（语音输入）beta

概念：通过按键说话实现语音输入，支持 20 种语言。

启动方式：/voice

特点：

• 按键激活（可重新绑定）
• 多语言支持
• 实时转文字

4.9 Remote Control（远程控制）

概念：从**任何设备（手机、平板、浏览器）**继续本地会话。

启动方式：/remote-control 或 /rc

相关功能：

• Headless Mode（无头模式）：无需图形界面
• 远程调试

4.10 Git Worktrees（Git 工作树）

概念：使用隔离的 Git 分支进行并行开发，每个代理获得独立的工作副本。

特点：

• 分支隔离，互不干扰
• 支持并行任务执行
• 充分利用多核 CPU

五、开发工作流对比

5.1 通用架构模式

所有主流工作流都遵循相同的架构：

Research → Plan → Execute → Review → Ship

5.2 六大工作流对比

5.3 Superpowers 详解（118k Stars）

核心理念：TDD-first（测试驱动开发优先）

核心文件：

• writing-plans：写作计划技能
• test-driven-development：TDD 技能
• brainstorming：头脑风暴技能

铁律（Iron Laws）：

1. 先写测试，再写代码
2. 保持测试快速
3. 不提交未通过的测试

工作流：

1. 写计划 → 2. 审查计划 → 3. 写测试 → 4. 写代码 → 5. 重构 → 6. 审查

5.4 Everything Claude Code 详解（111k Stars）

核心理念：本能评分（Instinct Scoring）

核心组件：

• instinct scoring：本能评分系统
• AgentShield：代理安全防护
• multi-lang rules：多语言规则

特点：

• 动态调整代理行为
• 安全优先
• 跨语言支持

5.5 Get Shit Done 详解（43k Stars）

核心理念：新鲜大上下文 + Wave Execution（波次执行）

独特特性：

• 200k Token 上下文
• Wave Execution（波次执行）
• XML Plans（XML 格式计划）

工作流：

1. 接收任务（可能是 200k 上下文）
2. 分成多个「波」
3. 每波并行执行
4. 波间汇总

六、编排工作流详解

6.1 Command → Agent → Skill 模式

Claude Code 的编排工作流遵循 Command → Agent → Skill 的层级模式：

User invokes /command
        ↓
    Command loads
    (prompt template)
        ↓
    May spawn Agent
    (isolated context)
        ↓
    Agent uses Skill
    (reusable capability)

6.2 天气编排器示例

仓库中提供了 weather-orchestrator 示例：

/claude /weather-orchestrator

这会触发：

1. Command：加载天气查询模板
2. Subagent：创建独立的天气查询代理
3. Skill：使用天气 API 技能获取数据
4. 结果返回：汇总多个数据源的天气信息

6.3 如何自定义编排

1. 创建 Command：在 .claude/commands/ 中定义
2. 创建 Subagent：在 .claude/agents/ 中定义
3. 创建 Skill：在 .claude/skills/ 中定义
4. 组合使用：通过 Command 调用 Subagent，Subagent 使用 Skill

七、实战建议

7.1 新手入门路径

第一阶段（1-2天）：

1. 安装 Claude Code，阅读官方文档
2. 尝试基本操作：读写文件、运行命令
3. 体验 /voice 语音输入
4. 体验 /help 获取帮助

第二阶段（3-7天）：

1. 配置 .claude/settings.json
2. 尝试 Subagents：创建简单子代理
3. 尝试 Commands：创建自定义命令
4. 体验 Hooks：添加简单的预工具钩子

第三阶段（长期）：

1. 构建个人 Skills 库
2. 配置 MCP Servers 连接常用工具
3. 探索 Agent Teams 并行开发
4. 研究适合自己的开发工作流

7.2 团队采用建议

第一步：制定规范

• 确定哪些操作需要人工审批
• 定义提交消息格式
• 制定 Code Review 流程

第二步：配置共享

• 在团队仓库中创建 .claude/ 配置
• 使用 Rules 组织团队规范
• 共享常用的 Commands 和 Skills

第三步：CI/CD 集成

• 配置 GitHub Actions 自动审查
• 使用 Scheduled Tasks 自动化报告
• 建立质量门禁

7.3 安全最佳实践

7.4 性能优化

八、总结

8.1 概念地图

Claude Code
├── 核心概念
│   ├── Subagents（独立上下文代理）
│   ├── Commands（提示词模板）
│   ├── Skills（可复用技能）
│   └── Hooks（事件钩子）
├── 扩展能力
│   ├── MCP Servers（外部工具连接）
│   ├── Plugins（可分发包）
│   └── Channels（远程触发）
├── 配置系统
│   ├── Settings（分层配置）
│   ├── Status Line（状态栏）
│   └── Memory（持久记忆）
└── 新兴特性
    ├── Auto Mode（自动权限）
    ├── Agent Teams（并行代理）
    └── Remote Control（远程控制）

8.2 关键要点

1. 理解概念层次：Subagents、Commands、Skills 各有适用场景
2. 善用编排模式：Command → Agent → Skill 是核心模式
3. 注重安全配置：根据场景选择合适的权限模式
4. 采用最佳实践：参考六大开发工作流，选择适合团队的
5. 持续迭代优化：利用 Checkpointing 和 Status Line 监控改进

8.3 资源链接

相关话题标签

#Claude Code #AI编程 #Anthropic #最佳实践 #Agent工作流

来源

• GitHub：https://github.com/shanraisshan/claude-code-best-practice
• Boris Cherny 推文：https://x.com/bcherny/status/2007179832300581177

本文为技术分析文章，内容基于 GitHub 公开信息和 Claude Code 官方文档。