Claude Code 대화 트레이싱 자동화: LangSmith 연동으로 개발 흐름을 관측하는 방법

이 글에서는 Claude Code CLI에서 발생하는 대화 내용을 자동으로 수집해 LangSmith로 전송하는 트레이싱 구성 방법을 다룹니다.
Claude Code를 활용해 개발하거나 실험을 진행할 때, 대화 이력과 도구 호출, 응답 결과를 체계적으로 관측하는 것은 디버깅과 품질 개선에 매우 중요합니다. 본문에서는 Claude Code의 Stop Hook 기능을 활용해 대화 트랜스크립트를 LangSmith의 트레이스로 변환·전송하는 전체 과정을 단계별로 정리합니다.

반응형

---

Claude Code 트레이싱 개요

Claude Code는 CLI 환경에서 AI와 상호작용하며 개발을 진행할 수 있는 도구입니다.
LangSmith는 이러한 AI 상호작용을 Run / Trace 단위로 수집하고 시각화할 수 있는 관측성 플랫폼입니다.

이번 구성의 핵심 목적은 다음과 같습니다.

• Claude Code 대화 내용을 자동으로 수집
• 사용자 메시지, 도구 호출, 모델 응답을 LangSmith로 전송
• 하나의 세션을 Thread 단위로 묶어 분석 가능하게 구성

---

전체 동작 구조

Claude Code 트레이싱은 다음과 같은 흐름으로 동작합니다.

1. Claude Code가 응답을 생성할 때마다 글로벌 Stop Hook이 실행됨
2. Hook 스크립트가 Claude Code가 생성한 대화 트랜스크립트를 읽음
3. 트랜스크립트를 LangSmith Run 형식으로 변환
4. LangSmith 프로젝트로 Trace 전송

이 방식은 옵트인(opt-in) 구조로, 프로젝트 단위 또는 전역 설정을 통해 활성화할 수 있습니다.

---

사전 준비 사항

설정을 시작하기 전에 다음 요소들이 준비되어 있어야 합니다.

• Claude Code CLI 설치 완료
• LangSmith API Key 보유
• JSON 처리를 위한 커맨드라인 도구 jq 설치
• macOS 환경 (현재 가이드는 macOS만 지원)

---

1. Stop Hook 스크립트 생성

Claude Code가 응답을 마칠 때마다 실행될 스크립트를 생성합니다.

파일 위치

~/.claude/hooks/stop_hook.sh

이 스크립트는 Claude Code가 생성한 대화 트랜스크립트를 처리해 LangSmith로 전송하는 역할을 합니다.
가이드에서 제공된 stop_hook.sh 내용을 그대로 파일에 저장합니다.

실행 권한 부여

chmod +x ~/.claude/hooks/stop_hook.sh

이 과정이 누락되면 Hook 실행 시 권한 오류가 발생합니다.

---

2. 글로벌 Stop Hook 설정

다음으로 Claude Code의 전역 설정 파일에 Stop Hook을 등록합니다.

설정 파일 위치

~/.claude/settings.json

설정 내용

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/stop_hook.sh"
          }
        ]
      }
    ]
  }
}

이 설정을 통해 모든 Claude Code 세션 종료 시 stop_hook.sh가 자동 실행됩니다.

---

3. 프로젝트 단위 트레이싱 활성화

트레이싱은 프로젝트별로 활성화됩니다.
Claude Code 프로젝트 디렉토리 내 설정 파일을 수정합니다.

설정 파일

.claude/settings.local.json

필수 환경 변수

{
  "env": {
    "TRACE_TO_LANGSMITH": "true",
    "CC_LANGSMITH_API_KEY": "lsv2_pt_...",
    "CC_LANGSMITH_PROJECT": "project-name",
    "CC_LANGSMITH_DEBUG": "true"
  }
}

주요 변수 설명

• TRACE_TO_LANGSMITH: 해당 프로젝트에서 트레이싱 활성화 여부
• CC_LANGSMITH_API_KEY: LangSmith API 키
• CC_LANGSMITH_PROJECT: Trace를 저장할 LangSmith 프로젝트 이름
• CC_LANGSMITH_DEBUG: 상세 디버그 로그 활성화 (선택)

---

전역 설정으로 트레이싱 활성화하는 방법

모든 Claude Code 세션에서 트레이싱을 사용하고 싶다면, 위 환경 변수 설정을 전역 settings.json에 추가해도 됩니다.
이 방식은 여러 프로젝트를 동시에 관리하는 환경에서 유용합니다.

---

4. 설정 검증 방법

설정이 정상적으로 동작하는지 확인하는 방법은 다음과 같습니다.

1. 트레이싱이 활성화된 프로젝트에서 Claude Code 실행
2. Claude Code가 응답을 생성
3. LangSmith 대시보드에서 Trace 확인

LangSmith에서는 다음과 같은 형태로 데이터가 표시됩니다.

• 각 메시지가 개별 Trace로 기록
• 동일한 Claude Code 세션은 하나의 thread_id로 묶임
• Threads 탭에서 전체 대화 흐름 확인 가능

---

문제 해결 가이드

LangSmith에 Trace가 나타나지 않을 경우

1. Hook 실행 로그 확인

tail -f ~/.claude/state/hook.log

1. 환경 변수 설정 확인

• TRACE_TO_LANGSMITH가 true인지 확인
• API Key가 lsv2_pt_로 시작하는지 확인
• LangSmith 프로젝트가 실제로 존재하는지 확인

1. 디버그 모드 활성화

{
  "env": {
    "CC_LANGSMITH_DEBUG": "true"
  }
}

---

권한 오류 발생 시

chmod +x ~/.claude/hooks/stop_hook.sh

스크립트 실행 권한이 없는 경우 가장 흔히 발생하는 문제입니다.

---

필수 명령어 누락 오류

다음 명령어가 설치되어 있는지 확인합니다.

which jq curl uuidgen

jq가 없는 경우:

• macOS: brew install jq
• Ubuntu/Debian: sudo apt-get install jq

---

로그 파일 관리

디버그 모드 활성화 시 로그 파일 크기가 빠르게 증가할 수 있습니다.

ls -lh ~/.claude/state/hook.log

로그 초기화:

> ~/.claude/state/hook.log

---

728x90

이번 구성은 Claude Code CLI의 대화 흐름을 LangSmith로 자동 수집해 관측 가능하게 만드는 실전 트레이싱 예제입니다.
Hook 기반 구조를 활용함으로써 코드 수정 없이도 AI 상호작용을 체계적으로 기록할 수 있으며, 세션 단위 분석과 디버깅, 프롬프트 개선에 큰 도움을 줍니다.

특히 AI 기반 개발 워크플로우가 복잡해질수록, 이러한 관측성(Observability) 체계는 선택이 아닌 필수가 될 가능성이 큽니다.
Claude Code와 LangSmith의 연동은 향후 AI 개발 환경에서 표준적인 디버깅 패턴으로 자리 잡을 수 있는 구성이라 할 수 있습니다.

300x250

https://docs.langchain.com/langsmith/trace-claude-code

Trace Claude Code - Docs by LangChain