11 KiB

Raw Permalink Blame History

Claude Code 基础设施展示库

精心策划的生产就绪 Claude Code 基础设施参考库。

源于管理复杂 TypeScript 微服务项目的 6 个月实际使用经验，本展示库提供了解决"技能无法自动激活"问题的模式和系统，并将 Claude Code 扩展到企业级开发。

这不是一个可运行的应用程序 - 它是一个参考库。将您需要的内容复制到您自己的项目中即可。

内容概览

生产就绪的基础设施包含：

✅ 通过钩子实现技能自动激活
✅ 模块化技能模式（500 行规则与渐进式披露）
✅ 专门处理复杂任务的智能体
✅ 能在上下文重置后存活的开发文档系统
✅ 使用通用博客域的综合示例

构建所需时间投入： 6 个月的迭代开发 集成到您项目的时间： 15-30 分钟

快速开始 - 选择您的路径

🤖 使用 Claude Code 进行集成？

Claude： 阅读 CLAUDE_INTEGRATION_GUIDE.md 获取针对 AI 辅助设置的详细集成说明。

🎯 我想要技能自动激活

突破性功能： 真正能在您需要时激活的技能。

您需要的：

技能激活钩子（2 个文件）
与您工作相关的 1-2 个技能
15 分钟时间

👉 设置指南：.claude/hooks/README.md

📚 我想要添加一个技能

浏览技能目录并复制您需要的内容。

可用技能：

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

🤖 我想要专门的智能体

10 个生产就绪的智能体，适用于复杂任务：

代码架构审查
重构辅助
文档生成
错误调试
等等...

👉 智能体指南：.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	426	创建和管理技能	元开发
backend-dev-guidelines	304	Express/Prisma/Sentry 模式	后端 API
frontend-dev-guidelines	398	React/MUI v7/TypeScript	React 前端
route-tester	389	测试已认证路由	API 测试
error-tracking	~250	Sentry 集成	错误监控

所有技能都遵循模块化模式 - 主文件 + 渐进式披露的资源文件。

👉 如何集成技能 →

🪝 钩子 (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	⚠️ 可选	⚠️ 中等

从两个必需钩子开始 - 它们实现技能自动激活，开箱即用。

👉 钩子设置指南 →

🤖 智能体 (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 错误

👉 智能体工作原理 →

💬 斜杠命令 (3)

命令	用途
/dev-docs	创建结构化开发文档
/dev-docs-update	在上下文重置前更新文档
/route-research-for-testing	研究测试路由模式

核心概念

钩子 + skill-rules.json = 自动激活

该系统：

skill-activation-prompt 钩子 在每个用户提示时运行
检查 skill-rules.json 中的触发模式
自动建议相关技能
仅在需要时加载技能

这解决了 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 服务器在您的设置中可能不存在

使用方法：

仅提取 UserPromptSubmit 和 PostToolUse 钩子
自定义或跳过 Stop 钩子
为您的设置更新 MCP 服务器列表

博客域示例

技能使用通用博客示例（Post/Comment/User）：

这些是教学示例，不是要求
模式适用于任何域（电商、SaaS 等）
将模式适配到您的业务逻辑

钩子目录结构

一些钩子期望特定结构：

tsc-check.sh 期望服务目录
基于您的项目布局进行自定义

集成工作流

推荐方法：

阶段 1：技能激活（15 分钟）

复制 skill-activation-prompt 钩子
复制 post-tool-use-tracker 钩子
更新 settings.json
安装钩子依赖

阶段 2：添加第一个技能（10 分钟）

选择 1 个相关技能
复制技能目录
创建/更新 skill-rules.json
自定义路径模式

阶段 3：测试和迭代（5 分钟）

编辑文件 - 技能应该激活
提问 - 应该建议技能
根据需要添加更多技能

阶段 4：可选增强

添加您觉得有用的智能体
添加斜杠命令
自定义 Stop 钩子（高级）

获取帮助

对于用户

集成问题？

查看 CLAUDE_INTEGRATION_GUIDE.md
向 Claude 询问："为什么 [技能] 没有激活？"
提出包含您项目结构的问题

对于 Claude Code

帮助用户集成时：

首先阅读 CLAUDE_INTEGRATION_GUIDE.md
询问他们的项目结构
自定义，而不是盲目复制
集成后验证

这解决了什么问题

使用此基础设施前

❌ 技能不会自动激活 ❌ 必须记住使用哪个技能 ❌ 大型技能触及上下文限制 ❌ 上下文重置丢失项目知识 ❌ 开发中缺乏一致性 ❌ 每次都需要手动调用智能体

使用此基础设施后

✅ 技能根据上下文自动建议 ✅ 钩子在适当时机触发技能 ✅ 模块化技能保持在上下文限制内 ✅ Dev Docs 在重置后保留知识 ✅ 通过护栏实现一致的模式 ✅ 智能体简化复杂任务

社区

觉得有用？

⭐ 为这个仓库点星
🐛 报告问题或建议改进
💬 分享您自己的技能/钩子/智能体
📝 从您的域贡献示例

背景： 这套基础设施在我发布到 Reddit 的帖子"Claude Code is a Beast – Tips from 6 Months of Hardcore Use"中有详细介绍。在收到数百个请求后，创建了这个展示库来帮助社区实施这些模式。

许可证

MIT 许可证 - 在您的项目中自由使用，无论是商业项目还是个人项目。

快速链接

📖 Claude 集成指南 - 用于 AI 辅助设置
🎨 技能文档
🪝 钩子设置
🤖 智能体指南
📝 Dev Docs 模式

开始使用： 复制两个必需钩子，添加一个技能，见证自动激活魔法发生。

11 KiB Raw Permalink Blame History Unescape Escape