Skip to main content

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.

​
핵심 원칙 다섯 가지

​
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: 시크릿을 코드에 평문 저장

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

# ✅ 환경 변수 또는 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분 후 첫 트래픽이 들어왔을 때 에러가 터지는 경우가 흔합니다. 핵심 기능을 한 번 사용해 본 뒤 로그를 다시 확인하세요. 
# 배포 직후
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는 사람의 판단을 대체하지 않고, 사람의 작업 속도를 높이는 도구입니다. 가장 큰 가치는:
  • 반복적인 보일러플레이트의 자동화
  • 코드베이스 탐색 시간 단축
  • 멀티 도구 워크플로우의 원스톱 처리
가장 큰 위험은:
  • 검증 없는 신뢰
  • 시크릿 노출
  • 자동화의 폭주
원칙을 지키면 도구의 강점만 취할 수 있습니다.