@choblue/claude-code-toolkit 1.1.2 → 1.1.6

package/.claude/.project-map-cache

@@ -0,0 +1 @@
+d077ab9cf015379b7523bdb1d5f301e8492bd08a

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) 위임
@@ -83,10 +89,17 @@ Main Agent의 Context Window는 제한적이다. 반드시 서브에이전트에
   - `SKILL.md` - 공통 TDD 원칙
   - `frontend.md` - React 테스트 규칙
   - `backend.md` - NestJS 테스트 규칙
+- `.claude/skills/DDD/SKILL.md` - DDD 전술적 패턴 (Entity, VO, Aggregate, Repository, Domain Event)
 - `.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,44 @@
+# PROJECT MAP
+
+> Auto-generated by `generate-project-map.sh`
+> 이 파일은 explore 에이전트의 사전 캐시로 사용된다. 직접 수정하지 말 것.
+
+## 프로젝트 정보
+
+- **이름**: @choblue/claude-code-toolkit
+- **브랜치**: main
+- **최근 커밋**: 1a377b9 FEAT: DDD 전술적 패턴 스킬 추가
+- **생성 시간**: 2026-02-26 14:09:28
+- **총 파일 수**: 44
+
+## 디렉토리 구조
+
+```
+.
+./.claude
+./.claude/agents
+./.claude/hooks
+./.claude/scripts
+./.claude/skills
+./.claude/skills/Coding
+./.claude/skills/DDD
+./.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,20 @@
+# 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
+DDD|DDD|ddd domain entity value object aggregate repository domain service domain event bounded context 도메인 엔티티 값객체 애그리거트 리포지토리 도메인서비스 도메인이벤트

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/Coding/SKILL.md

@@ -26,10 +26,108 @@ FE/BE별 상세 규칙은 각각의 파일을 참고한다.
 - **높은 응집도**: 관련 있는 로직을 같은 모듈에 모은다
   - 하나의 모듈 안에서 데이터와 동작이 밀접하게 관련된다
 
+### Early Return (Guard Clause)
+- 예외/실패 조건을 함수 상단에서 먼저 처리하고 빠져나온다
+- 중첩 if를 줄여 가독성을 높인다
+
+```typescript
+// Bad - 깊은 중첩
+function processOrder(order: Order): void {
+  if (order) {
+    if (order.isValid()) {
+      if (order.items.length > 0) {
+        // 실제 로직
+      }
+    }
+  }
+}
+
+// Good - 얼리 리턴
+function processOrder(order: Order): void {
+  if (!order) return;
+  if (!order.isValid()) return;
+  if (order.items.length === 0) return;
+
+  // 실제 로직
+}
+```
+
 ### DRY (Don't Repeat Yourself)
 - 동일한 로직이 3번 이상 반복되면 추출한다
 - 단, 2번까지는 중복을 허용한다 (섣부른 추상화 방지)
 
+### 선언적 & 함수형 스타일
+
+**선언적 > 명령적** - "어떻게(how)" 대신 "무엇(what)"을 표현한다.
+
+```typescript
+// Bad - 명령적: 루프로 직접 조작
+const activeNames: string[] = [];
+for (const user of users) {
+  if (user.isActive) {
+    activeNames.push(user.name);
+  }
+}
+
+// Good - 선언적: 의도를 바로 드러냄
+// 필터/변환 조건은 변수로 추출하여 합성하라
+const isActive = (u: User) => u.isActive;
+const toName = (u: User) => u.name;
+const activeNames = users.filter(isActive).map(toName);
+```
+
+**순수 함수 우선** - 같은 입력이면 항상 같은 출력, 부수효과 없음.
+
+```typescript
+// Bad - 외부 상태를 변경
+let totalPrice = 0;
+function addItemPrice(price: number): void {
+  totalPrice += price; // 외부 변수 변경
+}
+
+// Good - 새 값을 반환하는 순수 함수
+function calculateTotal(prices: number[]): number {
+  return prices.reduce((sum, price) => sum + price, 0);
+}
+```
+
+**불변성** - 기존 데이터를 변경하지 않고 새 데이터를 생성한다.
+
+```typescript
+// Bad - 원본 변경
+user.role = 'admin';
+items.push(newItem);
+
+// Good - 새 객체/배열 생성
+const promotedUser = { ...user, role: 'admin' };
+const updatedItems = [...items, newItem];
+```
+
+**부수효과 격리** - 순수 로직과 부수효과(I/O)를 분리한다.
+
+```typescript
+// Bad - 비즈니스 로직에 부수효과가 섞임
+async function processOrder(order: Order): Promise<void> {
+  const total = order.items.reduce((s, i) => s + i.price, 0);
+  const discount = total > 100 ? total * 0.1 : 0;
+  await db.save({ ...order, total: total - discount }); // 부수효과
+  await sendEmail(order.userId, total - discount);       // 부수효과
+}
+
+// Good - 순수 계산과 부수효과를 분리
+function calcOrderTotal(items: OrderItem[]): number {
+  const total = items.reduce((s, i) => s + i.price, 0);
+  const discount = total > 100 ? total * 0.1 : 0;
+  return total - discount;
+}
+
+async function processOrder(order: Order): Promise<void> {
+  const finalTotal = calcOrderTotal(order.items); // 순수
+  await db.save({ ...order, total: finalTotal }); // I/O 경계
+  await sendEmail(order.userId, finalTotal);       // I/O 경계
+}
+```
+
 ---
 
 ## 2. 네이밍 컨벤션