Claude Code 基础设施组件集成指南

本文介绍 Claude Code 基础设施组件集成指南，帮助开发者将 showcase 仓库中的组件集成到自己的项目中。

概述

这个仓库是 Claude Code 基础设施组件的参考库。用户会要求你将特定的组件集成到他们的项目中。你的角色是：

1. 询问澄清问题 - 了解他们的项目结构
2. 复制适当的文件
3. 自定义配置 - 针对他们的设置
4. 验证集成 - 确保正常工作

关键原则： 在假设项目结构之前，一定要先询问。适用于一个项目的方案不一定适用于另一个。

技术栈兼容性检查

关键： 在集成 skill 之前，验证用户的技术栈是否与 skill 要求匹配。

前端 Skills

frontend-dev-guidelines 需要：

• React (18+)
• MUI v7
• TanStack Query
• TanStack Router
• TypeScript

集成前询问： "你使用 React 和 MUI v7 吗？"

如果不匹配：

frontend-dev-guidelines skill 是专门为 React + MUI v7 设计的。我可以：
1. 使用这个模板帮你创建一个适配 [他们的技术栈] 的类似 skill
2. 提取框架无关的模式（文件组织、性能等）
3. 如果不相关就跳过这个 skill

你更喜欢哪个选项？

后端 Skills

backend-dev-guidelines 需要：

• Node.js/Express
• TypeScript
• Prisma ORM
• Sentry

集成前询问： "你使用 Node.js 和 Express 以及 Prisma 吗？"

如果不匹配：

backend-dev-guidelines skill 是为 Express/Prisma 设计的。我可以：
1. 使用这个模板帮你创建一个适配 [他们的技术栈] 的类似指南
2. 提取架构模式（分层架构适用于任何框架）
3. 跳过这个 skill

你更喜欢哪个选项？

技术栈无关的 Skills

这些适用于任何技术栈：

• ✅ skill-developer - 元 skill，无技术要求
• ✅ route-tester - 只需要 JWT cookie 认证（框架无关）
• ✅ error-tracking - Sentry 适用于大多数技术栈

通用集成模式

当用户说："将 [组件] 添加到我的项目中"

1. 识别组件类型（skill/hook/agent/command）
2. 检查技术栈兼容性（针对前端/后端 skills）
3. 询问他们的项目结构
4. 复制文件或适配到他们的技术栈
5. 针对他们的设置进行自定义
6. 验证集成
7. 提供后续步骤

集成 Skills

分步流程

当用户请求一个 skill（例如，"添加 backend-dev-guidelines"）：

1. 了解他们的项目

询问这些问题：

• "你的项目结构是什么？单应用、monorepo 还是多服务？"
• "你的 [后端/前端] 代码在哪里？"
• "你使用什么框架/技术？"

2. 复制 Skill

cp -r /path/to/showcase/.claude/skills/[skill-name] \\
      $CLAUDE_PROJECT_DIR/.claude/skills/

3. 处理 skill-rules.json

检查是否存在：

ls $CLAUDE_PROJECT_DIR/.claude/skills/skill-rules.json

如果不存在：

• 从 showcase 复制模板
• 移除用户不想要的 skills
• 针对他们的项目进行自定义

如果存在：

• 读取他们当前的 skill-rules.json
• 添加新的 skill 条目
• 仔细合并以避免破坏现有 skills

4. 自定义路径模式

关键： 更新 skill-rules.json 中的 pathPatterns 以匹配他们的结构：

示例 - 用户有 monorepo：

{
  "backend-dev-guidelines": {
    "fileTriggers": {
      "pathPatterns": [
        "packages/api/src/**/*.ts",
        "packages/server/src/**/*.ts",
        "apps/backend/**/*.ts"
      ]
    }
  }
}

示例 - 用户有单个后端：

{
  "backend-dev-guidelines": {
    "fileTriggers": {
      "pathPatterns": [
        "src/**/*.ts",
        "backend/**/*.ts"
      ]
    }
  }
}

安全的通用模式（不确定时使用）：

{
  "pathPatterns": [
    "**/*.ts",          // 所有 TypeScript 文件
    "src/**/*.ts",      // 常见的 src 目录
    "backend/**/*.ts"   // 常见的后端目录
  ]
}

5. 验证集成

# 检查 skill 是否已复制
ls -la $CLAUDE_PROJECT_DIR/.claude/skills/[skill-name]

# 验证 skill-rules.json 语法
cat $CLAUDE_PROJECT_DIR/.claude/skills/skill-rules.json | jq .

告诉用户： "尝试编辑 [their-backend-path] 中的文件，skill 应该会激活。"

Skill 特定说明

backend-dev-guidelines

• 技术要求： Node.js/Express, Prisma, TypeScript, Sentry
• 询问： "你使用 Express 和 Prisma 吗？" "你的后端代码在哪里？"
• 如果技术栈不同： 提供使用此模板进行适配
• 自定义： pathPatterns
• 示例路径： api/, server/, backend/, services/*/src/
• 适配提示： 架构模式（Routes→Controllers→Services）可移植到大多数框架

frontend-dev-guidelines

• 技术要求： React 18+, MUI v7, TanStack Query/Router, TypeScript
• 询问： "你使用 React 和 MUI v7 吗？" "你的前端代码在哪里？"
• 如果技术栈不同： 提供创建适配版本（Vue, Angular 等）
• 自定义： pathPatterns + 所有框架特定的示例
• 示例路径： frontend/, client/, web/, apps/web/src/
• 适配提示： 文件组织和性能模式可移植，组件代码不可移植

route-tester

• 技术要求： JWT cookie 认证（框架无关）
• 询问： "你使用 JWT cookie 认证吗？"
• 如果不匹配： "这个 skill 是为 JWT cookie 设计的。要我为你适配 [他们的认证类型] 还是跳过它？"
• 自定义： 服务 URL，认证模式
• 适用于： 任何使用 JWT cookie 的后端框架

error-tracking

• 技术要求： Sentry（适用于大多数后端）
• 询问： "你使用 Sentry 吗？" "你的后端代码在哪里？"
• 如果没有 Sentry： "想用这个作为 [他们的错误追踪] 的模板吗？"
• 自定义： pathPatterns
• 适配提示： 错误追踪理念可移植到其他工具（Rollbar, Bugsnag 等）

skill-developer

• 技术要求： 无！
• 原样复制 - 元 skill，完全通用，教授适用于任何技术栈的 skill 创建

为不同技术栈适配 Skills

当用户的技术栈与 skill 要求不同时，你有以下选项：

选项 1：适配现有 Skill（推荐）

何时使用： 用户想要类似指南但用于不同技术

流程：

1. 复制 skill 作为起点：

   bashCopy

   cp -r showcase/.claude/skills/frontend-dev-guidelines \\
         $CLAUDE_PROJECT_DIR/.claude/skills/vue-dev-guidelines

2. 识别需要更改的内容：

   • 框架特定的代码示例（React → Vue）
   • 库 API（MUI → Vuetify/PrimeVue）
   • Import 语句
   • 组件模式

3. 保留可移植的内容：

   • 文件组织原则
   • 性能优化策略
   • TypeScript 标准
   • 通用最佳实践

4. 系统地替换示例：

   • 询问用户他们技术栈中的等效模式
   • 将代码示例更新到他们的框架
   • 保留整体结构和章节

5. 更新 skill 名称和触发器：

   • 适当重命名 skill
   • 为他们的技术栈更新 skill-rules.json 触发器
   • 测试激活

选项 2：提取框架无关模式

何时使用： 技术栈差异很大，但核心原则适用

流程：

1. 通读现有 skill

2. 识别框架无关模式：

   • 分层架构（后端）
   • 文件组织策略
   • 性能优化原则
   • 测试策略
   • 错误处理理念

3. 仅用这些模式创建新 skill

4. 用户可以稍后添加框架特定的示例

选项 3：仅作为参考

何时使用： 差异太大无法适配，但用户想要灵感

流程：

1. 用户浏览现有 skill
2. 你帮助从头创建新 skill
3. 使用现有 skill 的结构作为模板
4. 遵循模块化模式（主文件 + 资源文件）

通常可跨技术栈移植的内容

架构与组织：

• ✅ 分层架构（Routes/Controllers/Services 模式）
• ✅ 关注点分离
• ✅ 文件组织策略（features/ 模式）
• ✅ 渐进式披露（主文件 + 资源文件）
• ✅ 数据访问的 Repository 模式

开发实践：

• ✅ 错误处理理念
• ✅ 输入验证重要性
• ✅ 测试策略
• ✅ 性能优化原则
• ✅ TypeScript 最佳实践

框架特定代码：

• ❌ React hooks → 不可移植到 Vue/Angular
• ❌ MUI 组件 → 不同的组件库
• ❌ Prisma 查询 → 不同的 ORM 语法
• ❌ Express 中间件 → 不同的框架模式
• ❌ 路由实现 → 框架特定

集成 Hooks

必备 Hooks（始终安全复制）

skill-activation-prompt (UserPromptSubmit)

目的： 根据用户提示自动建议 skills

集成（无需自定义）：

# 复制两个文件
cp showcase/.claude/hooks/skill-activation-prompt.sh \\
   $CLAUDE_PROJECT_DIR/.claude/hooks/
cp showcase/.claude/hooks/skill-activation-prompt.ts \\
   $CLAUDE_PROJECT_DIR/.claude/hooks/

# 设置可执行权限
chmod +x $CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh

# 如果需要，安装依赖
if [ -f "showcase/.claude/hooks/package.json" ]; then
  cp showcase/.claude/hooks/package.json \\
     $CLAUDE_PROJECT_DIR/.claude/hooks/
  cd $CLAUDE_PROJECT_DIR/.claude/hooks && npm install
fi

添加到 settings.json：

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh"
          }
        ]
      }
    ]
  }
}

这个 hook 完全通用 - 随处可用，无需自定义！

post-tool-use-tracker (PostToolUse)

目的： 跟踪文件更改以进行上下文管理

集成（无需自定义）：

# 复制文件
cp showcase/.claude/hooks/post-tool-use-tracker.sh \\
   $CLAUDE_PROJECT_DIR/.claude/hooks/

# 设置可执行权限
chmod +x $CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-use-tracker.sh

添加到 settings.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-use-tracker.sh"
          }
        ]
      }
    ]
  }
}

这个 hook 完全通用 - 自动检测项目结构！

可选 Hooks（需要大量自定义）

tsc-check.sh 和 trigger-build-resolver.sh (Stop hooks)

⚠️ 警告： 这些 hooks 是为特定的多服务 monorepo 结构配置的。

集成前询问：

1. "你有包含多个 TypeScript 服务的 monorepo 吗？"
2. "你的服务目录名称是什么？"
3. "你的 tsconfig.json 文件在哪里？"

对于简单项目（单服务）：

• 建议跳过这些 hooks
• 对于单服务项目它们过于复杂
• 用户可以手动运行 tsc --noEmit 代替

集成 Agents

Agents 是独立的 - 最容易集成！

标准 Agent 集成

# 复制 agent 文件
cp showcase/.claude/agents/[agent-name].md \\
   $CLAUDE_PROJECT_DIR/.claude/agents/

就是这样！ Agents 立即工作，无需配置。

检查硬编码路径

某些 agents 可能引用路径。复制前，阅读 agent 文件并检查：

• ~/git/old-project/ → 应该是 $CLAUDE_PROJECT_DIR 或 .
• /root/git/project/ → 应该是 $CLAUDE_PROJECT_DIR 或 .
• 硬编码截图路径 → 询问用户他们想要截图保存在哪里

如果找到，更新它们：

sed -i 's|~/git/old-project/|.|g' $CLAUDE_PROJECT_DIR/.claude/agents/[agent].md
sed -i 's|/root/git/.*PROJECT.*DIR|$CLAUDE_PROJECT_DIR|g' \\
    $CLAUDE_PROJECT_DIR/.claude/agents/[agent].md

集成 Slash Commands

# 复制 command 文件
cp showcase/.claude/commands/[command].md \\
   $CLAUDE_PROJECT_DIR/.claude/commands/

自定义路径

Commands 可能引用 dev docs 路径。检查并更新：

dev-docs 和 dev-docs-update：

• 查找 dev/active/ 路径引用
• 询问："你想把开发文档存储在哪里？"
• 更新 command 文件中的路径

常见模式与最佳实践

模式：询问项目结构

不要假设：

• ❌ "我将为你的 blog-api 服务添加这个"
• ❌ "正在为你的 frontend 目录配置"

要询问：

• ✅ "你的项目结构是什么？Monorepo 还是单应用？"
• ✅ "你的后端代码在哪里？"
• ✅ "你使用 workspaces 还是有多个服务？"

模式：自定义 skill-rules.json

用户有带 workspaces 的 monorepo：

{
  "pathPatterns": [
    "packages/*/src/**/*.ts",
    "apps/*/src/**/*.tsx"
  ]
}

用户有 Nx monorepo：

{
  "pathPatterns": [
    "apps/api/src/**/*.ts",
    "libs/*/src/**/*.ts"
  ]
}

用户有简单结构：

{
  "pathPatterns": [
    "src/**/*.ts",
    "backend/**/*.ts"
  ]
}

验证清单

集成后，验证这些项目：

# 1. Hooks 可执行
ls -la $CLAUDE_PROJECT_DIR/.claude/hooks/*.sh
# 应该显示：-rwxr-xr-x

# 2. skill-rules.json 是有效的 JSON
cat $CLAUDE_PROJECT_DIR/.claude/skills/skill-rules.json | jq .
# 应该无错误解析

# 3. Hook 依赖已安装（如果有 TypeScript hooks）
ls $CLAUDE_PROJECT_DIR/.claude/hooks/node_modules/
# 如果 package.json 存在，应该显示包

# 4. Settings.json 是有效的 JSON
cat $CLAUDE_PROJECT_DIR/.claude/settings.json | jq .
# 应该无错误解析

然后请用户测试：

• "尝试编辑 [relevant-path] 中的文件 - skill 应该会激活"
• "尝试问我关于 [topic] 的问题 - 我应该会建议 skill"

常见错误避免

❌ 不要：原样复制 settings.json

原因： Stop hooks 引用不存在的服务 要： 仅提取 UserPromptSubmit 和 PostToolUse 部分

❌ 不要：保留示例服务名称

原因： 用户没有 blog-api, auth-service 等 要： 询问他们实际的结构并更新

❌ 不要：跳过设置 hooks 可执行权限

原因： 没有执行权限 hooks 不会运行 要： 复制后始终 chmod +x

❌ 不要：假设 monorepo 结构

原因： 大多数项目是单服务 要： 先询问，然后自定义

❌ 不要：一次添加所有 skills

原因： 压倒性且可能不都相关 要： 询问哪些 skills 与他们的工作相关

❌ 不要：未测试就复制 Stop hooks

原因： 如果失败会阻塞 Stop 事件 要： 先手动测试，只有工作正常才添加

快速参考表

什么需要自定义？

何时建议跳过

来源

• 原文：Claude Integration Guide
• 项目：claude-code-infrastructure-showcase