23 KiB

Raw Blame History

Claude 集成指南

致 Claude Code： 当用户要求您将此展示库中的组件集成到他们的项目中时，请仔细遵循这些说明。

概述

此仓库是 Claude Code 基础设施组件的参考库。用户会要求您帮助将特定部分集成到他们的项目中。您的角色是：

提出澄清性问题 了解他们的项目结构
复制适当的文件
为他们量身定制配置
验证集成是否正常工作

核心原则： 永远先询问，再假设项目结构。适用于一个项目的方案不一定适用于另一个项目。

技术栈兼容性检查

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

前端技能

frontend-dev-guidelines 要求：

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

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

如果答案是否定的：

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

您更倾向于哪种方式？

后端技能

backend-dev-guidelines 要求：

Node.js/Express
TypeScript
Prisma ORM
Sentry

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

如果答案是否定的：

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

您更倾向于哪种方式？

技术无关的技能

这些适用于任何技术栈：

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

通用集成模式

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

识别组件类型（技能/钩子/智能体/命令）
检查技术栈兼容性（适用于前端/后端技能）
询问他们的项目结构
复制文件或为他们适配技术栈
为他们量身定制配置
验证集成
提供后续步骤

集成技能

分步流程

当用户请求技能（例如，"添加 backend-dev-guidelines"）：

1. 了解他们的项目

询问这些问题：

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

2. 复制技能

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

如果不存在：

从展示库复制模板
删除用户不需要的技能
为他们的项目定制

如果存在：

读取他们当前的 skill-rules.json
添加新的技能条目
小心合并，避免破坏现有技能

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"   // 常见 backend 目录
  ]
}

5. 验证集成

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

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

告诉用户： "尝试编辑 [他们的后端路径] 中的文件，技能应该会激活。"

技能特定说明

backend-dev-guidelines

技术要求： Node.js/Express、Prisma、TypeScript、Sentry
询问： "您使用 Express 和 Prisma 吗？" "您的后端代码在哪里？"
如果技术栈不同： 提供以这个为模板进行适配
自定义： pathPatterns
示例路径： api/、server/、backend/、services/*/src/
适配提示： 架构模式（路由→控制器→服务）适用于大多数框架

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 的认证吗？"
如果答案是否定： "此技能专为 JWT cookie 设计。要我为 [他们的认证类型] 适配它或跳过吗？"
自定义： 服务 URL、认证模式
适用于： 使用 JWT cookie 的任何后端框架

error-tracking

技术要求： Sentry（适用于大多数后端）
询问： "您使用 Sentry 吗？" "您的后端代码在哪里？"
如果没有 Sentry： "要以此作为 [他们的错误跟踪] 的模板吗？"
自定义： pathPatterns
适配提示： 错误跟踪理念适用于其他工具（Rollbar、Bugsnag 等）

skill-developer

技术要求： 无！
原样复制 - 元技能，完全通用，教授为任何技术栈创建技能

为不同技术栈适配技能

当用户的技术栈与技能要求不同时，您有选择：

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

何时使用： 用户想要针对不同技术有类似的指南

流程：

复制技能作为起点：

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

识别需要更改的部分：
- 框架特定代码示例（React → Vue）
- 库 API（MUI → Vuetify/PrimeVue）
- 导入语句
- 组件模式
保留可以迁移的部分：
- 文件组织原则
- 性能优化策略
- TypeScript 标准
- 通用最佳实践
系统地替换示例：
- 询问用户他们技术栈中的等效模式
- 将代码示例更新为他们的框架
- 保持整体结构和章节
更新技能名称和触发器：
- 适当地重命名技能
- 更新 skill-rules.json 触发器以适应他们的技术栈
- 测试激活

示例 - 为 Vue 适配 frontend-dev-guidelines：

我将基于 React 技能结构创建 vue-dev-guidelines：
- 将 React.FC → Vue defineComponent
- 将 useSuspenseQuery → Vue composables
- 将 MUI 组件 → [他们的组件库]
- 保留：文件组织、性能模式、TypeScript 指南

这需要几分钟时间。听起来不错吧？

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

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

流程：

阅读现有技能
识别与框架无关的模式：
- 分层架构（后端）
- 文件组织策略
- 性能优化原则
- 测试策略
- 错误处理理念
创建仅包含这些模式的新技能
用户可以稍后添加框架特定示例

示例：

backend-dev-guidelines 使用 Express，但分层架构
（路由 → 控制器 → 服务 → 仓库）也适用于 Django。

我可以创建一个包含以下内容的技能：
- 分层架构模式
- 关注点分离原则
- 错误处理最佳实践
- 测试策略

然后您可以在建立模式时添加 Django 特定示例。

选项 3：仅用作参考

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

流程：

用户浏览现有技能
您帮助从头创建新技能
使用现有技能的结构作为模板
遵循模块化模式（主文件 + 资源文件）

通常跨技术栈迁移的内容

架构与组织：

✅ 分层架构（路由/控制器/服务模式）
✅ 关注点分离
✅ 文件组织策略（features/ 模式）
✅ 渐进式披露（主文件 + 资源文件）
✅ 仓库模式用于数据访问

开发实践：

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

框架特定代码：

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

何时推荐适配 vs 跳过

推荐适配如果：

用户想要针对他们技术栈的类似指南
核心模式适用（分层架构等）
用户有时间帮助处理框架特定示例

推荐跳过如果：

技术栈完全不同
用户不需要这些模式
适配需要太长时间
用户更喜欢从头创建

集成钩子

必需钩子（始终可以安全复制）

skill-activation-prompt (UserPromptSubmit)

用途： 根据用户提示自动建议技能

集成（无需自定义）：

# 复制两个文件
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"
          }
        ]
      }
    ]
  }
}

此钩子完全通用 - 任何地方都适用，无需自定义！

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"
          }
        ]
      }
    ]
  }
}

此钩子完全通用 - 自动检测项目结构！

可选钩子（需要大量自定义）

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

⚠️ 警告： 这些钩子配置用于特定的多服务 monorepo 结构。

集成前询问：

"您有包含多个 TypeScript 服务的 monorepo 吗？"
"您的服务目录名称是什么？"
"您的 tsconfig.json 文件位于哪里？"

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

建议跳过 这些钩子
它们对于单服务项目来说过于复杂
用户可以手动运行 tsc --noEmit

对于复杂项目（多服务 monorepo）：

复制文件
必须编辑 tsc-check.sh - 找到此部分：

case "$repo" in
    email|exports|form|frontend|projects|uploads|users|utilities|events|database)
        echo "$repo"
        return 0
        ;;
esac

用用户的实际服务名称替换：

case "$repo" in
    api|web|auth|payments|notifications)  # ← 用户的服务
        echo "$repo"
        return 0
        ;;
esac

添加到 settings.json 前手动测试：

./.claude/hooks/tsc-check.sh

重要： 如果此钩子失败，它将阻止 Stop 事件。只有在确信它适用于他们的设置时才添加。

集成智能体

智能体是独立的 - 最容易集成！

标准智能体集成

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

就是这样！ 智能体立即工作，无需配置。

检查硬编码路径

一些智能体可能引用路径。复制前，阅读智能体文件并检查：

~/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

智能体特定说明

auth-route-tester / auth-route-debugger:

需要用户项目中的基于 JWT cookie 的认证
询问："您使用 JWT cookie 进行认证吗？"
如果答案是否定："这些智能体用于 JWT cookie 认证。跳过它们或要我适配？"

frontend-error-fixer:

可能引用截图路径
询问："截图应该保存在哪里？"

所有其他智能体：

原样复制，它们完全通用

集成斜杠命令

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

自定义路径

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

dev-docs 和 dev-docs-update:

查找 dev/active/ 路径引用
询问："您希望在哪里存储开发文档？"
更新命令文件中的路径

route-research-for-testing:

可能引用服务路径
询问他们关于 API 结构

通用模式与最佳实践

模式：询问项目结构

不要假设：

❌ "我将为您的 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"
  ]
}

模式：settings.json 集成

永远不要直接复制展示库的 settings.json！

相反，提取并合并 他们需要的部分：

读取他们现有的 settings.json
添加他们想要的钩子配置
保留他们现有的配置

示例合并：

{
  // ... 他们现有的配置 ...
  "hooks": {
    // ... 他们现有的钩子 ...
    "UserPromptSubmit": [  // ← 添加此部分
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh"
          }
        ]
      }
    ]
  }
}

验证清单

集成后，验证这些项目：

# 1. 钩子可执行
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. 钩子依赖已安装（如有 TypeScript 钩子）
ls $CLAUDE_PROJECT_DIR/.claude/hooks/node_modules/
# 如果存在 package.json 应该显示包

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

然后请用户测试：

"尝试编辑 [相关路径] 中的文件 - 技能应该激活"
"尝试问我关于 [主题] 的问题 - 我应该建议技能"

要避免的常见错误

❌ 不要：原样复制 settings.json

为什么： Stop 钩子引用不存在的服务 应该做： 仅提取 UserPromptSubmit 和 PostToolUse 部分

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

为什么： 用户没有 blog-api、auth-service 等 应该做： 询问他们的实际结构并更新

❌ 不要：跳过使钩子可执行

为什么： 没有执行权限钩子不会运行 应该做： 复制后始终运行 chmod +x

❌ 不要：假设 monorepo 结构

为什么： 大多数项目是单服务 应该做： 首先询问，然后自定义

❌ 不要：一次添加所有技能

为什么： 令人不知所措，可能不都相关 应该做： 询问哪些技能与他们的工作相关

❌ 不要：在未测试的情况下复制 Stop 钩子

为什么： 如果失败它们可能阻止 Stop 事件 应该做： 首先手动测试，只有在工作时才添加

示例集成对话

示例 1：添加后端技能

用户： "将 backend-dev-guidelines 技能添加到我的项目"

Claude 应该回应：

我将添加 backend-dev-guidelines 技能。首先，我需要了解
您的项目结构：

1. 这是有多个服务的 monorepo 还是单个后端应用？
2. 您的后端代码位于哪里？（例如 src/、backend/、server/）
3. 您使用 Express.js 吗？

用户： "单应用，代码在 src/api/ 中，是的我们使用 Express"

Claude 应该：

复制技能目录
使用 pathPattern 更新 skill-rules.json："src/api/**/*.ts"
验证复制正确
回应：

✅ 已添加 backend-dev-guidelines 技能！

配置：
- 当编辑 src/api/ 中的文件时技能触发
- 由 "controller"、"service"、"route"、"API" 等关键词激活

试试看：编辑 src/api/ 中的文件，您应该看到技能建议。

示例 2：设置钩子

用户： "设置技能激活钩子"

Claude 应该回应：

我将设置技能自动激活系统。这需要两个钩子：
1. skill-activation-prompt - 根据您的提示建议技能
2. post-tool-use-tracker - 跟踪文件更改

您已经有一个 .claude/settings.json 文件，还是我应该创建一个？

用户： "我已经有 settings.json"

Claude 应该：

读取他们的 settings.json
复制两个钩子文件
在 hooks 目录运行 npm install
将钩子配置添加到他们的 settings.json（保留现有配置）
使钩子可执行
回应：

✅ 技能激活钩子已安装！

我所做的：
- 复制了 skill-activation-prompt 钩子
- 复制了 post-tool-use-tracker 钩子
- 安装了依赖
- 添加到您的 settings.json

测试一下：问我"帮助进行后端开发"，我应该建议
backend-dev-guidelines 技能。

示例 3：添加智能体

用户： "添加 code-architecture-reviewer 智能体"

Claude 应该：

code-architecture-reviewer 智能体审查代码的架构问题
和最佳实践。此智能体独立工作，无需配置。

我现在将其复制到您的 .claude/agents/ 目录。

然后：

复制智能体文件
回应：

✅ 已添加 code-architecture-reviewer 智能体！

通过运行 Task 工具使用它：
- subagent_type: "code-architecture-reviewer"
- prompt: 要审查的代码描述

智能体将审查您的代码并提供架构反馈。

示例 3：技术栈不匹配

用户： "将 frontend-dev-guidelines 技能添加到我的 Vue 项目"

Claude 应该：

我看到您使用 Vue。frontend-dev-guidelines 技能专门为
React + MUI v7 设计。我有几个选项：

选项 1（推荐）：我可以创建 vue-dev-guidelines 技能，使用
React 技能作为模板。我将适配：
- Vue 的组件模式（Composition API、defineComponent）
- 将 MUI 示例替换为您的组件库
- 适配 Vue 模式的数据获取
- 保留：文件组织、性能原则、TypeScript 标准

选项 2：仅提取与框架无关的模式（文件组织、
性能、测试）不包含 React 特定代码。

选项 3：跳过它，帮助您从头创建 Vue 指南。

您更倾向于哪个选项？

用户： "选项 1 听起来不错，我使用 Vuetify"

Claude 应该：

将 frontend-dev-guidelines 复制为 vue-dev-guidelines
逐个资源文件
将 React 模式替换为 Vue Composition API
将 MUI 组件替换为 Vuetify
更新 skill-rules.json 包含 Vue 特定触发器（.vue 文件）
回应：

✅ 已创建适用于 Vue 3 + Vuetify 的 vue-dev-guidelines 技能！

我更改的内容：
- React.FC 组件 → Vue defineComponent
- MUI v7 示例 → Vuetify 组件
- TanStack Query → 您的数据获取方法
- 文件模式 → .vue 文件

我保留的内容：
- 文件组织（features/ 模式）
- 性能优化策略
- TypeScript 标准
- 加载/错误状态原则

试试编辑 .vue 文件 - 技能应该激活。

快速参考表

需要自定义什么？

组件	技术要求	自定义	询问什么
skill-developer	无	✅ 无	原样复制
backend-dev-guidelines	Express/Prisma/Node	⚠️ 路径 + 技术检查	"使用 Express/Prisma？" "后端在哪里？"
frontend-dev-guidelines	React/MUI v7	⚠️⚠️ 路径 + 框架	"使用 React/MUI v7？" "前端在哪里？"
route-tester	JWT cookies	⚠️ 认证 + 路径	"JWT cookie 认证？"
error-tracking	Sentry	⚠️ 路径	"使用 Sentry？" "后端在哪里？"
skill-activation-prompt	✅ 无	原样复制
post-tool-use-tracker	✅ 无	原样复制
tsc-check	⚠️⚠️⚠️ 大量	"Monorepo 还是单服务？"
所有智能体	✅ 最小	检查路径
所有命令	⚠️ 路径	"dev docs 放在哪里？"

何时建议跳过

组件	跳过如果...
tsc-check 钩子	单服务项目或不同构建设置
route-tester	不使用基于 JWT cookie 的认证
frontend-dev-guidelines	不使用 React + MUI
认证智能体	不使用基于 JWT cookie 的认证

Claude 的最后提示

当用户说"全部添加"时：

从必需品开始：技能激活钩子 + 1-2 个相关技能
不要用所有 5 个技能 + 10 个智能体让他们感到不知所措
询问他们实际需要什么

当某事不起作用时：

检查验证清单
验证路径匹配他们的结构
手动测试钩子
检查 JSON 语法错误

当用户不确定时：

建议仅从技能激活钩子开始
添加后端或前端技能（他们使用的）
根据需要稍后添加更多

始终解释您在做什么：

显示您运行的命令
解释为什么询问问题
集成后提供清晰的后续步骤

记住： 这是一个参考库，不是可运行的应用程序。您的任务是帮助用户为他们的特定项目结构精选和适配组件。

23 KiB Raw Blame History Unescape Escape

Claude 集成指南

概述

技术栈兼容性检查

前端技能

后端技能

技术无关的技能

通用集成模式

集成技能

分步流程

1. 了解他们的项目

2. 复制技能

3. 处理 skill-rules.json

4. 自定义路径模式

5. 验证集成

技能特定说明

backend-dev-guidelines

frontend-dev-guidelines

route-tester

error-tracking

skill-developer

为不同技术栈适配技能

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

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

选项 3：仅用作参考

通常跨技术栈迁移的内容

何时推荐适配 vs 跳过

集成钩子

必需钩子（始终可以安全复制）

skill-activation-prompt (UserPromptSubmit)

post-tool-use-tracker (PostToolUse)

可选钩子（需要大量自定义）

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

集成智能体

标准智能体集成

检查硬编码路径

智能体特定说明

集成斜杠命令

自定义路径

通用模式与最佳实践

模式：询问项目结构

模式：自定义 skill-rules.json

模式：settings.json 集成

验证清单

要避免的常见错误

❌ 不要：原样复制 settings.json

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

❌ 不要：跳过使钩子可执行

❌ 不要：假设 monorepo 结构

❌ 不要：一次添加所有技能

❌ 不要：在未测试的情况下复制 Stop 钩子

示例集成对话

示例 1：添加后端技能

示例 2：设置钩子

示例 3：添加智能体

示例 3：技术栈不匹配

快速参考表

需要自定义什么？

何时建议跳过

Claude 的最后提示

23 KiB

Raw Blame History