# claude-code-infrastructure-showcase **Repository Path**: vcdplus/claudeskill ## Basic Information - **Project Name**: claude-code-infrastructure-showcase - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-11-28 - **Last Updated**: 2025-11-28 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Claude Code 基础设施展示 **一个经过生产验证的 Claude Code 基础设施精选参考库。** 源于6个月的实际使用经验，管理复杂的 TypeScript 微服务项目，这个展示库提供了解决"技能不会自动激活"问题的模式和系统，并为企业开发扩展了 Claude Code。 > **这不是一个可运行的应用程序** - 它是一个参考库。将你需要的部分复制到你自己的项目中。 --- ## 内容概览 **经过生产验证的基础设施包括：** - ✅ **自动激活技能** 通过 hooks 实现 - ✅ **模块化技能模式** (500行规则，渐进式披露) - ✅ **专业代理** 用于复杂任务 - ✅ **开发文档系统** 能够在上下文重置后保留 - ✅ **全面的示例** 使用通用博客领域 **构建时间投入：** 6个月的迭代 **集成到你的项目时间：** 15-30分钟 --- ## 快速开始 - 选择你的路径 ### 🤖 使用 Claude Code 进行集成？ **Claude：** 阅读 [`CLAUDE_INTEGRATION_GUIDE.md`](CLAUDE_INTEGRATION_GUIDE.md) 获取针对 AI 辅助设置的分步集成说明。 ### 🎯 我想要技能自动激活 **突破性功能：** 真正在你需要时激活的技能。 **你需要的：** 1. 技能激活 hooks (2个文件) 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 hook 可以： - 分析你的提示 - 检查文件上下文 - 自动建议相关技能 - 通过 `skill-rules.json` 配置工作 **结果：** 技能在你需要时激活，而不是在你记得时激活。 ### 经过生产验证的模式 这些不是理论示例 - 它们是从以下内容中提取的： - ✅ 6个生产中的微服务 - ✅ 50,000+ 行 TypeScript 代码 - ✅ 具有复杂数据网格的 React 前端 - ✅ 复杂的工作流引擎 - ✅ 6个月的日常 Claude Code 使用 这些模式有效是因为它们解决了真实的问题。 ### 模块化技能 (500行规则) 大型技能会遇到上下文限制。解决方案： ``` skill-name/ 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个自动化 hooks │ ├── 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/ # 开发文档模式示例 └── 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)** ### 🪝 Hooks (6个) | Hook | 类型 | 必需？ | 自定义 | |------|------|-----------|---------------| | skill-activation-prompt | UserPromptSubmit | ✅ 是 | ✅ 无需自定义 | | post-tool-use-tracker | PostToolUse | ✅ 是 | ✅ 无需自定义 | | tsc-check | Stop | ⚠️ 可选 | ⚠️ 重度 - 仅单体仓库 | | trigger-build-resolver | Stop | ⚠️ 可选 | ⚠️ 重度 - 仅单体仓库 | | error-handling-reminder | Stop | ⚠️ 可选 | ⚠️ 中度 | | stop-build-check-enhanced | Stop | ⚠️ 可选 | ⚠️ 中度 | **从两个必需的 hooks 开始** - 它们启用技能自动激活并且开箱即用。 **👉 [Hook 设置指南 →](.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 | 研究路由模式用于测试 | --- ## 关键概念 ### Hooks + skill-rules.json = 自动激活 **系统：** 1. **skill-activation-prompt hook** 在每个用户提示上运行 2. 检查 **skill-rules.json** 的触发模式 3. 自动建议相关技能 4. 只在需要时加载技能 **这解决了 Claude Code 技能的 #1 问题：** 它们不会自己激活。 ### 渐进式披露 (500行规则) **问题：** 大型技能遇到上下文限制 **解决方案：** 模块化结构 - 主 SKILL.md <500 行 (概述 + 导航) - 资源文件 <500 行每个 (深度探讨) - Claude 根据需要逐步加载 **示例：** backend-dev-guidelines 有12个资源文件，涵盖路由、控制器、服务、仓库、测试等。 ### 开发文档模式 **问题：** 上下文重置会丢失项目上下文 **解决方案：** 三文件结构 - `[task]-plan.md` - 战略计划 - `[task]-context.md` - 关键决策和文件 - `[task]-tasks.md` - 检查清单格式 **与以下配合使用：** `/dev-docs` 斜杠命令自动生成这些 --- ## ⚠️ 重要：什么不会直接生效 ### settings.json 包含的 `settings.json` 仅是**示例**： - Stop hooks 引用特定的单体仓库结构 - 服务名称 (blog-api 等) 是示例 - MCP 服务器在你的设置中可能不存在 **使用方法：** 1. 仅提取 UserPromptSubmit 和 PostToolUse hooks 2. 自定义或跳过 Stop hooks 3. 为你的设置更新 MCP 服务器列表 ### 博客领域示例 技能使用通用博客示例 (Post/Comment/User)： - 这些是**教学示例**，不是要求 - 模式适用于任何领域 (电子商务、SaaS 等) - 根据你的业务逻辑调整模式 ### Hook 目录结构 一些 hooks 期望特定结构： - `tsc-check.sh` 期望服务目录 - 根据你的项目布局进行自定义 --- ## 集成工作流程 **推荐方法：** ### 第1阶段：技能激活 (15分钟) 1. 复制 skill-activation-prompt hook 2. 复制 post-tool-use-tracker hook 3. 更新 settings.json 4. 安装 hook 依赖 ### 第2阶段：添加第一个技能 (10分钟) 1. 选择一个相关技能 2. 复制技能目录 3. 创建/更新 skill-rules.json 4. 自定义路径模式 ### 第3阶段：测试和迭代 (5分钟) 1. 编辑文件 - 技能应该激活 2. 提问 - 应该建议技能 3. 根据需要添加更多技能 ### 第4阶段：可选增强 - 添加你认为有用的代理 - 添加斜杠命令 - 自定义 Stop hooks (高级) --- ## 获取帮助 ### 对于用户 **集成有问题？** 1. 检查 [CLAUDE_INTEGRATION_GUIDE.md](CLAUDE_INTEGRATION_GUIDE.md) 2. 询问 Claude："为什么 [技能] 没有激活？" 3. 根据你的项目结构打开问题 ### 对于 Claude Code 帮助用户集成时： 1. **首先阅读 CLAUDE_INTEGRATION_GUIDE.md** 2. 询问他们的项目结构 3. 进行自定义，不要盲目复制 4. 集成后进行验证 --- ## 这解决了什么 ### 在此基础设施之前 ❌ 技能不会自动激活 ❌ 必须记得使用哪个技能 ❌ 大型技能遇到上下文限制 ❌ 上下文重置会丢失项目知识 ❌ 开发中没有一致性 ❌ 每次都需要手动调用代理 ### 在此基础设施之后 ✅ 技能根据上下文自我建议 ✅ Hooks 在正确时间触发技能 ✅ 模块化技能保持在上下文限制内 ✅ 开发文档在重置后保留知识 ✅ 通过护栏实现一致模式 ✅ 代理简化复杂任务 --- ## 社区 **发现这很有用？** - ⭐ 给这个仓库加星 - 🐛 报告问题或建议改进 - 💬 分享你自己的技能/hooks/代理 - 📝 贡献你领域的示例 **背景：** 这个基础设施在我发布的 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) - 🪝 [Hooks 设置](.claude/hooks/README.md) - 🤖 [代理指南](.claude/agents/README.md) - 📝 [开发文档模式](dev/README.md) **从这里开始：** 复制两个必需的 hooks，添加一个技能，看看自动激活的魔力是如何发生的。