@choblue/claude-code-toolkit 1.1.2 → 1.1.4

package/.claude/.project-map-cache

@@ -0,0 +1 @@
+03a6f698d5246e33e211ef5f209fc9471c01cf50

package/.claude/CLAUDE.md

@@ -9,6 +9,12 @@ Claude는 작업 시작 전 반드시 이 규칙을 따라야 한다.
 
 Main Agent의 Context Window는 제한적이다. 반드시 서브에이전트에 위임하라.
 
+### PROJECT_MAP.md 활용
+- `.claude/PROJECT_MAP.md`가 있으면 explore 전에 반드시 먼저 Read하라
+- 단순 구조 확인은 explore 생략 가능
+- 세부 코드 탐색이 필요할 때만 explore 위임
+- 갱신: `.claude/scripts/generate-project-map.sh` 실행
+
 ### 위임 규칙
 - **탐색/검색 작업** → `explore` 에이전트 (haiku) 위임
 - **코드 구현** → `code-writer-fe` 또는 `code-writer-be` 에이전트 (opus) 위임
@@ -85,8 +91,14 @@ Main Agent의 Context Window는 제한적이다. 반드시 서브에이전트에
   - `backend.md` - NestJS 테스트 규칙
 - `.claude/skills/Git/SKILL.md` - Git 커밋/PR/브랜치 규칙
 
+### Scripts
+- `.claude/scripts/generate-project-map.sh` - PROJECT_MAP.md 자동 생성
+
 ### Hooks
 - `.claude/hooks/quality-gate.sh` - 품질 체크 프로토콜
+- `.claude/hooks/skill-detector.sh` - 프롬프트 기반 스킬 자동 추천
+- `.claude/hooks/skill-keywords.conf` - 스킬별 키워드 매핑 설정
+- `.claude/hooks/project-map-detector.sh` - 프로젝트 구조 변경 감지
 
 ---
 

package/.claude/PROJECT_MAP.md

@@ -0,0 +1,43 @@
+# PROJECT MAP
+
+> Auto-generated by `generate-project-map.sh`
+> 이 파일은 explore 에이전트의 사전 캐시로 사용된다. 직접 수정하지 말 것.
+
+## 프로젝트 정보
+
+- **이름**: @choblue/claude-code-toolkit
+- **브랜치**: main
+- **최근 커밋**: 03a6f69 DOCS: skill-detector hook 문서 반영 및 CHANGELOG 추가
+- **생성 시간**: 2026-02-25 15:12:39
+- **총 파일 수**: 41
+
+## 디렉토리 구조
+
+```
+.
+./.claude
+./.claude/agents
+./.claude/hooks
+./.claude/scripts
+./.claude/skills
+./.claude/skills/Coding
+./.claude/skills/Git
+./.claude/skills/NextJS
+./.claude/skills/React
+./.claude/skills/ReactHookForm
+./.claude/skills/TDD
+./.claude/skills/TailwindCSS
+./.claude/skills/TanStackQuery
+./.claude/skills/TypeORM
+./.claude/skills/TypeScript
+./.claude/skills/Zustand
+./bin
+./skills
+```
+
+## 주요 파일
+
+### 설정 파일
+
+- `package.json`
+

package/.claude/agents/explore.md

@@ -18,6 +18,13 @@ Main Agent의 Context를 오염시키지 않고, 필요한 정보만 정리하
 
 ---
 
+## 사전 체크
+
+1. `.claude/PROJECT_MAP.md` 존재 시 먼저 Read
+2. PROJECT_MAP.md에 없는 상세 정보만 Glob/Grep 사용
+
+---
+
 ## 탐색 방법
 
 ### 파일 찾기

package/.claude/hooks/project-map-detector.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# project-map-detector.sh - PROJECT_MAP.md 구조 변경 감지 hook
+# UserPromptSubmit hook으로 등록하여 매 프롬프트마다 실행된다.
+# 구조 변경 감지 시 PROJECT_MAP.md 갱신을 안내한다.
+
+# stdin으로 전달된 JSON을 읽어서 버린다 (hook 프로토콜 준수)
+read -r INPUT 2>/dev/null || true
+
+CLAUDE_DIR=".claude"
+MAP_FILE="$CLAUDE_DIR/PROJECT_MAP.md"
+CACHE_FILE="$CLAUDE_DIR/.project-map-cache"
+
+# PROJECT_MAP.md 없으면 생성 안내
+if [ ! -f "$MAP_FILE" ]; then
+  echo "[PROJECT_MAP] PROJECT_MAP.md가 없습니다. 다음 명령으로 생성하세요:"
+  echo "  .claude/scripts/generate-project-map.sh"
+  exit 0
+fi
+
+# Git repo 아니면 조용히 종료
+if ! git rev-parse --is-inside-work-tree &>/dev/null 2>&1; then
+  exit 0
+fi
+
+# 현재 HEAD 해시
+CURRENT_HEAD="$(git rev-parse HEAD 2>/dev/null)" || exit 0
+
+# 캐시 비교
+if [ -f "$CACHE_FILE" ]; then
+  CACHED_HEAD="$(cat "$CACHE_FILE" 2>/dev/null)"
+  if [ "$CURRENT_HEAD" = "$CACHED_HEAD" ]; then
+    # 캐시 히트 → 변경 없음
+    exit 0
+  fi
+fi
+
+# 캐시 미스 → git diff로 구조 변경 확인
+# 이전 캐시가 없으면 현재 HEAD만 캐시하고 종료 (첫 실행)
+if [ ! -f "$CACHE_FILE" ]; then
+  printf '%s' "$CURRENT_HEAD" > "$CACHE_FILE"
+  exit 0
+fi
+
+CACHED_HEAD="$(cat "$CACHE_FILE" 2>/dev/null)"
+
+# 구조 변경 패턴 필터링
+STRUCTURE_CHANGED=false
+
+# 파일 추가/삭제/이동 감지 (A, D, R)
+ADD_DEL="$(git diff --name-status "$CACHED_HEAD" "$CURRENT_HEAD" 2>/dev/null | grep -E '^[ADR]' | head -20)" || true
+
+if [ -n "$ADD_DEL" ]; then
+  STRUCTURE_CHANGED=true
+fi
+
+# 설정 파일 변경 감지
+CONFIG_PATTERN="package\.json$|tsconfig\.json$|\.eslintrc|next\.config|vite\.config|nest-cli\.json|docker-compose"
+CONFIG_CHANGED="$(git diff --name-only "$CACHED_HEAD" "$CURRENT_HEAD" 2>/dev/null | grep -E "$CONFIG_PATTERN" | head -5)" || true
+
+if [ -n "$CONFIG_CHANGED" ]; then
+  STRUCTURE_CHANGED=true
+fi
+
+# 캐시 업데이트
+printf '%s' "$CURRENT_HEAD" > "$CACHE_FILE"
+
+# 변경 감지 시 안내
+if [ "$STRUCTURE_CHANGED" = true ]; then
+  echo "[PROJECT_MAP] 프로젝트 구조 변경이 감지되었습니다. PROJECT_MAP.md 갱신을 권장합니다:"
+  echo "  .claude/scripts/generate-project-map.sh"
+fi

package/.claude/hooks/skill-detector.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# Skill Detector Hook
+# 사용자 프롬프트를 분석하여 관련 스킬을 자동 추천한다.
+# UserPromptSubmit hook으로 등록하여 사용한다.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CONF_FILE="${SCRIPT_DIR}/skill-keywords.conf"
+
+if [[ ! -f "$CONF_FILE" ]]; then
+  exit 0
+fi
+
+# stdin에서 프롬프트 읽기 (JSON 형태: {"prompt": "..."})
+INPUT=$(cat)
+PROMPT=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('prompt',''))" 2>/dev/null || echo "$INPUT")
+
+if [[ -z "$PROMPT" ]]; then
+  exit 0
+fi
+
+# 소문자 변환
+PROMPT_LOWER=$(echo "$PROMPT" | tr '[:upper:]' '[:lower:]')
+
+# 스킬별 점수 계산
+declare -a SKILL_NAMES=()
+declare -a SKILL_COMMANDS=()
+declare -a SKILL_SCORES=()
+
+while IFS= read -r line; do
+  # 빈 줄, 주석 건너뛰기
+  [[ -z "$line" || "$line" == \#* ]] && continue
+
+  SKILL_NAME=$(echo "$line" | cut -d'|' -f1)
+  SKILL_CMD=$(echo "$line" | cut -d'|' -f2)
+  KEYWORDS_STR=$(echo "$line" | cut -d'|' -f3)
+
+  SCORE=0
+  for keyword in $KEYWORDS_STR; do
+    if [[ "$PROMPT_LOWER" == *"$keyword"* ]]; then
+      SCORE=$((SCORE + 1))
+    fi
+  done
+
+  if ((SCORE > 0)); then
+    SKILL_NAMES+=("$SKILL_NAME")
+    SKILL_COMMANDS+=("$SKILL_CMD")
+    SKILL_SCORES+=("$SCORE")
+  fi
+done < "$CONF_FILE"
+
+# 매칭된 스킬이 없으면 침묵
+if ((${#SKILL_NAMES[@]} == 0)); then
+  exit 0
+fi
+
+# 점수 기준 내림차순 정렬 (상위 5개)
+SORTED_INDICES=()
+for i in "${!SKILL_SCORES[@]}"; do
+  SORTED_INDICES+=("$i")
+done
+
+# 버블 정렬 (점수 내림차순)
+for ((i = 0; i < ${#SORTED_INDICES[@]}; i++)); do
+  for ((j = i + 1; j < ${#SORTED_INDICES[@]}; j++)); do
+    idx_i=${SORTED_INDICES[$i]}
+    idx_j=${SORTED_INDICES[$j]}
+    if ((SKILL_SCORES[idx_j] > SKILL_SCORES[idx_i])); then
+      SORTED_INDICES[$i]=$idx_j
+      SORTED_INDICES[$j]=$idx_i
+    fi
+  done
+done
+
+# 상위 5개만
+MAX=5
+if ((${#SORTED_INDICES[@]} < MAX)); then
+  MAX=${#SORTED_INDICES[@]}
+fi
+
+# 출력
+echo "[Skill Detector]"
+echo "프롬프트 분석 결과, 다음 스킬을 반드시 참조하라:"
+for ((i = 0; i < MAX; i++)); do
+  idx=${SORTED_INDICES[$i]}
+  echo "- ${SKILL_NAMES[$idx]}: /skill ${SKILL_COMMANDS[$idx]}"
+done
+echo "구현 전에 위 스킬을 로드하여 패턴을 따르라."

package/.claude/hooks/skill-keywords.conf

@@ -0,0 +1,19 @@
+# Skill Detector 키워드 매핑 설정
+# FORMAT: SKILL_NAME|SKILL_COMMAND|KEYWORD1 KEYWORD2 ...
+# - SKILL_NAME: 표시용 이름
+# - SKILL_COMMAND: /skill 명령에 사용할 이름
+# - KEYWORDS: 공백으로 구분된 매칭 키워드 (소문자)
+#
+# 스킬 추가 시 이 파일만 수정하면 됩니다.
+
+React|React|react 리액트 컴포넌트 component hook usestate useeffect usememo usecallback useref props jsx tsx 훅 커스텀훅
+NextJS|NextJS|next.js nextjs 넥스트 app router server component route handler server action ssr ssg isr middleware layout page
+TailwindCSS|TailwindCSS|tailwind tailwindcss 테일윈드 스타일 className cn cva variant 반응형 다크모드 dark mode
+TanStackQuery|TanStackQuery|tanstack query react-query 리액트쿼리 usequery usemutation querykey prefetch invalidate 서버상태
+Zustand|Zustand|zustand 주스탄드 store 스토어 전역상태 global state slice persist devtools
+ReactHookForm|ReactHookForm|react-hook-form 리액트훅폼 useform register handlesubmit controller zod schema 폼 form validation 검증
+TypeScript|TypeScript|typescript 타입스크립트 타입 type interface generic 제네릭 유틸리티타입 타입가드 type guard
+TypeORM|TypeORM|typeorm 타입오알엠 entity repository querybuilder migration 마이그레이션 relation 트랜잭션 transaction
+Coding|Coding|리팩토링 refactor 클린코드 clean code 네이밍 naming 에러처리 error handling 코드품질
+TDD|TDD|tdd 테스트 test jest vitest 단위테스트 unit test e2e 통합테스트 integration test mock stub spy
+Git|Git|git 커밋 commit 브랜치 branch pr pull request merge rebase

package/.claude/scripts/generate-project-map.sh

@@ -0,0 +1,264 @@
+#!/usr/bin/env bash
+# generate-project-map.sh - PROJECT_MAP.md를 자동 생성한다
+# Usage: .claude/scripts/generate-project-map.sh
+# 프로젝트 루트에서 실행하면 .claude/PROJECT_MAP.md를 생성한다.
+
+set -e
+
+# .claude 디렉토리 확인
+CLAUDE_DIR=""
+if [ -d ".claude" ]; then
+  CLAUDE_DIR=".claude"
+elif [ -d "$(git rev-parse --show-toplevel 2>/dev/null)/.claude" ]; then
+  CLAUDE_DIR="$(git rev-parse --show-toplevel)/.claude"
+else
+  echo "Error: .claude/ 디렉토리를 찾을 수 없습니다." >&2
+  exit 1
+fi
+
+OUTPUT_FILE="$CLAUDE_DIR/PROJECT_MAP.md"
+TEMP_FILE="$(mktemp)"
+trap 'rm -f "$TEMP_FILE"' EXIT
+
+# === JSON 파싱 헬퍼 ===
+# python3 사용 가능하면 python3, 아니면 순수 grep/sed 폴백
+json_get() {
+  local file="$1"
+  local key="$2"
+  if command -v python3 &>/dev/null; then
+    python3 -c "
+import json, sys
+try:
+    d = json.load(open('$file'))
+    val = d.get('$key', '')
+    if isinstance(val, str):
+        print(val)
+    elif isinstance(val, dict):
+        for k in val:
+            print(k)
+    elif isinstance(val, list):
+        for item in val:
+            print(item)
+except:
+    pass
+" 2>/dev/null
+  else
+    grep -o "\"$key\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" "$file" 2>/dev/null | head -1 | sed 's/.*: *"\(.*\)"/\1/'
+  fi
+}
+
+json_get_scripts() {
+  local file="$1"
+  if command -v python3 &>/dev/null; then
+    python3 -c "
+import json, sys
+try:
+    d = json.load(open('$file'))
+    scripts = d.get('scripts', {})
+    for key in ['dev', 'build', 'test', 'start', 'lint']:
+        if key in scripts:
+            print(f'{key}: {scripts[key]}')
+except:
+    pass
+" 2>/dev/null
+  fi
+}
+
+json_get_deps() {
+  local file="$1"
+  if command -v python3 &>/dev/null; then
+    python3 -c "
+import json, sys
+try:
+    d = json.load(open('$file'))
+    deps = {}
+    deps.update(d.get('dependencies', {}))
+    deps.update(d.get('devDependencies', {}))
+    # 주요 프레임워크/라이브러리만 추출
+    keywords = [
+        'react', 'next', 'vue', 'nuxt', 'angular', 'svelte',
+        'nest', 'express', 'fastify', 'koa', 'hono',
+        'typeorm', 'prisma', 'drizzle', 'mongoose', 'sequelize',
+        'tailwind', 'styled-components', 'emotion',
+        'jest', 'vitest', 'mocha', 'cypress', 'playwright',
+        'typescript', 'webpack', 'vite', 'turbo', 'esbuild',
+        'zustand', 'redux', 'recoil', 'jotai', 'mobx',
+        'tanstack', 'react-query', 'swr', 'axios',
+        'zod', 'yup', 'joi', 'class-validator',
+        'react-hook-form', 'formik',
+        'storybook', 'eslint', 'prettier',
+    ]
+    found = []
+    for dep, ver in sorted(deps.items()):
+        dep_lower = dep.lower()
+        for kw in keywords:
+            if kw in dep_lower:
+                found.append(f'{dep}@{ver}')
+                break
+    for item in found:
+        print(item)
+except:
+    pass
+" 2>/dev/null
+  fi
+}
+
+# === 생성 시작 ===
+{
+  echo "# PROJECT MAP"
+  echo ""
+  echo "> Auto-generated by \`generate-project-map.sh\`"
+  echo "> 이 파일은 explore 에이전트의 사전 캐시로 사용된다. 직접 수정하지 말 것."
+  echo ""
+
+  # --- 프로젝트 정보 ---
+  echo "## 프로젝트 정보"
+  echo ""
+
+  if [ -f "package.json" ]; then
+    local_name="$(json_get package.json name)"
+    if [ -n "$local_name" ]; then
+      echo "- **이름**: $local_name"
+    fi
+  fi
+
+  if command -v git &>/dev/null && git rev-parse --is-inside-work-tree &>/dev/null 2>&1; then
+    echo "- **브랜치**: $(git branch --show-current 2>/dev/null || echo 'unknown')"
+    echo "- **최근 커밋**: $(git log -1 --format='%h %s' 2>/dev/null || echo 'unknown')"
+  fi
+
+  echo "- **생성 시간**: $(date '+%Y-%m-%d %H:%M:%S')"
+
+  # 총 파일 수 (소스 파일만)
+  total_files=0
+  if command -v git &>/dev/null && git rev-parse --is-inside-work-tree &>/dev/null 2>&1; then
+    total_files=$(git ls-files 2>/dev/null | wc -l | tr -d ' ')
+  else
+    total_files=$(find . -type f \
+      -not -path '*/node_modules/*' \
+      -not -path '*/.git/*' \
+      -not -path '*/.next/*' \
+      -not -path '*/dist/*' \
+      -not -path '*/build/*' \
+      -not -path '*/coverage/*' \
+      2>/dev/null | wc -l | tr -d ' ')
+  fi
+  echo "- **총 파일 수**: $total_files"
+  echo ""
+
+  # --- 기술 스택 ---
+  if [ -f "package.json" ]; then
+    deps="$(json_get_deps package.json)"
+    if [ -n "$deps" ]; then
+      echo "## 기술 스택"
+      echo ""
+      echo '```'
+      echo "$deps"
+      echo '```'
+      echo ""
+    fi
+  fi
+
+  # --- 디렉토리 구조 ---
+  echo "## 디렉토리 구조"
+  echo ""
+  echo '```'
+
+  EXCLUDE_DIRS="node_modules|.git|.next|dist|build|coverage|.cache|.turbo|__pycache__|.venv|vendor"
+
+  find_dirs() {
+    find . -maxdepth 3 -type d \
+      \( -name node_modules -o -name .git -o -name .next -o -name dist \
+         -o -name build -o -name coverage -o -name .cache -o -name .turbo \
+         -o -name __pycache__ -o -name .venv -o -name vendor \
+         -o -name .idea -o -name .vscode \) -prune \
+      -o -type d -print 2>/dev/null | sort | head -80
+  }
+
+  if command -v tree &>/dev/null; then
+    tree -d -L 3 -I "$EXCLUDE_DIRS|.idea|.vscode" --noreport 2>/dev/null || find_dirs
+  else
+    find_dirs
+  fi
+
+  echo '```'
+  echo ""
+
+  # --- 주요 파일 ---
+  echo "## 주요 파일"
+  echo ""
+
+  # 설정 파일
+  config_files=""
+  for f in package.json tsconfig.json tsconfig.*.json \
+           .eslintrc* eslint.config.* .prettierrc* prettier.config.* \
+           next.config.* vite.config.* webpack.config.* \
+           nest-cli.json ormconfig.* \
+           docker-compose.yml Dockerfile \
+           .env.example .env.local.example; do
+    # glob 확장이 파일과 매치하는지 확인
+    for match in $f; do
+      if [ -f "$match" ]; then
+        config_files="$config_files$match\n"
+      fi
+    done
+  done
+
+  if [ -n "$config_files" ]; then
+    echo "### 설정 파일"
+    echo ""
+    printf '%b' "$config_files" | sort -u | while read -r cf; do
+      [ -n "$cf" ] && echo "- \`$cf\`"
+    done
+    echo ""
+  fi
+
+  # 엔트리포인트
+  entry_files=""
+  for f in src/main.ts src/main.tsx src/index.ts src/index.tsx \
+           src/app.ts src/app.tsx src/App.tsx \
+           app/layout.tsx app/page.tsx \
+           src/app/layout.tsx src/app/page.tsx \
+           pages/_app.tsx pages/index.tsx \
+           src/pages/_app.tsx src/pages/index.tsx; do
+    if [ -f "$f" ]; then
+      entry_files="$entry_files$f\n"
+    fi
+  done
+
+  if [ -n "$entry_files" ]; then
+    echo "### 엔트리포인트"
+    echo ""
+    printf '%b' "$entry_files" | while read -r ef; do
+      [ -n "$ef" ] && echo "- \`$ef\`"
+    done
+    echo ""
+  fi
+
+  # --- 빌드 명령 ---
+  if [ -f "package.json" ]; then
+    scripts="$(json_get_scripts package.json)"
+    if [ -n "$scripts" ]; then
+      echo "## 빌드 명령"
+      echo ""
+      echo '```'
+      echo "$scripts"
+      echo '```'
+      echo ""
+    fi
+  fi
+
+} > "$TEMP_FILE"
+
+# 파일 크기 확인 (20KB 제한)
+file_size=$(wc -c < "$TEMP_FILE" | tr -d ' ')
+if [ "$file_size" -gt 20480 ]; then
+  echo "Warning: PROJECT_MAP.md가 20KB를 초과합니다 (${file_size}B). 잘라냅니다." >&2
+  head -c 20480 "$TEMP_FILE" > "$OUTPUT_FILE"
+  echo "" >> "$OUTPUT_FILE"
+  echo "> [truncated - 20KB 제한 초과]" >> "$OUTPUT_FILE"
+else
+  cp "$TEMP_FILE" "$OUTPUT_FILE"
+fi
+
+echo "PROJECT_MAP.md 생성 완료: $OUTPUT_FILE (${file_size}B)"

package/.claude/settings.json

@@ -7,6 +7,14 @@
           {
             "type": "command",
             "command": ".claude/hooks/quality-gate.sh"
+          },
+          {
+            "type": "command",
+            "command": ".claude/hooks/skill-detector.sh"
+          },
+          {
+            "type": "command",
+            "command": ".claude/hooks/project-map-detector.sh"
           }
         ]
       }

package/.claude/skills/TailwindCSS/SKILL.md

@@ -26,11 +26,23 @@ React 규칙은 `../React/SKILL.md`, 공통 원칙은 `../Coding/SKILL.md`를
 
 ### 클래스 조합
 - 관련 있는 클래스를 논리적 그룹으로 정렬한다
-- 권장 순서: 레이아웃 -> 크기 -> 간격 -> 타이포그래피 -> 색상 -> 효과
+- 권장 순서: 레이아웃 → 크기 → 간격 → 타이포그래피 → 색상 → 효과
+- **클래스가 길어지면 관심사별로 줄바꿈하여 가독성을 높인다**
 
 ```typescript
-// Good - 논리적 순서로 정렬
+// Bad - 한 줄로 길게 나열 (화면 벗어남, 어떤 CSS가 있는지 파악 어려움)
 <button className="flex items-center justify-center w-full h-10 px-4 text-sm font-medium text-white bg-blue-600 rounded-lg hover:bg-blue-700">
+
+// Good - 관심사별 줄바꿈
+<button
+  className={cn(
+    'flex items-center justify-center', // 레이아웃
+    'w-full h-10 px-4',                 // 크기/간격
+    'text-sm font-medium text-white',   // 타이포그래피
+    'bg-blue-600 rounded-lg',           // 배경/모양
+    'hover:bg-blue-700',                // 상태
+  )}
+>
   버튼
 </button>
 ```
@@ -227,7 +239,8 @@ export function Button({ variant = 'primary', size = 'md', className, children }
     <button
       className={cn(
         // 기본 스타일
-        'inline-flex items-center justify-center rounded-lg font-medium transition-colors',
+        'inline-flex items-center justify-center',
+        'rounded-lg font-medium transition-colors',
         // variant
         {
           'bg-blue-600 text-white hover:bg-blue-700': variant === 'primary',
@@ -261,7 +274,12 @@ import { cn } from '@/lib/utils';
 
 const buttonVariants = cva(
   // 기본 스타일
-  'inline-flex items-center justify-center rounded-lg font-medium transition-colors disabled:pointer-events-none disabled:opacity-50',
+  [
+    'inline-flex items-center justify-center', // 레이아웃
+    'rounded-lg font-medium',                  // 모양/타이포
+    'transition-colors',                       // 효과
+    'disabled:pointer-events-none disabled:opacity-50', // 상태
+  ],
   {
     variants: {
       variant: {
@@ -370,4 +388,4 @@ const colorClasses = {
 } as const;
 
 <div className={colorClasses[color]}>
-```
+```

package/README.md

@@ -49,8 +49,13 @@
 │   │   └── backend.md           ← NestJS 테스트 규칙
 │   └── Git/
 │       └── SKILL.md             ← 커밋/PR/브랜치 규칙
-└── hooks/
-    └── quality-gate.sh          ← 품질 체크 프로토콜
+├── hooks/
+│   ├── quality-gate.sh          ← 품질 체크 프로토콜
+│   ├── skill-detector.sh        ← 프롬프트 기반 스킬 자동 추천
+│   ├── skill-keywords.conf      ← 스킬별 키워드 매핑 설정
+│   └── project-map-detector.sh  ← 프로젝트 구조 변경 감지
+└── scripts/
+    └── generate-project-map.sh  ← PROJECT_MAP.md 자동 생성
 ```
 
 ## 설치
@@ -131,9 +136,35 @@ Main Agent는 직접 코드를 작성하거나 탐색하지 않고, 전문 서
 | test-writer | opus | TDD 테스트 작성/실행 |
 | git-manager | sonnet | 커밋, 브랜치, PR |
 
-### Quality Gate Hook
+### Hooks
 
-매 프롬프트마다 `quality-gate.sh`가 실행되어 적절한 에이전트/스킬 활용을 상기시킨다.
+매 프롬프트마다 UserPromptSubmit hook이 실행된다.
+
+| Hook | 역할 |
+|------|------|
+| quality-gate.sh | 적절한 에이전트/스킬 활용을 상기시킨다 |
+| skill-detector.sh | 프롬프트 키워드를 분석하여 관련 스킬을 자동 추천한다 |
+| project-map-detector.sh | 프로젝트 구조 변경을 감지하여 PROJECT_MAP.md 갱신을 안내한다 |
+
+`skill-keywords.conf`에서 스킬별 키워드를 관리하며, 스킬 추가 시 conf 파일만 수정하면 된다.
+
+### PROJECT_MAP.md
+
+explore 에이전트가 매번 코드베이스를 재탐색하는 비용을 줄이기 위해, 프로젝트 구조를 캐싱한다.
+
+```bash
+# PROJECT_MAP.md 생성
+.claude/scripts/generate-project-map.sh
+```
+
+생성되는 내용:
+- 프로젝트 정보 (이름, 브랜치, 최근 커밋)
+- 기술 스택 (package.json에서 자동 감지)
+- 디렉토리 구조 (3레벨 깊이)
+- 주요 파일 (설정 파일, 엔트리포인트)
+- 빌드 명령 (dev/build/test/start)
+
+`project-map-detector.sh` hook이 구조 변경(파일 추가/삭제, 설정 파일 변경)을 감지하면 갱신을 안내한다.
 
 ## 프로젝트별 커스터마이징
 

package/install.sh

@@ -242,6 +242,10 @@ copy_common() {
   # hooks
   copy_dir "hooks"
   chmod +x "$TARGET_DIR/hooks/"*.sh
+
+  # scripts
+  copy_dir "scripts"
+  chmod +x "$TARGET_DIR/scripts/"*.sh
 }
 
 # FE (프론트엔드)
@@ -330,6 +334,7 @@ echo "  $TARGET_DIR/settings.json"
 echo "  $TARGET_DIR/agents/"
 echo "  $TARGET_DIR/skills/"
 echo "  $TARGET_DIR/hooks/"
+echo "  $TARGET_DIR/scripts/"
 echo ""
 if [ "$INSTALL_MODE" = "global" ]; then
   echo "이제 어떤 프로젝트에서든 Claude Code를 실행하면 자동으로 적용됩니다."
@@ -337,3 +342,6 @@ else
   echo "현재 프로젝트($(pwd))에서 Claude Code를 실행하면 자동으로 적용됩니다."
   echo "다른 프로젝트에도 적용하려면 --global 옵션을 사용하세요."
 fi
+echo ""
+echo "PROJECT_MAP.md를 생성하면 explore 에이전트가 더 빠르게 동작합니다:"
+echo "  $TARGET_DIR/scripts/generate-project-map.sh"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@choblue/claude-code-toolkit",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Claude Code 서브에이전트 위임 툴킷 - npx로 바로 설치",
   "bin": {
     "claude-code-toolkit": "bin/cli.js"