docs: 添加中文翻译文档
添加三个中文翻译文档： - README_zh.md：Claude Code基础设施展示库概述 - CLAUDE_INTEGRATION_GUIDE_zh.md：Claude集成指南 - dev/README_zh.md：Dev Docs模式文档
This commit is contained in:
dzq
parent
bf0a30e0ae
commit
e16a4ccf1d
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,883 @@
|
|||
# Claude 集成指南
|
||||
|
||||
**致 Claude Code：** 当用户要求您将此展示库中的组件集成到他们的项目中时，请仔细遵循这些说明。
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
此仓库是 Claude Code 基础设施组件的**参考库**。用户会要求您帮助将特定部分集成到他们的项目中。您的角色是：
|
||||
|
||||
1. **提出澄清性问题** 了解他们的项目结构
|
||||
2. **复制适当的文件**
|
||||
3. **为他们量身定制配置**
|
||||
4. **验证集成是否正常工作**
|
||||
|
||||
**核心原则：** 永远先询问，再假设项目结构。适用于一个项目的方案不一定适用于另一个项目。
|
||||
|
||||
---
|
||||
|
||||
## 技术栈兼容性检查
|
||||
|
||||
**关键：** 在集成技能之前，验证用户的技术栈是否与技能要求匹配。
|
||||
|
||||
### 前端技能
|
||||
|
||||
**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 适用于大多数技术栈
|
||||
|
||||
---
|
||||
|
||||
## 通用集成模式
|
||||
|
||||
当用户说：**"添加 [组件] 到我的项目"**
|
||||
|
||||
1. 识别组件类型（技能/钩子/智能体/命令）
|
||||
2. **检查技术栈兼容性**（适用于前端/后端技能）
|
||||
3. 询问他们的项目结构
|
||||
4. 复制文件或为他们适配技术栈
|
||||
5. 为他们量身定制配置
|
||||
6. 验证集成
|
||||
7. 提供后续步骤
|
||||
|
||||
---
|
||||
|
||||
## 集成技能
|
||||
|
||||
### 分步流程
|
||||
|
||||
**当用户请求技能**（例如，"添加 backend-dev-guidelines"）：
|
||||
|
||||
#### 1. 了解他们的项目
|
||||
|
||||
**询问这些问题：**
|
||||
- "您的项目结构是什么？单应用、monorepo 还是多服务？"
|
||||
- "您的 [后端/前端] 代码位于哪里？"
|
||||
- "您使用什么框架/技术？"
|
||||
|
||||
#### 2. 复制技能
|
||||
|
||||
```bash
|
||||
cp -r /path/to/showcase/.claude/skills/[skill-name] \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/skills/
|
||||
```
|
||||
|
||||
#### 3. 处理 skill-rules.json
|
||||
|
||||
**检查是否存在：**
|
||||
```bash
|
||||
ls $CLAUDE_PROJECT_DIR/.claude/skills/skill-rules.json
|
||||
```
|
||||
|
||||
**如果不存在：**
|
||||
- 从展示库复制模板
|
||||
- 删除用户不需要的技能
|
||||
- 为他们的项目定制
|
||||
|
||||
**如果存在：**
|
||||
- 读取他们当前的 skill-rules.json
|
||||
- 添加新的技能条目
|
||||
- 小心合并，避免破坏现有技能
|
||||
|
||||
#### 4. 自定义路径模式
|
||||
|
||||
**关键：** 更新 `skill-rules.json` 中的 `pathPatterns` 以匹配他们的结构：
|
||||
|
||||
**示例 - 用户有 monorepo：**
|
||||
```json
|
||||
{
|
||||
"backend-dev-guidelines": {
|
||||
"fileTriggers": {
|
||||
"pathPatterns": [
|
||||
"packages/api/src/**/*.ts",
|
||||
"packages/server/src/**/*.ts",
|
||||
"apps/backend/**/*.ts"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**示例 - 用户有单个后端：**
|
||||
```json
|
||||
{
|
||||
"backend-dev-guidelines": {
|
||||
"fileTriggers": {
|
||||
"pathPatterns": [
|
||||
"src/**/*.ts",
|
||||
"backend/**/*.ts"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**安全通用模式**（不确定时使用）：
|
||||
```json
|
||||
{
|
||||
"pathPatterns": [
|
||||
"**/*.ts", // 所有 TypeScript 文件
|
||||
"src/**/*.ts", // 常见 src 目录
|
||||
"backend/**/*.ts" // 常见 backend 目录
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. 验证集成
|
||||
|
||||
```bash
|
||||
# 检查技能是否已复制
|
||||
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：适配现有技能（推荐）
|
||||
|
||||
**何时使用：** 用户想要针对不同技术有类似的指南
|
||||
|
||||
**流程：**
|
||||
1. **复制技能作为起点：**
|
||||
```bash
|
||||
cp -r showcase/.claude/skills/frontend-dev-guidelines \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/skills/vue-dev-guidelines
|
||||
```
|
||||
|
||||
2. **识别需要更改的部分：**
|
||||
- 框架特定代码示例（React → Vue）
|
||||
- 库 API（MUI → Vuetify/PrimeVue）
|
||||
- 导入语句
|
||||
- 组件模式
|
||||
|
||||
3. **保留可以迁移的部分：**
|
||||
- 文件组织原则
|
||||
- 性能优化策略
|
||||
- TypeScript 标准
|
||||
- 通用最佳实践
|
||||
|
||||
4. **系统地替换示例：**
|
||||
- 询问用户他们技术栈中的等效模式
|
||||
- 将代码示例更新为他们的框架
|
||||
- 保持整体结构和章节
|
||||
|
||||
5. **更新技能名称和触发器：**
|
||||
- 适当地重命名技能
|
||||
- 更新 skill-rules.json 触发器以适应他们的技术栈
|
||||
- 测试激活
|
||||
|
||||
**示例 - 为 Vue 适配 frontend-dev-guidelines：**
|
||||
```
|
||||
我将基于 React 技能结构创建 vue-dev-guidelines：
|
||||
- 将 React.FC → Vue defineComponent
|
||||
- 将 useSuspenseQuery → Vue composables
|
||||
- 将 MUI 组件 → [他们的组件库]
|
||||
- 保留：文件组织、性能模式、TypeScript 指南
|
||||
|
||||
这需要几分钟时间。听起来不错吧？
|
||||
```
|
||||
|
||||
### 选项 2：提取与框架无关的模式
|
||||
|
||||
**何时使用：** 技术栈差异很大，但核心原则适用
|
||||
|
||||
**流程：**
|
||||
1. 阅读现有技能
|
||||
2. 识别与框架无关的模式：
|
||||
- 分层架构（后端）
|
||||
- 文件组织策略
|
||||
- 性能优化原则
|
||||
- 测试策略
|
||||
- 错误处理理念
|
||||
|
||||
3. 创建仅包含这些模式的新技能
|
||||
4. 用户可以稍后添加框架特定示例
|
||||
|
||||
**示例：**
|
||||
```
|
||||
backend-dev-guidelines 使用 Express，但分层架构
|
||||
（路由 → 控制器 → 服务 → 仓库）也适用于 Django。
|
||||
|
||||
我可以创建一个包含以下内容的技能：
|
||||
- 分层架构模式
|
||||
- 关注点分离原则
|
||||
- 错误处理最佳实践
|
||||
- 测试策略
|
||||
|
||||
然后您可以在建立模式时添加 Django 特定示例。
|
||||
```
|
||||
|
||||
### 选项 3：仅用作参考
|
||||
|
||||
**何时使用：** 差异太大无法适配，但用户想要灵感
|
||||
|
||||
**流程：**
|
||||
1. 用户浏览现有技能
|
||||
2. 您帮助从头创建新技能
|
||||
3. 使用现有技能的结构作为模板
|
||||
4. 遵循模块化模式（主文件 + 资源文件）
|
||||
|
||||
### 通常跨技术栈迁移的内容
|
||||
|
||||
**架构与组织：**
|
||||
- ✅ 分层架构（路由/控制器/服务模式）
|
||||
- ✅ 关注点分离
|
||||
- ✅ 文件组织策略（features/ 模式）
|
||||
- ✅ 渐进式披露（主文件 + 资源文件）
|
||||
- ✅ 仓库模式用于数据访问
|
||||
|
||||
**开发实践：**
|
||||
- ✅ 错误处理理念
|
||||
- ✅ 输入验证重要性
|
||||
- ✅ 测试策略
|
||||
- ✅ 性能优化原则
|
||||
- ✅ TypeScript 最佳实践
|
||||
|
||||
**框架特定代码：**
|
||||
- ❌ React hooks → 不要迁移到 Vue/Angular
|
||||
- ❌ MUI 组件 → 不同的组件库
|
||||
- ❌ Prisma 查询 → 不同的 ORM 语法
|
||||
- ❌ Express middleware → 不同的框架模式
|
||||
- ❌ 路由实现 → 框架特定
|
||||
|
||||
### 何时推荐适配 vs 跳过
|
||||
|
||||
**推荐适配如果：**
|
||||
- 用户想要针对他们技术栈的类似指南
|
||||
- 核心模式适用（分层架构等）
|
||||
- 用户有时间帮助处理框架特定示例
|
||||
|
||||
**推荐跳过如果：**
|
||||
- 技术栈完全不同
|
||||
- 用户不需要这些模式
|
||||
- 适配需要太长时间
|
||||
- 用户更喜欢从头创建
|
||||
|
||||
---
|
||||
|
||||
## 集成钩子
|
||||
|
||||
### 必需钩子（始终可以安全复制）
|
||||
|
||||
#### skill-activation-prompt (UserPromptSubmit)
|
||||
|
||||
**用途：** 根据用户提示自动建议技能
|
||||
|
||||
**集成（无需自定义）：**
|
||||
|
||||
```bash
|
||||
# 复制两个文件
|
||||
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：**
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"UserPromptSubmit": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**此钩子完全通用** - 任何地方都适用，无需自定义！
|
||||
|
||||
#### post-tool-use-tracker (PostToolUse)
|
||||
|
||||
**用途：** 跟踪文件更改用于上下文管理
|
||||
|
||||
**集成（无需自定义）：**
|
||||
|
||||
```bash
|
||||
# 复制文件
|
||||
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：**
|
||||
```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 结构。
|
||||
|
||||
**集成前询问：**
|
||||
1. "您有包含多个 TypeScript 服务的 monorepo 吗？"
|
||||
2. "您的服务目录名称是什么？"
|
||||
3. "您的 tsconfig.json 文件位于哪里？"
|
||||
|
||||
**对于简单项目（单个服务）：**
|
||||
- **建议跳过** 这些钩子
|
||||
- 它们对于单服务项目来说过于复杂
|
||||
- 用户可以手动运行 `tsc --noEmit`
|
||||
|
||||
**对于复杂项目（多服务 monorepo）：**
|
||||
|
||||
1. 复制文件
|
||||
2. **必须编辑** tsc-check.sh - 找到此部分：
|
||||
```bash
|
||||
case "$repo" in
|
||||
email|exports|form|frontend|projects|uploads|users|utilities|events|database)
|
||||
echo "$repo"
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
3. 用用户的实际服务名称替换：
|
||||
```bash
|
||||
case "$repo" in
|
||||
api|web|auth|payments|notifications) # ← 用户的服务
|
||||
echo "$repo"
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
4. 添加到 settings.json 前手动测试：
|
||||
```bash
|
||||
./.claude/hooks/tsc-check.sh
|
||||
```
|
||||
|
||||
**重要：** 如果此钩子失败，它将阻止 Stop 事件。只有在确信它适用于他们的设置时才添加。
|
||||
|
||||
---
|
||||
|
||||
## 集成智能体
|
||||
|
||||
**智能体是独立的** - 最容易集成！
|
||||
|
||||
### 标准智能体集成
|
||||
|
||||
```bash
|
||||
# 复制智能体文件
|
||||
cp showcase/.claude/agents/[agent-name].md \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/agents/
|
||||
```
|
||||
|
||||
**就是这样！** 智能体立即工作，无需配置。
|
||||
|
||||
### 检查硬编码路径
|
||||
|
||||
一些智能体可能引用路径。**复制前，阅读智能体文件并检查：**
|
||||
|
||||
- `~/git/old-project/` → 应该是 `$CLAUDE_PROJECT_DIR` 或 `.`
|
||||
- `/root/git/project/` → 应该是 `$CLAUDE_PROJECT_DIR` 或 `.`
|
||||
- 硬编码的截图路径 → 询问用户他们希望在哪里保存截图
|
||||
|
||||
**如果找到，更新它们：**
|
||||
```bash
|
||||
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:**
|
||||
- 可能引用截图路径
|
||||
- 询问："截图应该保存在哪里？"
|
||||
|
||||
**所有其他智能体：**
|
||||
- 原样复制，它们完全通用
|
||||
|
||||
---
|
||||
|
||||
## 集成斜杠命令
|
||||
|
||||
```bash
|
||||
# 复制命令文件
|
||||
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：**
|
||||
```json
|
||||
{
|
||||
"pathPatterns": [
|
||||
"packages/*/src/**/*.ts",
|
||||
"apps/*/src/**/*.tsx"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**用户有 Nx monorepo：**
|
||||
```json
|
||||
{
|
||||
"pathPatterns": [
|
||||
"apps/api/src/**/*.ts",
|
||||
"libs/*/src/**/*.ts"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**用户有简单结构：**
|
||||
```json
|
||||
{
|
||||
"pathPatterns": [
|
||||
"src/**/*.ts",
|
||||
"backend/**/*.ts"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 模式：settings.json 集成
|
||||
|
||||
**永远不要直接复制展示库的 settings.json！**
|
||||
|
||||
相反，**提取并合并** 他们需要的部分：
|
||||
|
||||
1. 读取他们现有的 settings.json
|
||||
2. 添加他们想要的钩子配置
|
||||
3. 保留他们现有的配置
|
||||
|
||||
**示例合并：**
|
||||
```json
|
||||
{
|
||||
// ... 他们现有的配置 ...
|
||||
"hooks": {
|
||||
// ... 他们现有的钩子 ...
|
||||
"UserPromptSubmit": [ // ← 添加此部分
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 验证清单
|
||||
|
||||
集成后，**验证这些项目：**
|
||||
|
||||
```bash
|
||||
# 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 应该：**
|
||||
1. 复制技能目录
|
||||
2. 使用 pathPattern 更新 skill-rules.json：`"src/api/**/*.ts"`
|
||||
3. 验证复制正确
|
||||
4. 回应：
|
||||
```
|
||||
✅ 已添加 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 应该：**
|
||||
1. 读取他们的 settings.json
|
||||
2. 复制两个钩子文件
|
||||
3. 在 hooks 目录运行 npm install
|
||||
4. 将钩子配置添加到他们的 settings.json（保留现有配置）
|
||||
5. 使钩子可执行
|
||||
6. 回应：
|
||||
```
|
||||
✅ 技能激活钩子已安装！
|
||||
|
||||
我所做的：
|
||||
- 复制了 skill-activation-prompt 钩子
|
||||
- 复制了 post-tool-use-tracker 钩子
|
||||
- 安装了依赖
|
||||
- 添加到您的 settings.json
|
||||
|
||||
测试一下：问我"帮助进行后端开发"，我应该建议
|
||||
backend-dev-guidelines 技能。
|
||||
```
|
||||
|
||||
### 示例 3：添加智能体
|
||||
|
||||
**用户：** "添加 code-architecture-reviewer 智能体"
|
||||
|
||||
**Claude 应该：**
|
||||
```
|
||||
code-architecture-reviewer 智能体审查代码的架构问题
|
||||
和最佳实践。此智能体独立工作，无需配置。
|
||||
|
||||
我现在将其复制到您的 .claude/agents/ 目录。
|
||||
```
|
||||
|
||||
**然后：**
|
||||
1. 复制智能体文件
|
||||
2. 回应：
|
||||
```
|
||||
✅ 已添加 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 应该：**
|
||||
1. 将 frontend-dev-guidelines 复制为 vue-dev-guidelines
|
||||
2. 逐个资源文件
|
||||
3. 将 React 模式替换为 Vue Composition API
|
||||
4. 将 MUI 组件替换为 Vuetify
|
||||
5. 更新 skill-rules.json 包含 Vue 特定触发器（.vue 文件）
|
||||
6. 回应：
|
||||
```
|
||||
✅ 已创建适用于 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 语法错误
|
||||
|
||||
**当用户不确定时：**
|
||||
- 建议仅从技能激活钩子开始
|
||||
- 添加后端**或**前端技能（他们使用的）
|
||||
- 根据需要稍后添加更多
|
||||
|
||||
**始终解释您在做什么：**
|
||||
- 显示您运行的命令
|
||||
- 解释为什么询问问题
|
||||
- 集成后提供清晰的后续步骤
|
||||
|
||||
---
|
||||
|
||||
**记住：** 这是一个参考库，不是可运行的应用程序。您的任务是帮助用户为他们的特定项目结构精选和适配组件。
|
||||
|
|
@ -0,0 +1,359 @@
|
|||
# Claude Code 基础设施展示库
|
||||
|
||||
**精心策划的生产就绪 Claude Code 基础设施参考库。**
|
||||
|
||||
源于管理复杂 TypeScript 微服务项目的 6 个月实际使用经验，本展示库提供了解决"技能无法自动激活"问题的模式和系统，并将 Claude Code 扩展到企业级开发。
|
||||
|
||||
> **这不是一个可运行的应用程序** - 它是一个参考库。将您需要的内容复制到您自己的项目中即可。
|
||||
|
||||
---
|
||||
|
||||
## 内容概览
|
||||
|
||||
**生产就绪的基础设施包含：**
|
||||
- ✅ 通过钩子实现技能自动激活
|
||||
- ✅ 模块化技能模式（500 行规则与渐进式披露）
|
||||
- ✅ 专门处理复杂任务的智能体
|
||||
- ✅ 能在上下文重置后存活的开发文档系统
|
||||
- ✅ 使用通用博客域的综合示例
|
||||
|
||||
**构建所需时间投入：** 6 个月的迭代开发
|
||||
**集成到您项目的时间：** 15-30 分钟
|
||||
|
||||
---
|
||||
|
||||
## 快速开始 - 选择您的路径
|
||||
|
||||
### 🤖 使用 Claude Code 进行集成？
|
||||
|
||||
**Claude：** 阅读 [`CLAUDE_INTEGRATION_GUIDE.md`](CLAUDE_INTEGRATION_GUIDE.md) 获取针对 AI 辅助设置的详细集成说明。
|
||||
|
||||
### 🎯 我想要技能自动激活
|
||||
|
||||
**突破性功能：** 真正能在您需要时激活的技能。
|
||||
|
||||
**您需要的：**
|
||||
1. 技能激活钩子（2 个文件）
|
||||
2. 与您工作相关的 1-2 个技能
|
||||
3. 15 分钟时间
|
||||
|
||||
**👉 [设置指南：.claude/hooks/README.md](.claude/hooks/README.md)**
|
||||
|
||||
### 📚 我想要添加一个技能
|
||||
|
||||
浏览[技能目录](.claude/skills/)并复制您需要的内容。
|
||||
|
||||
**可用技能：**
|
||||
- **backend-dev-guidelines** - Node.js/Express/TypeScript 模式
|
||||
- **frontend-dev-guidelines** - React/TypeScript/MUI v7 模式
|
||||
- **skill-developer** - 用于创建技能的元技能
|
||||
- **route-tester** - 测试已认证的 API 路由
|
||||
- **error-tracking** - Sentry 集成模式
|
||||
|
||||
**👉 [技能指南：.claude/skills/README.md](.claude/skills/README.md)**
|
||||
|
||||
### 🤖 我想要专门的智能体
|
||||
|
||||
10 个生产就绪的智能体，适用于复杂任务：
|
||||
- 代码架构审查
|
||||
- 重构辅助
|
||||
- 文档生成
|
||||
- 错误调试
|
||||
- 等等...
|
||||
|
||||
**👉 [智能体指南：.claude/agents/README.md](.claude/agents/README.md)**
|
||||
|
||||
---
|
||||
|
||||
## 这与别的方案有何不同？
|
||||
|
||||
### 自动激活突破
|
||||
|
||||
**问题：** Claude Code 技能只是静静地待在那里。您必须记住使用它们。
|
||||
|
||||
**解决方案：** UserPromptSubmit 钩子能够：
|
||||
- 分析您的提示
|
||||
- 检查文件上下文
|
||||
- 自动建议相关技能
|
||||
- 通过 `skill-rules.json` 配置工作
|
||||
|
||||
**结果：** 技能在您需要时激活，而不是在您记住时激活。
|
||||
|
||||
### 生产验证模式
|
||||
|
||||
这些不是理论示例 - 它们是从以下项目中提取的：
|
||||
- ✅ 生产环境中的 6 个微服务
|
||||
- ✅ 50,000+ 行 TypeScript 代码
|
||||
- ✅ 具有复杂数据网格的 React 前端
|
||||
- ✅ 复杂的工作流引擎
|
||||
- ✅ 6 个月的日常 Claude Code 使用经验
|
||||
|
||||
这些模式有效是因为它们解决了实际问题。
|
||||
|
||||
### 模块化技能（500 行规则）
|
||||
|
||||
大型技能会触及上下文限制。解决方案是：
|
||||
|
||||
```
|
||||
技能名称/
|
||||
SKILL.md # <500 行，高级指南
|
||||
resources/
|
||||
topic-1.md # 每个 <500 行
|
||||
topic-2.md
|
||||
topic-3.md
|
||||
```
|
||||
|
||||
**渐进式披露：** Claude 首先加载主技能，仅在需要时加载资源文件。
|
||||
|
||||
---
|
||||
|
||||
## 仓库结构
|
||||
|
||||
```
|
||||
.claude/
|
||||
├── skills/ # 5 个生产技能
|
||||
│ ├── backend-dev-guidelines/ (12 个资源文件)
|
||||
│ ├── frontend-dev-guidelines/ (11 个资源文件)
|
||||
│ ├── skill-developer/ (7 个资源文件)
|
||||
│ ├── route-tester/
|
||||
│ ├── error-tracking/
|
||||
│ └── skill-rules.json # 技能激活配置
|
||||
├── hooks/ # 6 个自动化钩子
|
||||
│ ├── skill-activation-prompt.* (必需)
|
||||
│ ├── post-tool-use-tracker.sh (必需)
|
||||
│ ├── tsc-check.sh (可选，需要自定义)
|
||||
│ └── trigger-build-resolver.sh (可选)
|
||||
├── agents/ # 10 个专门智能体
|
||||
│ ├── code-architecture-reviewer.md
|
||||
│ ├── refactor-planner.md
|
||||
│ ├── frontend-error-fixer.md
|
||||
│ └── ... 7 个更多
|
||||
└── commands/ # 3 个斜杠命令
|
||||
├── dev-docs.md
|
||||
└── ...
|
||||
|
||||
dev/
|
||||
└── active/ # Dev Docs 模式示例
|
||||
└── public-infrastructure-repo/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 组件目录
|
||||
|
||||
### 🎨 技能 (5)
|
||||
|
||||
| 技能 | 行数 | 用途 | 适用于 |
|
||||
|------|------|------|--------|
|
||||
| [**skill-developer**](.claude/skills/skill-developer/) | 426 | 创建和管理技能 | 元开发 |
|
||||
| [**backend-dev-guidelines**](.claude/skills/backend-dev-guidelines/) | 304 | Express/Prisma/Sentry 模式 | 后端 API |
|
||||
| [**frontend-dev-guidelines**](.claude/skills/frontend-dev-guidelines/) | 398 | React/MUI v7/TypeScript | React 前端 |
|
||||
| [**route-tester**](.claude/skills/route-tester/) | 389 | 测试已认证路由 | API 测试 |
|
||||
| [**error-tracking**](.claude/skills/error-tracking/) | ~250 | Sentry 集成 | 错误监控 |
|
||||
|
||||
**所有技能都遵循模块化模式** - 主文件 + 渐进式披露的资源文件。
|
||||
|
||||
**👉 [如何集成技能 →](.claude/skills/README.md)**
|
||||
|
||||
### 🪝 钩子 (6)
|
||||
|
||||
| 钩子 | 类型 | 必需？ | 自定义需求 |
|
||||
|------|------|--------|------------|
|
||||
| skill-activation-prompt | UserPromptSubmit | ✅ 是 | ✅ 无需 |
|
||||
| post-tool-use-tracker | PostToolUse | ✅ 是 | ✅ 无需 |
|
||||
| tsc-check | Stop | ⚠️ 可选 | ⚠️ 大量 - 仅限 monorepo |
|
||||
| trigger-build-resolver | Stop | ⚠️ 可选 | ⚠️ 大量 - 仅限 monorepo |
|
||||
| error-handling-reminder | Stop | ⚠️ 可选 | ⚠️ 中等 |
|
||||
| stop-build-check-enhanced | Stop | ⚠️ 可选 | ⚠️ 中等 |
|
||||
|
||||
**从两个必需钩子开始** - 它们实现技能自动激活，开箱即用。
|
||||
|
||||
**👉 [钩子设置指南 →](.claude/hooks/README.md)**
|
||||
|
||||
### 🤖 智能体 (10)
|
||||
|
||||
**独立运行 - 只需复制即可使用！**
|
||||
|
||||
| 智能体 | 用途 |
|
||||
|-------|------|
|
||||
| code-architecture-reviewer | 审查代码架构一致性 |
|
||||
| code-refactor-master | 规划和执行重构 |
|
||||
| documentation-architect | 生成综合文档 |
|
||||
| frontend-error-fixer | 调试前端错误 |
|
||||
| plan-reviewer | 审查开发计划 |
|
||||
| refactor-planner | 创建重构策略 |
|
||||
| web-research-specialist | 在线研究技术问题 |
|
||||
| auth-route-tester | 测试已认证端点 |
|
||||
| auth-route-debugger | 调试认证问题 |
|
||||
| auto-error-resolver | 自动修复 TypeScript 错误 |
|
||||
|
||||
**👉 [智能体工作原理 →](.claude/agents/README.md)**
|
||||
|
||||
### 💬 斜杠命令 (3)
|
||||
|
||||
| 命令 | 用途 |
|
||||
|---------|------|
|
||||
| /dev-docs | 创建结构化开发文档 |
|
||||
| /dev-docs-update | 在上下文重置前更新文档 |
|
||||
| /route-research-for-testing | 研究测试路由模式 |
|
||||
|
||||
---
|
||||
|
||||
## 核心概念
|
||||
|
||||
### 钩子 + skill-rules.json = 自动激活
|
||||
|
||||
**该系统：**
|
||||
1. **skill-activation-prompt 钩子** 在每个用户提示时运行
|
||||
2. 检查 **skill-rules.json** 中的触发模式
|
||||
3. 自动建议相关技能
|
||||
4. 仅在需要时加载技能
|
||||
|
||||
**这解决了 Claude Code 技能的第 1 号问题：** 它们不会自动激活。
|
||||
|
||||
### 渐进式披露（500 行规则）
|
||||
|
||||
**问题：** 大型技能会触及上下文限制
|
||||
|
||||
**解决方案：** 模块化结构
|
||||
- 主 SKILL.md < 500 行（概览 + 导航）
|
||||
- 资源文件每个 < 500 行（深入探讨）
|
||||
- Claude 根据需要增量加载
|
||||
|
||||
**示例：** backend-dev-guidelines 有 12 个资源文件，涵盖路由、控制器、服务、仓库、测试等。
|
||||
|
||||
### Dev Docs 模式
|
||||
|
||||
**问题：** 上下文重置会丢失项目上下文
|
||||
|
||||
**解决方案：** 三文件结构
|
||||
- `[task]-plan.md` - 战略计划
|
||||
- `[task]-context.md` - 关键决策和文件
|
||||
- `[task]-tasks.md` - 清单格式
|
||||
|
||||
**适用于：** `/dev-docs` 斜杠命令自动生成这些文件
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 重要：直接使用不会生效的内容
|
||||
|
||||
### settings.json
|
||||
包含的 `settings.json` 仅是**示例**：
|
||||
- Stop 钩子引用特定的 monorepo 结构
|
||||
- 服务名称（blog-api 等）是示例
|
||||
- MCP 服务器在您的设置中可能不存在
|
||||
|
||||
**使用方法：**
|
||||
1. 仅提取 UserPromptSubmit 和 PostToolUse 钩子
|
||||
2. 自定义或跳过 Stop 钩子
|
||||
3. 为您的设置更新 MCP 服务器列表
|
||||
|
||||
### 博客域示例
|
||||
技能使用通用博客示例（Post/Comment/User）：
|
||||
- 这些是**教学示例**，不是要求
|
||||
- 模式适用于任何域（电商、SaaS 等）
|
||||
- 将模式适配到您的业务逻辑
|
||||
|
||||
### 钩子目录结构
|
||||
一些钩子期望特定结构：
|
||||
- `tsc-check.sh` 期望服务目录
|
||||
- 基于您的项目布局进行自定义
|
||||
|
||||
---
|
||||
|
||||
## 集成工作流
|
||||
|
||||
**推荐方法：**
|
||||
|
||||
### 阶段 1：技能激活（15 分钟）
|
||||
1. 复制 skill-activation-prompt 钩子
|
||||
2. 复制 post-tool-use-tracker 钩子
|
||||
3. 更新 settings.json
|
||||
4. 安装钩子依赖
|
||||
|
||||
### 阶段 2：添加第一个技能（10 分钟）
|
||||
1. 选择 1 个相关技能
|
||||
2. 复制技能目录
|
||||
3. 创建/更新 skill-rules.json
|
||||
4. 自定义路径模式
|
||||
|
||||
### 阶段 3：测试和迭代（5 分钟）
|
||||
1. 编辑文件 - 技能应该激活
|
||||
2. 提问 - 应该建议技能
|
||||
3. 根据需要添加更多技能
|
||||
|
||||
### 阶段 4：可选增强
|
||||
- 添加您觉得有用的智能体
|
||||
- 添加斜杠命令
|
||||
- 自定义 Stop 钩子（高级）
|
||||
|
||||
---
|
||||
|
||||
## 获取帮助
|
||||
|
||||
### 对于用户
|
||||
**集成问题？**
|
||||
1. 查看 [CLAUDE_INTEGRATION_GUIDE.md](CLAUDE_INTEGRATION_GUIDE.md)
|
||||
2. 向 Claude 询问："为什么 [技能] 没有激活？"
|
||||
3. 提出包含您项目结构的问题
|
||||
|
||||
### 对于 Claude Code
|
||||
帮助用户集成时：
|
||||
1. **首先阅读 CLAUDE_INTEGRATION_GUIDE.md**
|
||||
2. 询问他们的项目结构
|
||||
3. 自定义，而不是盲目复制
|
||||
4. 集成后验证
|
||||
|
||||
---
|
||||
|
||||
## 这解决了什么问题
|
||||
|
||||
### 使用此基础设施前
|
||||
|
||||
❌ 技能不会自动激活
|
||||
❌ 必须记住使用哪个技能
|
||||
❌ 大型技能触及上下文限制
|
||||
❌ 上下文重置丢失项目知识
|
||||
❌ 开发中缺乏一致性
|
||||
❌ 每次都需要手动调用智能体
|
||||
|
||||
### 使用此基础设施后
|
||||
|
||||
✅ 技能根据上下文自动建议
|
||||
✅ 钩子在适当时机触发技能
|
||||
✅ 模块化技能保持在上下文限制内
|
||||
✅ Dev Docs 在重置后保留知识
|
||||
✅ 通过护栏实现一致的模式
|
||||
✅ 智能体简化复杂任务
|
||||
|
||||
---
|
||||
|
||||
## 社区
|
||||
|
||||
**觉得有用？**
|
||||
|
||||
- ⭐ 为这个仓库点星
|
||||
- 🐛 报告问题或建议改进
|
||||
- 💬 分享您自己的技能/钩子/智能体
|
||||
- 📝 从您的域贡献示例
|
||||
|
||||
**背景：**
|
||||
这套基础设施在我发布到 Reddit 的帖子["Claude Code is a Beast – Tips from 6 Months of Hardcore Use"](https://www.reddit.com/r/ClaudeAI/comments/1oivjvm/claude_code_is_a_beast_tips_from_6_months_of/)中有详细介绍。在收到数百个请求后，创建了这个展示库来帮助社区实施这些模式。
|
||||
|
||||
---
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT 许可证 - 在您的项目中自由使用，无论是商业项目还是个人项目。
|
||||
|
||||
---
|
||||
|
||||
## 快速链接
|
||||
|
||||
- 📖 [Claude 集成指南](CLAUDE_INTEGRATION_GUIDE.md) - 用于 AI 辅助设置
|
||||
- 🎨 [技能文档](.claude/skills/README.md)
|
||||
- 🪝 [钩子设置](.claude/hooks/README.md)
|
||||
- 🤖 [智能体指南](.claude/agents/README.md)
|
||||
- 📝 [Dev Docs 模式](dev/README.md)
|
||||
|
||||
**开始使用：** 复制两个必需钩子，添加一个技能，见证自动激活魔法发生。
|
||||
|
|
@ -0,0 +1,424 @@
|
|||
# Dev Docs 模式
|
||||
|
||||
一种在 Claude Code 会话和上下文重置之间维护项目上下文的方法论。
|
||||
|
||||
---
|
||||
|
||||
## 问题
|
||||
|
||||
**上下文重置会丢失一切：**
|
||||
- 实施决策
|
||||
- 关键文件及其用途
|
||||
- 任务进度
|
||||
- 技术约束
|
||||
- 为什么选择某些方法
|
||||
|
||||
**重置后，Claude 必须重新发现一切。**
|
||||
|
||||
---
|
||||
|
||||
## 解决方案：持久化开发文档
|
||||
|
||||
一个三文件结构，捕获继续工作所需的一切：
|
||||
|
||||
```
|
||||
dev/active/[task-name]/
|
||||
├── [task-name]-plan.md # 战略计划
|
||||
├── [task-name]-context.md # 关键决策和文件
|
||||
└── [task-name]-tasks.md # 清单格式
|
||||
```
|
||||
|
||||
**这些文件在上下文重置后仍然存在** - Claude 读取它们即可立即恢复状态。
|
||||
|
||||
---
|
||||
|
||||
## 三文件结构
|
||||
|
||||
### 1. [task-name]-plan.md
|
||||
|
||||
**用途：** 实施战略计划
|
||||
|
||||
**包含：**
|
||||
- 执行摘要
|
||||
- 当前状态分析
|
||||
- 提议的未来状态
|
||||
- 实施阶段
|
||||
- 带有验收标准的详细任务
|
||||
- 风险评估
|
||||
- 成功指标
|
||||
- 时间线估算
|
||||
|
||||
**何时创建：** 复杂任务开始时
|
||||
|
||||
**何时更新：** 范围变更或发现新阶段时
|
||||
|
||||
**示例：**
|
||||
```markdown
|
||||
# 功能名称 - 实施计划
|
||||
|
||||
## 执行摘要
|
||||
我们正在构建什么以及为什么
|
||||
|
||||
## 当前状态
|
||||
我们现在在哪里
|
||||
|
||||
## 实施阶段
|
||||
|
||||
### 阶段 1：基础设施（2 小时）
|
||||
- 任务 1.1：设置数据库模式
|
||||
- 验收：模式编译，关系正确
|
||||
- 任务 1.2：创建服务结构
|
||||
- 验收：所有目录已创建
|
||||
|
||||
### 阶段 2：核心功能（3 小时）
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. [task-name]-context.md
|
||||
|
||||
**用途：** 继续工作的关键信息
|
||||
|
||||
**包含：**
|
||||
- SESSION PROGRESS 部分（经常更新！）
|
||||
- 已完成与进行中的内容
|
||||
- 关键文件及其用途
|
||||
- 做出的重要决策
|
||||
- 发现的技术约束
|
||||
- 相关文件的链接
|
||||
- 快速恢复说明
|
||||
|
||||
**何时创建：** 任务开始时
|
||||
|
||||
**何时更新：** **经常** - 在重大决策、完成或发现之后
|
||||
|
||||
**示例：**
|
||||
```markdown
|
||||
# 功能名称 - 上下文
|
||||
|
||||
## SESSION PROGRESS (2025-10-29)
|
||||
|
||||
### ✅ 已完成
|
||||
- 数据库模式已创建（User、Post、Comment 模型）
|
||||
- PostController 已实施，使用 BaseController 模式
|
||||
- Sentry 集成正常工作
|
||||
|
||||
### 🟡 进行中
|
||||
- 创建具有业务逻辑的 PostService
|
||||
- 文件：src/services/postService.ts
|
||||
|
||||
### ⚠️ 阻碍
|
||||
- 需要决定缓存策略
|
||||
|
||||
## 关键文件
|
||||
|
||||
**src/controllers/PostController.ts**
|
||||
- 扩展 BaseController
|
||||
- 处理帖子的 HTTP 请求
|
||||
- 委托给 PostService
|
||||
|
||||
**src/services/postService.ts**（进行中）
|
||||
- 帖子操作的业务逻辑
|
||||
- 接下来：添加缓存
|
||||
|
||||
## 快速恢复
|
||||
要继续：
|
||||
1. 阅读此文件
|
||||
2. 继续实施 PostService.createPost()
|
||||
3. 查看任务文件了解剩余工作
|
||||
```
|
||||
|
||||
**关键：** 每次完成重要工作后更新 SESSION PROGRESS 部分！
|
||||
|
||||
---
|
||||
|
||||
### 3. [task-name]-tasks.md
|
||||
|
||||
**用途：** 跟踪进度的清单
|
||||
|
||||
**包含：**
|
||||
- 按逻辑部分分解的阶段
|
||||
- 复选框格式的任务
|
||||
- 状态指示符（✅/🟡/⏳）
|
||||
- 验收标准
|
||||
- 快速恢复部分
|
||||
|
||||
**何时创建：** 任务开始时
|
||||
|
||||
**何时更新：** 完成每个任务或发现新任务后
|
||||
|
||||
**示例：**
|
||||
```markdown
|
||||
# 功能名称 - 任务清单
|
||||
|
||||
## 阶段 1：设置 ✅ 完成
|
||||
- [x] 创建数据库模式
|
||||
- [x] 设置控制器
|
||||
- [x] 配置 Sentry
|
||||
|
||||
## 阶段 2：实施 🟡 进行中
|
||||
- [x] 创建 PostController
|
||||
- [ ] 创建 PostService（进行中）
|
||||
- [ ] 创建 PostRepository
|
||||
- [ ] 使用 Zod 添加验证
|
||||
|
||||
## 阶段 3：测试 ⏳ 未开始
|
||||
- [ ] 服务的单元测试
|
||||
- [ ] 集成测试
|
||||
- [ ] 手动 API 测试
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 何时使用开发文档
|
||||
|
||||
**用于：**
|
||||
- ✅ 复杂的多日任务
|
||||
- ✅ 有很多移动部分的功能
|
||||
- ✅ 可能跨越多个会话的任务
|
||||
- ✅ 需要仔细规划的工作
|
||||
- ✅ 重构大型系统
|
||||
|
||||
**跳过：**
|
||||
- ❌ 简单错误修复
|
||||
- ❌ 单文件更改
|
||||
- ❌ 快速更新
|
||||
- ❌ 琐碎修改
|
||||
|
||||
**经验法则：** 如果需要超过 2 小时或跨越多个会话，使用开发文档。
|
||||
|
||||
---
|
||||
|
||||
## 开发文档工作流程
|
||||
|
||||
### 开始新任务
|
||||
|
||||
1. **使用 /dev-docs 斜杠命令：**
|
||||
```
|
||||
/dev-docs 重构认证系统
|
||||
```
|
||||
|
||||
2. **Claude 创建三个文件：**
|
||||
- 分析需求
|
||||
- 检查代码库
|
||||
- 创建综合计划
|
||||
- 生成上下文和任务文件
|
||||
|
||||
3. **审查和调整：**
|
||||
- 检查计划是否合理
|
||||
- 添加任何缺失的考虑
|
||||
- 调整时间线估算
|
||||
|
||||
### 实施期间
|
||||
|
||||
1. **参考计划** 了解整体策略
|
||||
2. **频繁更新 context.md：**
|
||||
- 标记已完成的工作
|
||||
- 记录做出的决策
|
||||
- 添加阻碍
|
||||
3. **在 tasks.md 中勾选任务** 完成时
|
||||
|
||||
### 上下文重置后
|
||||
|
||||
1. **Claude 读取所有三个文件**
|
||||
2. **在几秒内理解完整状态**
|
||||
3. **从上次离开的确切位置继续**
|
||||
|
||||
无需解释您在做什么 - 一切都已记录！
|
||||
|
||||
---
|
||||
|
||||
## 与斜杠命令集成
|
||||
|
||||
### /dev-docs
|
||||
**创建：** 任务的新开发文档
|
||||
|
||||
**用法：**
|
||||
```
|
||||
/dev-docs 实施实时通知
|
||||
```
|
||||
|
||||
**生成：**
|
||||
- `dev/active/implement-real-time-notifications/`
|
||||
- implement-real-time-notifications-plan.md
|
||||
- implement-real-time-notifications-context.md
|
||||
- implement-real-time-notifications-tasks.md
|
||||
|
||||
### /dev-docs-update
|
||||
**更新：** 上下文重置前的现有开发文档
|
||||
|
||||
**用法：**
|
||||
```
|
||||
/dev-docs-update
|
||||
```
|
||||
|
||||
**更新：**
|
||||
- 标记已完成的任务
|
||||
- 添加发现的新任务
|
||||
- 使用会话进度更新上下文
|
||||
- 捕获当前状态
|
||||
|
||||
**使用时机：** 接近上下文限制或会话结束时
|
||||
|
||||
---
|
||||
|
||||
## 文件组织
|
||||
|
||||
```
|
||||
dev/
|
||||
├── README.md # 本文件
|
||||
├── active/ # 当前工作
|
||||
│ ├── task-1/
|
||||
│ │ ├── task-1-plan.md
|
||||
│ │ ├── task-1-context.md
|
||||
│ │ └── task-1-tasks.md
|
||||
│ └── task-2/
|
||||
│ └── ...
|
||||
└── archive/ # 已完成的工作（可选）
|
||||
└── old-task/
|
||||
└── ...
|
||||
```
|
||||
|
||||
**active/**：正在进行的工作
|
||||
**archive/**：已完成的任务（供参考）
|
||||
|
||||
---
|
||||
|
||||
## 示例：实际使用
|
||||
|
||||
查看此仓库中的 **dev/active/public-infrastructure-repo/** 了解真实示例：
|
||||
- **plan.md** - 创建此展示库的 700+ 行战略计划
|
||||
- **context.md** - 跟踪已完成内容、做出决策、下一步
|
||||
- **tasks.md** - 所有阶段和任务的清单
|
||||
|
||||
这是用于构建此展示库的实际开发文档！
|
||||
|
||||
---
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 频繁更新上下文
|
||||
|
||||
**不好：** 仅在会话结束时更新
|
||||
**好：** 在每个重要里程碑后更新
|
||||
|
||||
**SESSION PROGRESS 部分应始终反映现实：**
|
||||
```markdown
|
||||
## SESSION PROGRESS (YYYY-MM-DD)
|
||||
|
||||
### ✅ 已完成（列出完成的所有工作）
|
||||
### 🟡 进行中（您现在正在处理的工作）
|
||||
### ⚠️ 阻碍（阻止进度的工作）
|
||||
```
|
||||
|
||||
### 使任务可执行
|
||||
|
||||
**不好：** "修复认证"
|
||||
**好：** "在 AuthMiddleware.ts 中实施 JWT 令牌验证（验收：令牌验证，错误发送到 Sentry）"
|
||||
|
||||
**包括：**
|
||||
- 特定文件名
|
||||
- 清晰的验收标准
|
||||
- 对其他任务的依赖
|
||||
|
||||
### 保持计划最新
|
||||
|
||||
如果范围变更：
|
||||
- 更新计划
|
||||
- 添加新阶段
|
||||
- 调整时间线估算
|
||||
- 记录范围变更原因
|
||||
|
||||
---
|
||||
|
||||
## 对于 Claude Code
|
||||
|
||||
**当用户要求创建开发文档时：**
|
||||
|
||||
1. **如果可用，使用 /dev-docs 斜杠命令**
|
||||
2. **或手动创建：**
|
||||
- 询问任务范围
|
||||
- 分析相关代码库文件
|
||||
- 创建综合计划
|
||||
- 生成上下文和任务
|
||||
|
||||
3. **使用以下结构化计划：**
|
||||
- 清晰的阶段
|
||||
- 可执行的任务
|
||||
- 验收标准
|
||||
- 风险评估
|
||||
|
||||
4. **使上下文文件可恢复：**
|
||||
- 顶部的 SESSION PROGRESS
|
||||
- 快速恢复说明
|
||||
- 带说明的关键文件列表
|
||||
|
||||
**从开发文档恢复时：**
|
||||
|
||||
1. **阅读所有三个文件**（计划、上下文、任务）
|
||||
2. **从 context.md 开始** - 有当前状态
|
||||
3. **检查 tasks.md** - 了解已完成和待处理
|
||||
4. **参考 plan.md** - 了解整体策略
|
||||
|
||||
**频繁更新：**
|
||||
- 完成任务后立即标记
|
||||
- 重要工作后更新 SESSION PROGRESS
|
||||
- 发现新任务时添加
|
||||
|
||||
---
|
||||
|
||||
## 手动创建开发文档
|
||||
|
||||
如果您没有 /dev-docs 命令：
|
||||
|
||||
**1. 创建目录：**
|
||||
```bash
|
||||
mkdir -p dev/active/your-task-name
|
||||
```
|
||||
|
||||
**2. 创建 plan.md：**
|
||||
- 执行摘要
|
||||
- 实施阶段
|
||||
- 详细任务
|
||||
- 时间线估算
|
||||
|
||||
**3. 创建 context.md：**
|
||||
- SESSION PROGRESS 部分
|
||||
- 关键文件
|
||||
- 重要决策
|
||||
- 快速恢复说明
|
||||
|
||||
**4. 创建 tasks.md：**
|
||||
- 带复选框的阶段
|
||||
- [ ] 任务格式
|
||||
- 验收标准
|
||||
|
||||
---
|
||||
|
||||
## 好处
|
||||
|
||||
### 使用开发文档前
|
||||
- 上下文重置 = 重新开始
|
||||
- 忘记决策原因
|
||||
- 失去进度跟踪
|
||||
- 重复工作
|
||||
|
||||
### 使用开发文档后
|
||||
- 上下文重置 = 读取 3 个文件，立即恢复
|
||||
- 决策已记录
|
||||
- 进度已跟踪
|
||||
- 无重复工作
|
||||
|
||||
**节省的时间：** 每次上下文重置数小时
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
1. **在下一次复杂任务中尝试此模式**
|
||||
2. **使用 /dev-docs** 斜杠命令（如果可用）
|
||||
3. **频繁更新** - 特别是 context.md
|
||||
4. **查看实际操作** - 浏览 dev/active/public-infrastructure-repo/
|
||||
|
||||
**有疑问？** 查看 [CLAUDE_INTEGRATION_GUIDE.md](../CLAUDE_INTEGRATION_GUIDE.md)
|
||||
Loading…
Reference in New Issue