diet103/Claude Code 基础设施展示库：技能自动激活、钩子与智能体集成方案

发生了什么

Claude Code Infrastructure Showcase A curated reference library of production-tested Claude Code infrastructure. Born from 6 months of real-world use managing a complex TypeScript microservices project, this showcase provides the patterns and systems that solved the "skills don't activate automatically" problem and scaled Claude Code for enterprise development. This is NOT a working application - it's a reference library. Copy what you need into your own projects. New to Claude Code infrastructure? Three terms cover 90% of this README: Skill - a markdown guide (patterns, conventions, examples) that Claude loads when relevant Hook - a script Claude Code runs automatically at key moments (every prompt, before/after edits) skill-rules.json - the config that tells hooks which prompts/files should trigger which skills Full explanations in Key Concepts . What's Inside Production-tested infrastructure for: ✅ Auto-activating skills via hooks ✅ Modular skill pattern (500-line rule with progressive disclosure) ✅ Specialized agents for complex tasks ✅ Dev docs system that survives context resets ✅ Comprehensive examples using generic blog domain Time investment to build: 6 months of iteration Time to integrate into your project: 15-30 minutes Quick Start Requirements Node.js 18+ (20+ recommended) and npm macOS, Linux, or WSL2 - the hooks are bash scripts and won't run in plain cmd/PowerShell (Windows users: use WSL2) jq - only needed if you enable the optional Stop hooks Note: the first npx tsx run may ask to install tsx - say yes. Option A: Setup Wizard (Recommended) The wizard copies everything, installs dependencies, and configures your mode: # 1. Clone this repo git clone https://github.com/diet103/claude-code-infrastructure-showcase.git # 2. Run the setup wizard, pointing to YOUR project cd claude-code-infrastructure-showcase npx tsx setup.ts ~ /my-project The wizard will: Copy .claude/ (hooks, skills, agents, commands) into your project Detect your tech stack (React, Express, Prisma, etc.) Ask: Classic (regex-only) or AI-Enhanced mode? If AI: which provider? Validates API key availability Install hook dependencies and make scripts executable Verify its own work - 8 health checks before it declares success Scripting it, or letting Claude Code run it? Add --yes : npx tsx setup.ts ~/my-project --yes (see --help for all flags) Option B: Manual (3 Commands) # 1. Clone this repo git clone https://github.com/diet103/claude-code-infrastructure-showcase.git # 2. Copy .claude/ into YOUR project cp -r claude-code-infrastructure-showcase/.claude ~ /my-project/.claude # 3. Install hook dependencies cd ~ /my-project/.claude/hooks && npm install && chmod +x * .sh Option C: Let Claude Code Do It (Easiest) Don't want to touch the terminal? Open Claude Code in your project and paste this: Clone https://github.com/diet103/claude-code-infrastructure-showcase to a temp directory and read its CLAUDE_INTEGRATION_GUIDE.md. Then install the infrastructure into this project by running the setup wizard non-interactively (npx tsx setup.ts <this project's absolute path> --yes). When it finishes, show me the verification results and fix anything that failed. Claude clones the repo, runs the wizard (which verifies its own work), and reports back. Verify It Works (30 Seconds) Any time, from your project root: bash .claude/scripts/verify-setup.sh Eight checks - Node version, hook registration, executable bits, dependencies, config validity, even firing a test prompt through the real activation hook - each with an exact fix command if it fails. Or ask Claude to run /verify-setup and it fixes failures itself. Enable AI-Powered Classification (Optional) No API key needed by default. The standard mode uses regex/keyword matching - free, offline, zero API calls. AI classification is an optional upgrade that matches your intent instead of your keywords. To enable it (Gemini's free tier easily covers this use case): # 1. Get a free Gemini API key: https://aistudio.google.com/apikey # 2. Put it in the hooks .env file: cp .claude/hooks/.env.example .claude/hooks/.env # then open .claude/hooks/.env and uncomment: GEMINI_API_KEY=your-key-here # (add .env to your project's .gitignore so you never commit it) # 3. Enable AI mode - edit .claude/skills/skill-rules.json and change: # "skill_activation_mode": "disabled" → "skill_activation_mode": "fallback" Prefer environment variables? export GEMINI_API_KEY=your-key in ~/.bashrc works too - the hooks read both. ( fallback mode always degrades gracefully: no key, dead network, slow provider - you get regex matching, never a broken prompt.) Upgrading an Existing Install Re-running the wizard on a project that already has .claude/ deliberately copies no files - it only re-chmods hooks, updates skill-rules.json settings, and reinstalls dependencies. It will never clobber your customized skill-rules.json or skills. To pick up new files from a newer version of this repo: Copy specific pieces from a fresh clone (e.g. cp -r showcase/.claude/scripts ~/my-project/.claude/ ), or If your .claude/ is committed to git: delete it, re-run the wizard, then git diff to port your customizations back. Editor Setup (Optional) The repo includes a NeoVim configuration optimized for Claude Code's prompt editing mode ( Ctrl+G ): Relative line numbers for easy jumping ( 5j = down 5 lines) Word-boundary wrapping for long prompts System clipboard integration (yank = Cmd+C) Space+w to save and submit, Space+q to cancel The setup wizard can install this automatically, or manually: mkdir -p ~ /.config/nvim cp editor-config/init.lua ~ /.config/nvim/init.lua cp editor-config/vimrc ~ /.vimrc echo ' export EDITOR=nvim ' >> ~ /.bashrc && source ~ /.bashrc See editor-config/README.md for full keybinding reference. What You'll See After setup, when you type "create a React component" in Claude Code: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ⛔ MANDATORY SKILL ACTIVATION REQUIRED ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ You MUST activate these skills BEFORE any action: → frontend-dev-guidelines ⚠️ EDITS WILL BE BLOCKED until mandatory skills are activated. Your FIRST action must be: Skill tool calls. [via regex] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Skills auto-activate based on your prompts. No more forgetting to load them. Pick Your Path 🤖 Using Claude Code to Integrate? Claude: Read CLAUDE_INTEGRATION_GUIDE.md for step-by-step integration instructions tailored for AI-assisted setup. 📚 Browse the Skills Catalog Available skills ( full catalog ): backend-dev-guidelines - Node.js/Express/TypeScript patterns frontend-dev-guidelines - React/TypeScript/MUI v7 patterns skill-developer - Meta-skill for creating skills error-tracking - Sentry integration patterns 🤖 Specialized Agents 8 production-tested agents for complex tasks ( full list ): Code architecture review, refactoring, documentation, error debugging, and more What Makes This Different? The Auto-Activation Breakthrough Problem: Claude Code skills just sit there. You have to remember to use them. Solution: UserPromptSubmit hook that: Analyzes your prompts Checks file context Automatically suggests relevant skills Works via skill-rules.json configuration Result: Skills activate when you need them, not when you remember them. AI-Powered Classification (NEW in v2.0) Choose your activation mode: Mode How It Works Cost Offline disabled (default) Regex/keyword matching only Free Yes fallback AI first, regex on failure Low Graceful ai-only Pure AI classification Low No Supported AI providers: Provider Model API Key Free Tier Gemini gemini-3-flash-preview GEMINI_API_KEY Yes (generous) OpenAI gpt-4o-mini OPENAI_API_KEY No Anthropic claude-haiku-4-5 ANTHROPIC_API_KEY No Ollama llama3.2 (local) None needed Yes (local) Auto-detection tries providers in order: Gemini > OpenAI > Anthropic > Ollama. Override with SKILL_AI_PROVIDER=gemini . Conservativeness levels control suggestion aggressiveness: strict - Minimize false positives. Only suggest when clear intent. balanced (default) - Standard behavior. aggressive - Catch everything. Suggest liberally. Production-Tested Patterns These aren't theoretical examples - they're extracted from: ✅ 6 microservices in production ✅ 50,000+ lines of TypeScript ✅ React frontend with complex data grids ✅ Sophisticated workflow engine ✅ 6 months of daily Claude Code use The patterns work because they solved real problems. Modular Skills (500-Line Rule) Large skills hit context limits. The solution: skill-name/ SKILL.md # <500 lines, high-level guide resources/ topic-1.md # aim for <500 lines each topic-2.md topic-3.md Progressive disclosure: Claude loads main skill first, loads resources only when needed. Repository Structure .claude/ ├── skills/ # 4 production skills │ ├── backend-dev-guidelines/ (11 resource files) │ ├── frontend-dev-guidelines/ (10 resource files) │ ├── skill-developer/ (6 resource files) │ ├── error-tracking/ │ └── skill-rules.json # Skill activation configuration ├── hooks/ # 9 hooks for automation │ ├── skill-activation-prompt.* (ESSENTIAL) │ ├── skill-verification-guard.* (ESSENTIAL, v2.0) │ ├── skill-activation-tracker.* (ESSENTIAL, v2.0) │ ├── post-tool-use-tracker.sh (ESSENTIAL) │ ├── session-doc-updater.* (optional, installed by default) │ ├── error-handling-reminder.* (optional) │ ├── stop-build-check-enhanced.sh (optional) │ ├── tsc-check.sh (optional, needs customization) │ └── trigger-build-resolver.sh (optional) ├── agents/ # 8 specialized agents │ ├── code-architecture-reviewer.md │ ├── refactor-planner.md │ ├── frontend-error-fixer.md │ └── ... 5 more ├── commands/ # 4 slash commands │ ├── dev-docs.md │ ├── verify-setup.md │ └── ... └── scripts/ └── verify-setup.sh # One-command health check dev/ └── active/ # Dev docs pattern examples └── showcase-ai-upgrade/ Component Catalog 🎨 Skills (4) Skill Lines Purpose Best For skill-developer 426 Creating and managing skills Meta-development backend-dev-guidelines 304 Express/Prisma/Sentry patterns Backend APIs frontend-dev-guidelines 398 React/MUI v7/TypeScript React frontends error-tracking ~250 Sentry integration Error monitoring All skills follow the modular pattern - main file + resource files for progressive disclosure. 👉 How to integrate skills → 🪝 Hooks (9) Hook Type Essential? Customization skill-activation-prompt UserPromptSubmit ✅ YES ✅ None needed skill-verification-guard PreToolUse ✅ YES (v2.0) ✅ None needed skill-activation-tracker PostToolUse (Skill) ✅ YES (v2.0) ✅ None needed post-tool-use-tracker PostToolUse (Edit) ✅ YES ✅ None needed tsc-check Stop ⚠️ Optional ⚠️ Heavy - monorepo only trigger-build-resolver Stop ⚠️ Optional ⚠️ Heavy - monorepo only error-handling-reminder Stop ⚠️ Optional ⚠️ Moderate stop-build-check-enhanced Stop ⚠️ Optional ⚠️ Moderate session-doc-updater Stop ⚠️ Optional (installed by default) ✅ None - no-ops until session indexing is configured ( CONFIG.md ) Hook types: UserPromptSubmit fires on every prompt you send; PreToolUse fires before each Edit/Write; PostToolUse fires after; Stop fires when Claude finishes responding. New in v2.0: skill-verification-guard - PreToolUse hook that analyzes code being written and enforces mandatory skill activation (two-try blocking model) skill-activation-tracker - Clears skills from mandatory_pending after they're activated via the Skill tool Start with the essential hooks - they enable skill auto-activation and work out of the box. 👉 Hook setup guide → 🤖 Agents (8) Standalone - just copy and use! Agent Purpose code-architecture-reviewer Review code for architectural consistency code-refactor-master Plan and execute

为什么重要

Claude Code 相关变化会影响 AI 产品团队的技术选型和发布判断。

影响谁

Claude Code · Claude · GPT · Gemini

建议动作

Upgrade or review the changed version

地区可用性

No region-specific availability verified.

Generated from event evidence.

• src-skill-radar · summary
• src-skill-radar · reason