admin123
/
translation
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
translation/translated/documents/claude-code-infrastructure-.../README_zh.md

359 lines
11 KiB
Markdown
Raw Normal View History

docs: 添加中文翻译文档 添加三个中文翻译文档： - README_zh.md：Claude Code基础设施展示库概述 - CLAUDE_INTEGRATION_GUIDE_zh.md：Claude集成指南 - dev/README_zh.md：Dev Docs模式文档
2025-11-12 10:22:38 +08:00
# 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)
**开始使用：** 复制两个必需钩子，添加一个技能，见证自动激活魔法发生。