Claude Code 高级配置完整指南

Claude Code 高级配置完整指南

根据 X 用户 @affaanmustafa 发布的文章（Everything Claude Code 配置分享）和其配套 GitHub 仓库（https://github.com/affaan-m/everything-claude-code），本文整理了一个详细的中文教程。该仓库收集了经过实战验证的 Claude Code 配置，包括 agents（子代理）、skills（技能）、hooks（钩子）、commands（命令）、rules（规则）和 MCP（Model Control Protocol，模型控制协议，用于外部服务集成）。这些配置由 Anthropic 黑客马拉松获奖者开发，历经 10+ 个月打磨，用于构建真实产品。

Claude Code 是使用 Anthropic Claude 模型（Opus、Sonnet、Haiku）进行高级编码工作的环境，支持子代理分工、自动化钩子、持久化记忆和工具集成，能大幅提升编码效率、代码质量和安全性。

本教程详细讲解设置步骤、各组件作用，并提供实际实例。适合有 Claude Code 环境（本地配置目录 ~/.claude/）的用户。

1. 快速开始（Quick Start）

1. 克隆仓库：

   git clone https://github.com/affaan-m/everything-claude-code.git
   cd everything-claude-code
   

2. 复制配置到本地目录：
   Claude Code 使用 ~/.claude/ 目录存储配置。将仓库中的文件复制过去：

   cp -r agents commands contexts examples hooks mcp-configs plugins rules skills ~/.claude/
   

3. 配置钩子（hooks）：
   在 Claude Code 的 settings.json 中添加 hooks.json 内容（仓库 hooks/ 目录下）：

   {
     "hooks": {
       "PreToolUse": [...],  // 工具使用前触发
       "PostToolUse": [...], // 工具使用后触发
       "Stop": [...]         // 停止时触发
     }
   }
   

4. 配置 MCP（外部服务集成）：
   编辑 ~/.claude.json，添加 MCP 服务器（如 GitHub、Supabase、Vercel）：

   {
     "mcp_servers": {
       "github": { "api_key": "your_github_token" },
       "supabase": { "url": "your_supabase_url", "key": "your_key" },
       // 其他服务类似
     }
   }
   

   注意：永远不要提交真实密钥到 Git，使用占位符并本地替换。

5. 启动 Claude Code：
   重启你的 Claude Code 会话，这些配置会自动加载。你可以通过 @mention 文件（如 @planner）调用子代理，或使用 /command（如 /tdd）触发工作流。

关键建议：

• 上下文窗口管理：每个项目启用 <10 个 MCP，<80 个工具，避免上下文溢出。
• 模型选择：高质量任务用 Claude Opus 4.5（或最新 Opus），成本敏感用 Haiku/Sonnet。

2. 核心组件详解

2.1 Rules（规则）—— 始终遵守的指导原则

位于 rules/ 目录，这些文件是 Claude 必须遵循的全局规则，通过项目级 CLAUDE.md 引用。

作用：强制代码风格、安全、测试等标准。

主要文件及实例：

• security.md：禁止硬编码秘密、要求输入验证。
  示例规则：

  永远不要在代码中硬编码 API 密钥或密码。必须使用环境变量或 MCP 配置的密钥管理。
  所有用户输入必须进行 sanitization，防止 XSS、SQL 注入。
  

• coding-style.md：统一代码格式。
  示例：

  使用 Prettier + ESLint 格式化代码。
  函数名使用 camelCase，类名 PascalCase。
  

• testing.md：强制 TDD 和覆盖率。
  示例：

  所有新功能必须遵循 RED-GREEN-REFACTOR 循环。
  测试覆盖率必须 ≥80%。
  

• git-workflow.md：Git 提交规范。
  示例：

  Commit 消息必须遵循 Conventional Commits 格式。
  每次推送前必须运行测试。
  

使用方式：在主 CLAUDE.md 中 @rules/security @rules/testing 等引用。

2.2 Agents（子代理）—— 专业分工代理

位于 agents/ 目录，每个 .md 文件是一个可 @mention 的专职代理。

作用：将复杂任务分解给不同专家代理，主代理（orchestrator）通过 agents.md 调度。

主要代理实例：

• planner.md：项目规划师，负责分解任务。

• architect.md：系统架构师，设计整体结构。

• tdd-guide.md：TDD 指导者，监督测试驱动开发。

• code-reviewer.md：代码审查者，使用 Read、Grep、Glob、Bash 工具。
  示例定义（简化）：

  @code-reviewer
  你是严格的代码审查专家。
  工具：Read, Grep, Glob, Bash
  模型：Opus
  任务：检查代码是否符合所有 rules，提出改进建议。
  

• security-reviewer.md：安全审查。

• build-error-resolver.md：构建错误修复。

• e2e-runner.md：端到端测试运行。

• refactor-cleaner.md：重构清理。

• doc-updater.md：文档更新。

实例使用：
在聊天中输入 @code-reviewer 请审查 src/components/Button.tsx，Claude 会切换到该代理角色进行审查。

高级技巧：在 agents.md 中定义主调度逻辑：

当任务涉及安全时，自动委托给 @security-reviewer。

2.3 Skills（技能）—— 工作流与领域知识

位于 skills/ 目录，提供具体工作流和专业知识。

实例：

• tdd-workflow/：详细 TDD 流程（RED → GREEN → REFACTOR）。
• security-review/：安全审查检查清单。
• backend-patterns.md / frontend-patterns.md：后/前端最佳实践。
• clickhouse-io.md：特定技术（如 ClickHouse）优化。

使用：通过命令或代理引用。

2.4 Commands（命令）—— 快捷 slash 命令

位于 commands/ 目录，定义 /command 快速触发工作流。

实例：

• /tdd：启动 TDD 循环。
  示例内容（tdd.md）：

  /tdd
  开始测试驱动开发：
  1. 写失败测试（RED）
  2. 写最小代码通过（GREEN）
  3. 重构优化（REFACTOR）
  

• /plan：生成项目计划（调用 planner）。

• /code-review：触发代码审查。

• /build-fix：修复构建错误。

• /e2e：运行端到端测试。

• /refactor-clean：重构清理。

使用实例：直接输入 /tdd 添加用户登录功能，Claude 会按流程执行。

2.5 Hooks（钩子）—— 自动化触发

位于 hooks/ 目录，通过 hooks.json 定义。

类型：

• PreToolUse：在工具使用前触发。
• PostToolUse：工具使用后触发。
• Stop：会话结束时触发。

实例：

• 警告使用 console.log：

  {
    "trigger": "bash grep 'console.log' *.ts *.js",
    "action": "warn",
    "message": "禁止在生产代码中使用 console.log，请使用专用日志库。"
  }
  

• 持久化记忆：在 Stop 时总结进度并保存到 .tmp 文件，下次会话加载。

2.6 MCP（模型控制协议）—— 外部服务集成

位于 mcp-configs/ 目录，配置 API 访问（如 GitHub 自动提交、Supabase 数据库操作）。

实例：

• GitHub MCP：自动创建 PR。
• Vercel/Railway：部署预览。

配置注意：仅启用需要的 MCP，避免上下文浪费。

3. 实际项目实例

假设你正在开发一个 React + Node.js 全栈应用：

1. 创建新项目，复制配置到 ~/.claude/。
2. 开始会话：
   • 输入 /plan 用户认证系统 → planner 生成计划。
   • 输入 /tdd 实现登录 API → 进入 TDD 循环。
   • 写代码后，输入 /code-review → code-reviewer 检查。
   • 发现安全问题 → 自动委托 security-reviewer。
   • 构建出错 → /build-fix 修复。
   • 完成后 → GitHub MCP 自动提交。

最终得到高质量、可测试、安全的代码。

4. 进阶技巧与最佳实践

• 记忆共享：使用 hooks 在会话间保存总结到 .tmp 文件。
• 自定义状态栏：使用 /statusline 命令设置（如显示当前代理、进度）。
• 成本优化：子代理使用 Haiku 处理简单任务，主代理用 Opus。
• 贡献：仓库欢迎 PR，遵循 CONTRIBUTING.md。

这个配置体系能让 Claude 从“简单助手”变成“专业工程团队”。建议先从小项目实践，逐步添加组件。

参考原仓库：https://github.com/affaan-m/everything-claude-code
原 X 文章：https://x.com/affaanmustafa/status/2012378465664745795

如有问题，可在仓库提 issue 或查看社区讨论。祝编码愉快！