@kood/claude-code 0.6.5 → 0.6.7

package/templates/.claude/skills/project-optimizer/rules/code-error-handling.md

@@ -0,0 +1,75 @@
+---
+title: Consistent Error Handling Pattern
+impact: MEDIUM
+impactDescription: Predictable error flow, easier debugging
+tags: code, error, exception, result, handling
+languages: all
+related: [code-complexity, memory-leak-prevention]
+---
+
+## 일관된 에러 처리 패턴
+
+프로젝트 전체에서 하나의 에러 처리 패턴을 일관되게 사용합니다.
+
+**언어별 권장 패턴:**
+
+| 언어 | 패턴 | 핵심 |
+|------|------|------|
+| **Go** | `(value, error)` | 항상 err 체크, sentinel errors |
+| **Rust** | `Result<T, E>` | `?` 연산자, 커스텀 Error enum |
+| **Python** | Exception 계층 | 커스텀 Exception, `raise from` |
+| **JS/TS** | 커스텀 Error / Result | Error 서브클래스 또는 Result 타입 |
+| **Java** | Unchecked 선호 | RuntimeException 서브클래스 |
+
+**✅ 올바른 예시:**
+
+```typescript
+// JS/TS - 커스텀 Error 클래스
+class AppError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public statusCode: number = 500
+  ) {
+    super(message)
+    this.name = 'AppError'
+  }
+}
+class NotFoundError extends AppError {
+  constructor(resource: string) {
+    super(`${resource} not found`, 'NOT_FOUND', 404)
+  }
+}
+```
+
+```go
+// Go - sentinel errors + wrapping
+var ErrNotFound = errors.New("not found")
+var ErrUnauthorized = errors.New("unauthorized")
+
+func getUser(id string) (*User, error) {
+    user, err := db.Find(id)
+    if err != nil {
+        return nil, fmt.Errorf("getUser(%s): %w", id, err)
+    }
+    if user == nil {
+        return nil, ErrNotFound
+    }
+    return user, nil
+}
+```
+
+```rust
+// Rust - thiserror
+#[derive(Debug, thiserror::Error)]
+enum AppError {
+    #[error("not found: {0}")]
+    NotFound(String),
+    #[error("unauthorized")]
+    Unauthorized,
+    #[error(transparent)]
+    Database(#[from] sqlx::Error),
+}
+```
+
+**원칙:** 에러는 발생 지점에서 컨텍스트를 추가하고, 처리 지점에서 변환/로깅합니다.

package/templates/.claude/skills/project-optimizer/rules/code-naming.md

@@ -0,0 +1,52 @@
+---
+title: Use Intent-Revealing Names
+impact: MEDIUM
+impactDescription: Self-documenting code, reduced cognitive load
+tags: code, naming, readability, maintainability
+languages: all
+related: [code-complexity, dx-type-safety]
+---
+
+## 의도를 드러내는 이름 사용
+
+변수/함수/클래스 이름만으로 역할과 의도를 파악할 수 있게 합니다.
+
+**❌ 잘못된 예시:**
+
+```python
+d = {}          # 무엇의 딕셔너리?
+tmp = get()     # 임시? 무엇을 가져옴?
+flag = True     # 어떤 플래그?
+def proc(x):    # 무엇을 처리?
+    pass
+
+for i in lst:   # i와 lst가 무엇?
+    if i.s == 1:  # s가 무엇? 1이 무엇?
+        do(i)
+```
+
+**✅ 올바른 예시:**
+
+```python
+user_scores = {}
+active_user = get_current_user()
+is_premium = True
+def calculate_shipping_cost(order):
+    pass
+
+STATUS_ACTIVE = 1
+for user in users:
+    if user.status == STATUS_ACTIVE:
+        send_notification(user)
+```
+
+**명명 패턴:**
+
+| 유형 | 패턴 | 예시 |
+|------|------|------|
+| **Boolean** | `is_`, `has_`, `can_`, `should_` | `is_valid`, `has_permission` |
+| **함수** | 동사 + 목적어 | `calculate_total`, `send_email` |
+| **컬렉션** | 복수형 | `users`, `order_items` |
+| **맵/딕셔너리** | `x_by_y` | `user_by_id`, `orders_by_date` |
+| **상수** | `UPPER_SNAKE` | `MAX_RETRY_COUNT` |
+| **축약 금지** | 풀네임 사용 | `transaction` (not `txn`) |

package/templates/.claude/skills/project-optimizer/rules/concurrency-defer-await.md

@@ -0,0 +1,54 @@
+---
+title: Defer Await to Point of Use
+impact: CRITICAL
+impactDescription: Eliminates unnecessary blocking, enables overlap
+tags: concurrency, async, await, deferred
+languages: all
+related: [concurrency-parallel, memory-lazy-init]
+---
+
+## await/블로킹을 사용 지점으로 이동
+
+비동기 작업의 결과를 기다리는 시점을 실제 사용 지점으로 미뤄서, 그 사이에 다른 작업이 실행될 수 있게 합니다.
+
+**❌ 잘못된 예시 (즉시 대기):**
+
+```typescript
+// 결과가 10줄 뒤에서 필요한데 즉시 await
+const data = await fetchData()
+// ... 다른 동기 작업 10줄 ...
+processData(data)
+```
+
+```python
+data = await fetch_data()  # 여기서 블로킹
+# ... 다른 동기 작업 ...
+process_data(data)
+```
+
+**✅ 올바른 예시 (사용 시점에서 대기):**
+
+```typescript
+// Promise를 먼저 시작, 나중에 await
+const dataPromise = fetchData()  // 시작만 함
+// ... 다른 동기 작업 (이 동안 fetch 진행) ...
+const data = await dataPromise   // 실제 필요 시점에 await
+processData(data)
+```
+
+```python
+import asyncio
+task = asyncio.create_task(fetch_data())  # 시작만 함
+# ... 다른 동기 작업 ...
+data = await task  # 실제 필요 시점에 await
+process_data(data)
+```
+
+```go
+ch := make(chan *Data, 1)
+go func() { ch <- fetchData(ctx) }()  // 시작
+// ... 다른 작업 ...
+data := <-ch  // 실제 필요 시점에 수신
+```
+
+**핵심:** 작업 시작과 결과 소비 사이에 다른 유용한 작업이 있으면 defer 적용.

package/templates/.claude/skills/project-optimizer/rules/concurrency-parallel.md

@@ -0,0 +1,90 @@
+---
+title: Parallelize Independent Operations
+impact: CRITICAL
+impactDescription: 2-10x improvement on I/O-bound workloads
+tags: concurrency, parallelization, async, performance
+languages: all
+related: [concurrency-defer-await, concurrency-pool, io-batch-queries]
+---
+
+## 독립 작업 병렬 실행
+
+서로 의존성이 없는 I/O 작업은 동시에 실행하여 총 대기 시간을 최장 작업 1개 수준으로 줄입니다.
+
+**❌ 잘못된 예시 (순차 실행, 3번 왕복):**
+
+```typescript
+// JS/TS
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+// 총 시간: T(user) + T(posts) + T(comments)
+```
+
+```python
+# Python
+user = await fetch_user()
+posts = await fetch_posts()
+comments = await fetch_comments()
+```
+
+```go
+// Go
+user, _ := fetchUser(ctx)
+posts, _ := fetchPosts(ctx)
+comments, _ := fetchComments(ctx)
+```
+
+**✅ 올바른 예시 (병렬 실행, 1번 왕복):**
+
+```typescript
+// JS/TS
+const [user, posts, comments] = await Promise.all([
+  fetchUser(), fetchPosts(), fetchComments()
+])
+// 총 시간: max(T(user), T(posts), T(comments))
+```
+
+```python
+# Python
+user, posts, comments = await asyncio.gather(
+    fetch_user(), fetch_posts(), fetch_comments()
+)
+```
+
+```go
+// Go (errgroup)
+g, ctx := errgroup.WithContext(ctx)
+var user *User; var posts []Post; var comments []Comment
+g.Go(func() error { var err error; user, err = fetchUser(ctx); return err })
+g.Go(func() error { var err error; posts, err = fetchPosts(ctx); return err })
+g.Go(func() error { var err error; comments, err = fetchComments(ctx); return err })
+if err := g.Wait(); err != nil { return err }
+```
+
+```rust
+// Rust (tokio)
+let (user, posts, comments) = tokio::try_join!(
+    fetch_user(), fetch_posts(), fetch_comments()
+)?;
+```
+
+```java
+// Java
+var userFuture = CompletableFuture.supplyAsync(() -> fetchUser());
+var postsFuture = CompletableFuture.supplyAsync(() -> fetchPosts());
+CompletableFuture.allOf(userFuture, postsFuture).join();
+var user = userFuture.get();
+var posts = postsFuture.get();
+```
+
+```csharp
+// C#
+var userTask = FetchUserAsync();
+var postsTask = FetchPostsAsync();
+await Task.WhenAll(userTask, postsTask);
+var user = userTask.Result;
+var posts = postsTask.Result;
+```
+
+**적용 기준:** 두 작업이 서로의 결과를 필요로 하지 않으면 병렬화 대상.

package/templates/.claude/skills/project-optimizer/rules/concurrency-pipeline.md

@@ -0,0 +1,68 @@
+---
+title: Pipeline Parallelization
+impact: HIGH
+impactDescription: Continuous throughput for multi-stage processing
+tags: concurrency, pipeline, streaming, producer-consumer
+languages: all
+related: [concurrency-parallel, io-stream, memory-large-data]
+---
+
+## 파이프라인 병렬화
+
+다단계 처리에서 각 단계를 동시에 실행하여 처리량을 극대화합니다. 한 단계의 출력이 다음 단계의 입력이 되는 스트리밍 방식.
+
+**❌ 잘못된 예시 (단계별 전체 처리):**
+
+```python
+# 모든 데이터를 한 단계 완료 후 다음 단계
+items = fetch_all()           # 10초 대기
+processed = [process(i) for i in items]  # 10초 대기
+results = [save(p) for p in processed]   # 10초 대기
+# 총 30초, 메모리에 전체 데이터 적재
+```
+
+**✅ 올바른 예시 (스트리밍 파이프라인):**
+
+```python
+# Python (async generator)
+async def fetch_stream():
+    async for item in db.stream_query("SELECT ..."):
+        yield item
+
+async def process_stream(items):
+    async for item in items:
+        yield transform(item)
+
+async def save_stream(items):
+    batch = []
+    async for item in items:
+        batch.append(item)
+        if len(batch) >= 100:
+            await db.bulk_insert(batch)
+            batch.clear()
+    if batch:
+        await db.bulk_insert(batch)
+
+# 파이프라인 연결
+await save_stream(process_stream(fetch_stream()))
+```
+
+```go
+// Go (channel pipeline)
+func fetch(ctx context.Context) <-chan Item {
+    out := make(chan Item, 100)
+    go func() { defer close(out); /* fetch and send */ }()
+    return out
+}
+
+func process(in <-chan Item) <-chan Result {
+    out := make(chan Result, 100)
+    go func() { defer close(out); for item := range in { out <- transform(item) } }()
+    return out
+}
+
+// 파이프라인 연결
+results := process(fetch(ctx))
+```
+
+**적용 기준:** 데이터가 대량이고 단계별로 독립 처리 가능할 때.

package/templates/.claude/skills/project-optimizer/rules/concurrency-pool.md

@@ -0,0 +1,68 @@
+---
+title: Limit Concurrency with Pools
+impact: HIGH
+impactDescription: Prevents resource exhaustion, stable throughput
+tags: concurrency, pool, semaphore, rate-limiting, backpressure
+languages: all
+related: [concurrency-parallel, io-connection-reuse, memory-bounded-cache]
+---
+
+## 동시 실행 수 제한
+
+무제한 병렬화는 리소스 고갈을 유발. 커넥션 풀, 세마포어, 워커 풀로 동시 실행 수를 제한합니다.
+
+**❌ 잘못된 예시 (무제한 동시 실행):**
+
+```typescript
+// 1000개 URL 동시 요청 → 커넥션 고갈, OOM
+const results = await Promise.all(
+  urls.map(url => fetch(url))
+)
+```
+
+**✅ 올바른 예시 (동시 실행 수 제한):**
+
+```typescript
+// JS/TS (p-limit)
+import pLimit from 'p-limit'
+const limit = pLimit(10)  // 최대 10개 동시
+const results = await Promise.all(
+  urls.map(url => limit(() => fetch(url)))
+)
+```
+
+```python
+# Python (asyncio.Semaphore)
+sem = asyncio.Semaphore(10)
+async def limited_fetch(url):
+    async with sem:
+        return await fetch(url)
+
+results = await asyncio.gather(*[limited_fetch(url) for url in urls])
+```
+
+```go
+// Go (worker pool)
+func worker(jobs <-chan string, results chan<- Result) {
+    for url := range jobs {
+        results <- fetch(url)
+    }
+}
+// 10개 워커 실행
+for i := 0; i < 10; i++ { go worker(jobs, results) }
+```
+
+```rust
+// Rust (tokio::sync::Semaphore)
+let sem = Arc::new(Semaphore::new(10));
+let tasks: Vec<_> = urls.iter().map(|url| {
+    let permit = sem.clone().acquire_owned();
+    async move {
+        let _permit = permit.await.unwrap();
+        fetch(url).await
+    }
+}).collect();
+let results = futures::future::join_all(tasks).await;
+```
+
+**적정 동시 실행 수:** DB 커넥션 10-25, HTTP 요청 10-50, 파일 I/O 5-20.

package/templates/.claude/skills/project-optimizer/rules/deps-lightweight-alt.md

@@ -0,0 +1,37 @@
+---
+title: Replace Heavy Libraries with Lightweight Alternatives
+impact: MEDIUM
+impactDescription: 30-80% bundle/install size reduction
+tags: deps, lightweight, alternative, bundle-size
+languages: all
+related: [build-tree-shake, build-minify]
+---
+
+## 무거운 라이브러리 경량 대안으로 교체
+
+사용 기능 대비 과도하게 큰 라이브러리를 경량 대안 또는 네이티브 API로 교체합니다.
+
+**흔한 교체 대상:**
+
+| 무거운 라이브러리 | 경량 대안 | 크기 감소 |
+|-----------------|----------|----------|
+| `moment.js` (300KB) | `date-fns` 또는 `dayjs` (2-7KB) | 97% |
+| `lodash` (72KB) | 네이티브 JS 메서드 / `lodash-es` 직접 import | 90%+ |
+| `axios` (29KB) | `fetch` (내장) / `ky` (3KB) | 90% |
+| `uuid` (12KB) | `crypto.randomUUID()` (내장) | 100% |
+| `chalk` (20KB) | `picocolors` (2KB) | 90% |
+| `express` | `h3` / `Hono` (더 빠르고 작음) | 50%+ |
+
+**Python:**
+
+| 무거운 | 경량 대안 |
+|-------|----------|
+| `requests` | `httpx` (async 지원) |
+| `beautifulsoup4` | `selectolax` (10x 빠름) |
+| `pandas` (작은 작업) | `polars` (메모리 효율) |
+| `flake8+isort+black` | `ruff` (100x 빠름, 올인원) |
+
+**판단 기준:**
+1. 사용하는 기능이 전체의 10% 미만 → 교체 고려
+2. 네이티브 API로 대체 가능 → 교체
+3. 번들 크기 50KB+ 차이 → 교체 고려

package/templates/.claude/skills/project-optimizer/rules/deps-peer-align.md

@@ -0,0 +1,44 @@
+---
+title: Resolve Peer Dependency Conflicts
+impact: LOW-MEDIUM
+impactDescription: Eliminates runtime version conflicts
+tags: deps, peer, conflict, resolution
+languages: all
+related: [deps-version-pin, deps-security-audit]
+---
+
+## Peer Dependency 버전 충돌 해결
+
+peer dependency 경고/에러를 해결하여 런타임 버전 충돌을 방지합니다.
+
+**감지:**
+
+```bash
+# npm
+npm ls --all 2>&1 | grep "peer dep"
+npm install  # 경고 메시지 확인
+
+# yarn
+yarn install  # 경고 확인
+
+# pnpm
+pnpm install  # strict peer deps 기본
+```
+
+**해결 전략:**
+
+| 상황 | 해결 |
+|------|------|
+| 라이브러리 A가 react@18 요구, B가 react@19 요구 | A 업데이트 또는 overrides 사용 |
+| 여러 버전의 같은 라이브러리 설치됨 | `npm ls [pkg]`로 확인, 상위 버전으로 통일 |
+| 호환 불가 | `overrides` (npm) / `resolutions` (yarn) / `overrides` (pnpm) |
+
+```json
+// package.json - 강제 버전 통일
+{
+  "overrides": { "react": "^19.0.0" },
+  "resolutions": { "react": "^19.0.0" }
+}
+```
+
+**원칙:** overrides는 최후 수단. 먼저 라이브러리 업데이트 시도.

package/templates/.claude/skills/project-optimizer/rules/deps-security-audit.md

@@ -0,0 +1,45 @@
+---
+title: Audit Dependencies for Security Vulnerabilities
+impact: MEDIUM
+impactDescription: Prevent known CVE exploitation
+tags: deps, security, audit, vulnerability, cve
+languages: all
+related: [deps-version-pin]
+---
+
+## 보안 취약점 스캔 및 업데이트
+
+알려진 보안 취약점이 있는 의존성을 감지하고 업데이트합니다.
+
+**스캔 도구:**
+
+| 언어 | 도구 | 명령어 |
+|------|------|--------|
+| **JS/TS** | npm audit | `npm audit` / `npm audit fix` |
+| **JS/TS** | yarn audit | `yarn npm audit` |
+| **Python** | pip-audit | `pip-audit` |
+| **Python** | safety | `safety check` |
+| **Go** | govulncheck | `govulncheck ./...` |
+| **Rust** | cargo-audit | `cargo audit` |
+| **범용** | trivy | `trivy fs .` |
+| **범용** | Snyk | `snyk test` |
+
+**CI 통합:**
+
+```yaml
+# GitHub Actions
+- name: Security audit
+  run: npm audit --audit-level=high
+
+# Dependabot (자동 PR)
+# .github/dependabot.yml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+```
+
+**원칙:** CI에서 high/critical 취약점 발견 시 빌드 실패 설정.

package/templates/.claude/skills/project-optimizer/rules/deps-unused-removal.md

@@ -0,0 +1,25 @@
+---
+title: Remove Unused Dependencies
+impact: MEDIUM
+impactDescription: Smaller install size, fewer vulnerabilities, faster CI
+tags: deps, unused, cleanup, audit
+languages: all
+related: [build-tree-shake, code-dead-elimination]
+---
+
+## 미사용 의존성 제거
+
+설치되었지만 코드에서 import/require 되지 않는 패키지를 제거합니다.
+
+**감지 도구:**
+
+| 언어 | 도구 | 명령어 |
+|------|------|--------|
+| **JS/TS** | knip | `npx knip` |
+| **JS/TS** | depcheck | `npx depcheck` |
+| **Python** | deptry | `deptry .` |
+| **Go** | go mod tidy | `go mod tidy` (자동 정리) |
+| **Rust** | cargo-udeps | `cargo +nightly udeps` |
+| **Java** | gradle-dependency-analysis | Gradle 플러그인 |
+
+**주의:** devDependencies (빌드/테스트 도구)는 코드에서 직접 import하지 않아도 필요할 수 있음. 빌드 확인 후 제거.

package/templates/.claude/skills/project-optimizer/rules/deps-version-pin.md

@@ -0,0 +1,40 @@
+---
+title: Pin Production Dependency Versions
+impact: MEDIUM
+impactDescription: Reproducible builds, no surprise breakages
+tags: deps, version, pin, lock, reproducible
+languages: all
+related: [deps-security-audit, deps-peer-align]
+---
+
+## 프로덕션 의존성 버전 고정
+
+lockfile을 커밋하고 프로덕션 의존성은 정확한 버전으로 설치합니다.
+
+**✅ 필수:**
+
+| 파일 | 언어 | Git 커밋 |
+|------|------|---------|
+| `package-lock.json` / `yarn.lock` / `pnpm-lock.yaml` | JS/TS | 필수 |
+| `Cargo.lock` | Rust (바이너리) | 필수 |
+| `go.sum` | Go | 필수 |
+| `poetry.lock` / `uv.lock` | Python | 필수 |
+| `Gemfile.lock` | Ruby | 필수 |
+
+**CI에서 lockfile 기반 설치:**
+
+```bash
+# npm
+npm ci  # (npm install 아님!)
+
+# yarn
+yarn install --immutable
+
+# pnpm
+pnpm install --frozen-lockfile
+
+# pip
+pip install -r requirements.txt --no-deps
+```
+
+**원칙:** `npm install`/`yarn install`은 lockfile을 수정할 수 있으므로 CI에서는 `ci`/`--frozen-lockfile` 사용.

package/templates/.claude/skills/project-optimizer/rules/dx-ci-speed.md

@@ -0,0 +1,47 @@
+---
+title: Optimize CI Pipeline Speed
+impact: MEDIUM
+impactDescription: 30-70% CI time reduction
+tags: dx, ci, pipeline, speed, cache
+languages: all
+related: [build-cache, build-incremental, dx-test-coverage]
+---
+
+## CI 파이프라인 속도 최적화
+
+CI 파이프라인의 불필요한 단계를 제거하고 병렬화/캐싱을 적용합니다.
+
+**최적화 전략:**
+
+| 전략 | 효과 | 적용 |
+|------|------|------|
+| **의존성 캐시** | 50-80% 설치 시간 감소 | lockfile 해시 기반 캐시 키 |
+| **병렬 단계** | 단계 수에 비례 감소 | lint, test, build 동시 실행 |
+| **변경 파일만** | 대규모 모노레포에서 효과적 | `turbo run --filter=...` |
+| **불필요 단계 제거** | 즉시 효과 | 중복 설치, 불필요 빌드 제거 |
+
+```yaml
+# GitHub Actions - 병렬 + 캐시
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/cache@v4
+        with: { path: node_modules, key: deps-${{ hashFiles('yarn.lock') }} }
+      - run: yarn lint
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/cache@v4
+        with: { path: node_modules, key: deps-${{ hashFiles('yarn.lock') }} }
+      - run: yarn test
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, test]  # lint/test 병렬 후 build
+    steps:
+      - run: yarn build
+```
+
+**모노레포:** Turborepo `--filter=[HEAD^1]`, Nx `affected:test`.

package/templates/.claude/skills/project-optimizer/rules/dx-dev-server.md

@@ -0,0 +1,35 @@
+---
+title: Speed Up Local Development Server
+impact: MEDIUM
+impactDescription: Faster feedback loop, improved developer productivity
+tags: dx, dev-server, hmr, startup, watch
+languages: [js, ts, go, python, rust]
+related: [build-incremental, dx-ci-speed]
+---
+
+## 로컬 개발 서버 시작 속도 개선
+
+개발 서버 시작 시간과 HMR(Hot Module Replacement) 속도를 최적화합니다.
+
+**프론트엔드:**
+
+| 도구 | 팁 |
+|------|-----|
+| **Vite** | 이미 빠름. `server.warmup` 활성화, `optimizeDeps.include` 프리번들링 |
+| **webpack** | Vite/Turbopack으로 마이그레이션 고려 |
+| **Next.js** | Turbopack (`next dev --turbo`) |
+
+**백엔드:**
+
+| 언어 | 도구 | 설정 |
+|------|------|------|
+| **Node.js** | `tsx --watch` | 네이티브 ESM, 즉시 시작 |
+| **Go** | `air` | `.air.toml` 설정 |
+| **Python** | `uvicorn --reload` | FastAPI 기본 |
+| **Rust** | `cargo-watch` | `cargo watch -x run` |
+
+**공통 개선:**
+
+- TypeScript: `tsconfig.json`에서 `skipLibCheck: true` (개발 시)
+- 불필요 플러그인 비활성화 (개발 시 린팅 플러그인 분리)
+- `.gitignore`/`watchignore`에 빌드 출력 디렉토리 추가