Claude Code Infrastructure Showcase 上手指南：用 Hooks 让 Skills “自动激活”，并用 Agents 固化复杂协作

这篇文章面向“第一次看到这个仓库的人”。我会用尽量直白的方式解释：它是什么、解决什么问题、你应该复制哪些文件、以及 15–30 分钟内把它接入到自己项目的最小路径。

---

0. 仓库地址与定位

仓库地址（建议先 Star，后面查结构很方便）：

https://github.com/diet103/claude-code-infrastructure-showcase

这个仓库不是一个可直接运行的应用，而是一个“可复制的参考库（reference library）”：把作者在真实项目里打磨出来的 Claude Code 基础设施（hooks、skills、agents、dev docs 体系）抽出来，供你拷贝到自己的工程里使用。

作者强调它解决的核心痛点之一是：Skills 不会在你需要时自动触发，你得靠记忆去手动调用；而这套方案通过 Hook + 规则把“该用什么 skill”变成自动提示/自动推荐。

---

1. 这个仓库到底解决什么？

README 里把价值讲得很清楚：它提供了生产实践验证过的一整套“Claude Code 基建”，包括：

• 通过 hooks 自动激活 skills

• 模块化 skill 结构（500 行规则 + 渐进式加载）

• 专用 agents 处理复杂任务（架构评审、重构、文档、排错等）

• Dev docs 体系：在上下文重置后依然能保存项目知识 

最直观的结果对比也在 README 里写了：从“技能不自动触发、上下文丢失、每次都要手动 invoke”变成“技能会根据上下文自我推荐、hooks 触发、dev docs 保持知识连续”。

---

2. 核心概念：Hooks + skill-rules.json = 自动激活

仓库给出的“自动激活”机制是：

1. 在每次用户提交提示词时触发一个 UserPromptSubmit hook

2. Hook 会分析你的提示词 + 文件上下文

3. 再根据 skill-rules.json 的配置去匹配触发条件

4. 命中后自动建议/引导使用相关 skill（并且 skills 只在需要时加载）

你可以把它理解成：给 Claude Code 加了一层“路由器/分发器”，把你的意图分发到最合适的 skill 或 agent。

---

3. 仓库结构速览（看懂后复制就不慌）

README 给了清晰目录结构（下面是“你真正会用到的部分”）

• .claude/skills/：一组可复用技能（并配套资源文件夹），以及 skill-rules.json（触发规则）

• .claude/hooks/：多种 hooks，其中 两个是“必需（ESSENTIAL）”

  • skill-activation-prompt.*（必需）

  • post-tool-use-tracker.sh（必需）

• .claude/agents/：专用 agents（10 个），用于架构评审、重构规划、排错等复杂任务

• .claude/commands/：slash commands（例如 dev-docs）

• dev/active/：dev docs pattern 的示例落地方式（帮助你把项目知识“写得可持续”）

---

4. 最小集成路径（15–30 分钟完成）

README 给出的“最短可用路径”非常明确：

先复制两个 essential hooks，再加一个 skill，然后就能看到自动激活的效果。

Step 1：把仓库拉下来（或直接下载）

git clone https://github.com/diet103/claude-code-infrastructure-showcase
cd claude-code-infrastructure-showcase

Step 2：在你的项目根目录创建 .claude/

你自己的项目结构大概是这样：

your-project/
  ├── src/
  ├── package.json
  └── .claude/           # 你要放这里

Step 3：复制“两个必需 hooks”

从 showcase 里复制以下文件到你项目的 .claude/hooks/：

• .claude/hooks/skill-activation-prompt.*（必需）

• .claude/hooks/post-tool-use-tracker.sh（必需）

注：文件名里有 .*，表示可能存在同名的不同实现/扩展名（按仓库实际文件为准）。

Step 4：复制触发规则 skill-rules.json

把 showcase 里的：

• .claude/skills/skill-rules.json

复制到你项目同路径下。这个文件决定“什么关键词/上下文触发哪个 skill”。README 明确指出自动激活依赖它。

Step 5：只复制一个你最需要的 Skill（先跑通闭环）

从 skills 里挑一个最贴近你项目的（示例）：

• 后端：backend-dev-guidelines

• 前端：frontend-dev-guidelines

• 写 skill 的“元技能”：skill-developer

• API 路由测试：route-tester

• Sentry/错误追踪：error-tracking

先复制 一个目录 到你项目的 .claude/skills/，跑通闭环后再逐步加。

---

5. 怎么验证“自动激活真的生效”？

你可以用一个非常简单的验证方式：

1. 在 Claude Code 里打开你的项目

2. 输入一个明显匹配你 skill 的需求，比如：

   • “我要给某个 API 增加鉴权测试”

   • “我需要做一次架构 review/重构规划”

   • “帮我把这段错误栈定位到可能的原因并给出修复方案”

3. 如果 hooks 工作正常，它应该会根据你的提示词/上下文，提示你使用某个 skill 或 agent（核心价值点）。

---

6. 把 Skill 做成“可持续维护”的关键：500 行规则 + 渐进式加载

仓库强调一个非常工程化的实践：大 skill 会撞上下文限制，所以建议采用：

• 主 skill 文件控制在 <500 行（高层指南）

• 细分主题拆到 resources/ 下多个小文件（每个也 <500 行）

• Claude 先加载主文件，只有必要时才加载资源文件（progressive disclosure）

你可以照着这个结构设计自己的技能库：

your-skill/
  SKILL.md
  resources/
    topic-1.md
    topic-2.md

---

7. Agents 什么时候用？怎么用？

当任务从“写一段代码”升级为“需要流程化思考/多步骤输出”时，用 agents 会更稳：例如架构评审、重构计划、错误修复策略、文档生成等。仓库提供了 10 个生产实践 agent 作为模板。

实战建议：

• 先挑 1–2 个 agent（比如“架构评审”“重构规划”）

• 用同样思路把它们复制到你项目 .claude/agents/

• 以后遇到同类任务就复用 agent，减少“每次从零描述要求”的成本

---

8. 推荐的接入策略（别一上来全抄）

这类“基建仓库”最怕的就是：你全抄进去，然后不知道哪个起作用、哪个副作用更大。

更稳的策略是分 3 次迭代：

1. 只接入两个 essential hooks + 1 个 skill + skill-rules.json（先看到收益）

2. 再逐步增加 skills（每次只加 1–2 个）

3. 最后引入 agents / dev docs / slash commands（让团队工作流长期稳定）

---

9. 你可能会遇到的两个常见问题

Q1：为什么“我复制了文件，但看不到效果”？

优先检查三点：

• .claude/hooks/ 下是否真的包含 skill-activation 相关 hook 文件（名称是否一致）

• skill-rules.json 是否在你项目 .claude/skills/ 下（路径是否对）

• 你是否只复制了 skills，但没有复制 hooks（这会导致“技能永远静静躺着”）

Q2：我应该复制多少 skills？

建议从 1 个开始，最多 2 个。README 也暗示“先复制关键部分，再按需扩展”。

---

10. 小结：这仓库最值得抄的是什么？

如果你只想拿到 80% 的收益，请优先做三件事：

1. 把 两个 essential hooks 接入到项目里

2. 把 skill-rules.json 接入并根据你的项目关键词做最小配置

3. 复制 1 个最贴近你业务的 skill，跑通“自动激活闭环”