> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sifi.life/llms.txt
> Use this file to discover all available pages before exploring further.

# 모범 사례와 함정

> Claude Code를 안전하고 효과적으로 사용하기 위한 원칙과 안티 패턴

## 핵심 원칙 다섯 가지

### 1. 작업 전 검증 — 방향이 맞는지 두세 번 확인

코드를 짜기 전에 항상:

* **올바른 환경인가?** 워크스페이스, 카탈로그, 브랜치 모두 확인
* **현재 상태를 알고 있나?** 스키마, 데이터, 권한을 먼저 파악
* **영향 범위는?** 이 변경이 다른 기능을 깨뜨리지는 않나

> 잘못된 워크스페이스에 데이터를 넣고 나서 되돌리는 것은, 처음부터 5분 더 확인하는 것보다 훨씬 비쌉니다.

### 2. TDD — 테스트 통과까지가 "완료"

Claude는 코드 작성에 능숙하지만, 그것이 곧 동작 보장은 아닙니다. 항상:

```
함수 작성 → 단위 테스트 → 테스트 통과 → 완료
```

* 단일 함수 변경: 입출력 테스트
* API 엔드포인트 변경: HTTP 호출 + 응답 구조 검증
* 3개 이상 파일 변경: 통합 테스트 + 배포 후 로그 확인

### 3. 영향도 검토 — 한 줄 변경에도 전체 검토

* 변수 추가 시: 그 변수를 참조하는 모든 곳의 실행 순서 확인
* 함수 시그니처 변경 시: 호출하는 모든 곳을 검색
* 모듈 레벨 코드 변경 시: 시작 시 의존성 확인
* 프론트엔드 변경 시: 트랜스파일·번들 호환성 확인

### 4. 점진적 변경 — 큰 PR보다 작은 PR 여러 개

큰 변경을 한 번에 요청하면:

* 컨텍스트 폭주
* 부분 실패 시 롤백 어려움
* 리뷰 불가능

대신:

* `/plan`으로 계획을 단계로 분할
* 각 단계가 독립적으로 동작하고 테스트 가능하도록
* 단계마다 커밋

### 5. 비용 의식 — `/cost`를 자주 확인

Claude Code는 토큰을 빠르게 소모할 수 있습니다. 특히 대규모 코드베이스 탐색이나 멀티 에이전트 사용 시:

* `/cost`로 누적 비용 확인
* 컨텍스트가 무거워지면 `/clear` 또는 `/compact`
* 모델 선택: 단순 작업은 Sonnet/Haiku, 복잡한 작업만 Opus

## 흔한 안티 패턴

### 안티 패턴 1: "좋아 보이니 머지"

Claude가 "구현 완료"라고 했다고 동작이 검증된 것은 아닙니다. **반드시 직접 실행해서 확인**하세요. UI 변경이라면 브라우저에서 클릭해 보고, API 변경이라면 curl로 호출해 봅니다.

### 안티 패턴 2: 시크릿을 코드에 평문 저장

```python theme={null}
# ❌ 절대 금지
DATABRICKS_TOKEN = "dapi1234567890abcdef..."
```

```python theme={null}
# ✅ 환경 변수 또는 Databricks Secrets
import os
DATABRICKS_TOKEN = os.environ["DATABRICKS_TOKEN"]
```

`.claudeignore`에 시크릿 파일을 추가하는 것도 잊지 마세요.

### 안티 패턴 3: 모든 권한을 화이트리스트에 추가

처음에는 매번 권한 확인이 귀찮아 보이지만, 화이트리스트를 너무 넓게 잡으면 위험한 명령(예: `git reset --hard`, `rm -rf`, `databricks workspace delete`)도 자동 실행됩니다.

화이트리스트는 **명백히 읽기 전용이거나 되돌릴 수 있는 명령에만** 적용하세요.

### 안티 패턴 4: Claude의 추측을 검증 없이 신뢰

Claude는 대부분 정확하지만, 가끔 존재하지 않는 함수를 호출하거나 deprecated된 API를 사용합니다. 특히 라이브러리 버전이나 클라우드 서비스 사양에 대해서는:

* **실제 문서를 검증** (databricks-docs, context7 같은 스킬 활용)
* **실제 코드베이스를 그래프** (grep, ToolSearch)
* 의심스러우면 Claude에게 "이 함수가 정말 존재하는지 확인해줘"라고 명시적으로 요청

### 안티 패턴 5: 노트북에서 검증한 코드를 그대로 프로덕션에 복사

노트북은 인터랙티브 셀 컨텍스트에 의존합니다. 같은 코드를 스크립트로 옮기면:

* import 순서가 달라짐
* 환경 변수가 다르게 설정됨
* 권한 모델이 다름 (노트북 사용자 권한 vs SP)

Claude에게 "노트북에서 스크립트로 변환해줘"라고 할 때는 **반드시 변환 후 실행 테스트**를 요청하세요.

### 안티 패턴 6: 로그 한 번만 보고 "괜찮은 것 같아"

배포 후 즉시 로그를 보면 정상이지만, 5분 후 첫 트래픽이 들어왔을 때 에러가 터지는 경우가 흔합니다. 핵심 기능을 한 번 사용해 본 뒤 로그를 다시 확인하세요.

```bash theme={null}
# 배포 직후
databricks apps logs APP_NAME | tail -50

# 핵심 기능 사용 후
curl -X POST $APP_URL/api/critical-endpoint -d '{"test":true}'
databricks apps logs APP_NAME | tail -50 | grep -E 'ERROR|Traceback|500'
```

## 프롬프트 작성 모범 사례

### 목표 + 제약 + 검증을 한 번에

```
✅ 좋음:
"src/api/users.py의 GET /users 엔드포인트에 페이지네이션 추가해줘.
 page와 page_size 쿼리 파라미터, 기본값은 page=1 size=20, 최대 size=100.
 추가 후 tests/api/test_users.py에 테스트 추가하고 pytest로 통과 확인."

❌ 나쁨:
"users API에 페이지네이션 추가"
```

### 부정형보다 긍정형으로

```
❌ "타입 힌트 빼먹지 마"
✅ "모든 함수에 Python 타입 힌트를 작성해줘 (Pydantic 모델 사용)"

❌ "에러 핸들링 빠지면 안 돼"
✅ "각 외부 API 호출은 try/except로 감싸고, 실패 시 구조화된 에러 객체를 반환"
```

### 컨텍스트 제공

```
✅ "이 코드베이스는 FastAPI 0.110, Python 3.11을 사용해.
    데이터베이스는 Lakebase (Postgres) + SQLAlchemy 2.0 async."

✅ "팀 컨벤션상 함수명은 snake_case, 클래스명은 PascalCase,
    에러 클래스는 *Error 접미사."
```

## 디버깅 패턴

### 패턴 1: 가설 → 검증

```
> 사용자 로그인이 5분 후 만료되는 버그를 조사해줘.
  내 가설은 두 가지야:
  1. 쿠키 max-age가 짧게 설정됨
  2. 세션 갱신 로직에 race condition

  src/auth 전체를 보고, 각 가설을 지지하거나 반박하는 증거를 모아줘.
  가설 중 어느 쪽도 맞지 않으면 다른 가능성을 제시해줘.
```

### 패턴 2: 이분 탐색

```
> 어제 커밋에는 정상이었는데 오늘 깨졌어. 그 사이 30개 커밋이 있어.
  git bisect로 어느 커밋이 문제를 일으키는지 찾아줘.
  각 단계에서 npm run test:integration로 검증.
```

### 패턴 3: 로그 트레이싱

```
> 운영 환경에서 사용자 ID 12345가 이번 주 동안 겪은 모든 에러를 추적해줘.
  로그는 system.access.logs 테이블에 있고, MLflow trace ID와 매칭하면
  더 자세한 흐름을 볼 수 있어.
```

## 팀 도입 가이드

### 1단계: 개인 검증 (1\~2주)

먼저 본인이 충분히 사용하면서 워크플로우와 함정을 익힙니다.

### 2단계: 팀 표준 정의

* `CLAUDE.md`에 팀 컨벤션 명시 (commit 중)
* `.claude/settings.json`에 공유 권한·후크 등록 (commit)
* `.claude/settings.local.json`은 개인용 (gitignore)
* 팀이 공통으로 쓸 슬래시 커맨드를 `.claude/commands/`에

### 3단계: 핵심 워크플로우 자동화

* PR 리뷰 자동화 (`/review`)
* 배포 전 체크리스트 (`/pre-deploy`)
* 일일 헬스 체크 (`/daily-health-check` + cron)

### 4단계: 모니터링과 피드백

* 토큰 사용량 추적 (`/cost`)
* 사고 사례 공유 (Claude가 잘못한 것, 사람이 못 잡은 것 모두)
* `CLAUDE.md`와 후크를 학습된 교훈으로 지속 갱신

## 참고 자료

* [Claude Code 공식 문서](https://docs.claude.com/en/docs/claude-code/overview)
* [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook)
* [MCP 공식 사이트](https://modelcontextprotocol.io/)
* 본 사이트의 [Genie Code 가이드](/workshop/section-1-vibe-coding-intro/genie-code/what-is-genie-code) — Databricks 워크스페이스 안에서 동작하는 자매 도구

## 마무리

Claude Code는 **사람의 판단을 대체하지 않고, 사람의 작업 속도를 높이는** 도구입니다. 가장 큰 가치는:

* 반복적인 보일러플레이트의 자동화
* 코드베이스 탐색 시간 단축
* 멀티 도구 워크플로우의 원스톱 처리

가장 큰 위험은:

* 검증 없는 신뢰
* 시크릿 노출
* 자동화의 폭주

원칙을 지키면 도구의 강점만 취할 수 있습니다.