모범 사례와 함정

​

핵심 원칙 다섯 가지

​

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

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

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

​

2. TDD — 테스트 통과까지가 “완료”

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

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

​

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

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

​

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

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

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

​

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

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

​

흔한 안티 패턴

​

안티 패턴 1: “좋아 보이니 머지”

​

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

# ❌ 절대 금지
DATABRICKS_TOKEN = "dapi1234567890abcdef..."

# ✅ 환경 변수 또는 Databricks Secrets
import os
DATABRICKS_TOKEN = os.environ["DATABRICKS_TOKEN"]

​

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

​

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

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

​

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

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

​

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

# 배포 직후
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 공식 문서
• Anthropic Cookbook
• MCP 공식 사이트
• 본 사이트의 Genie Code 가이드 — Databricks 워크스페이스 안에서 동작하는 자매 도구

​

마무리

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

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