# 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) **开始使用：** 复制两个必需钩子，添加一个技能，见证自动激活魔法发生。