Claude Code 대화 기록을 LangSmith로 자동 추적하는 방법 - CLI 기반 LLM 개발 환경에서 트레이싱을 설정하는 실전 가이드

Claude Code CLI를 사용해 개발을 하다 보면,
“이 대화 흐름이 어떻게 이어졌는지”,
“어떤 도구 호출이 있었는지”,
“응답이 왜 이렇게 나왔는지”를 다시 보고 싶을 때가 많습니다.

이 글에서는 Claude Code CLI에서 발생하는 모든 대화를 LangSmith로 자동 전송하여 추적(Tracing)하는 방법을 정리합니다.
Claude Code의 Hook 기능을 활용해 응답 시점마다 대화 기록을 수집하고, 이를 LangSmith 프로젝트로 전송하는 전체 설정 과정과 동작 원리를 설명합니다.

반응형

---

Claude Code와 LangSmith 트레이싱 개요

Claude Code란?

Claude Code는 CLI 환경에서 Claude 모델과 대화하며 코드를 작성하고 실험할 수 있는 도구입니다.
다만 기본적으로는 대화 기록을 외부로 자동 전송하거나 시각화하는 기능은 제공하지 않습니다.

LangSmith란?

LangSmith는 LLM 애플리케이션의 실행 흐름을 Trace 단위로 시각화하고 분석할 수 있는 플랫폼입니다.
메시지, 도구 호출, 응답을 하나의 실행 단위(run)로 묶어 디버깅과 품질 개선에 활용할 수 있습니다.

이 두 도구를 연결하면, Claude Code에서 발생하는 모든 대화 흐름을 LangSmith에서 추적할 수 있습니다.

---

전체 동작 구조 (How it works)

이 설정은 Claude Code의 Global Stop Hook을 기반으로 동작합니다.

핵심 흐름

1. Claude Code가 응답을 완료할 때마다 Stop Hook 실행
2. Hook 스크립트가 Claude Code가 생성한 대화 transcript를 읽음
3. transcript 내 메시지, 도구 호출, 응답을 LangSmith Run으로 변환
4. 변환된 Trace를 지정된 LangSmith 프로젝트로 전송

⚠️ 참고
Claude Code의 transcript에는 System Prompt가 포함되지 않기 때문에, LangSmith Trace에도 System Prompt는 기록되지 않습니다.

---

사전 준비 사항 (Prerequisites)

설정을 시작하기 전에 아래 항목이 준비되어 있어야 합니다.

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

---

1단계: Stop Hook 스크립트 생성

Claude Code 응답 시마다 실행될 Hook 스크립트를 생성합니다.

파일 위치

~/.claude/hooks/stop_hook.sh

이 스크립트는 Claude Code가 생성한 대화 transcript를 처리하고, LangSmith로 Trace를 전송하는 역할을 합니다.

실행 권한 부여

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

이 단계가 누락되면 Hook이 실행되지 않습니다.

---

2단계: 글로벌 Hook 설정

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

설정 파일 위치

~/.claude/settings.json

설정 내용

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

이 설정을 통해 모든 Claude Code CLI 응답 이후 stop_hook.sh가 실행됩니다.

---

3단계: 프로젝트별 트레이싱 활성화

Tracing은 프로젝트 단위로 opt-in 방식입니다.

프로젝트 설정 파일

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 Key
• CC_LANGSMITH_PROJECT: Trace가 전송될 LangSmith 프로젝트 이름
• CC_LANGSMITH_DEBUG: 상세 로그 출력 (선택 사항)

💡 모든 Claude Code 세션에 적용하고 싶다면, 이 설정을 전역 settings.json에 추가할 수도 있습니다.

---

4단계: 정상 동작 확인

설정이 완료되면 Claude Code 세션을 시작합니다.

LangSmith에서 확인 가능한 내용

• Claude Code에 보낸 각 메시지가 Trace로 기록
• 하나의 세션에서 발생한 모든 대화는 동일한 thread_id로 그룹화
• LangSmith 프로젝트의 Threads 탭에서 대화 흐름 확인 가능

---

트러블슈팅 가이드

Trace가 보이지 않는 경우

Hook 실행 여부 확인

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

Claude 응답 이후 로그가 찍혀야 정상입니다.

환경 변수 점검

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

디버그 모드 활성화

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

---

권한 오류 발생 시

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

---

필수 명령어 누락 시

which jq curl uuidgen

jq가 없다면:

brew install jq

---

로그 파일 관리

Hook 로그는 아래 경로에 누적됩니다.

~/.claude/state/hook.log

로그 초기화

> ~/.claude/state/hook.log

---

728x90

이번 설정을 통해 얻을 수 있는 핵심 가치는 명확합니다.

• Claude Code CLI의 모든 대화 흐름을 자동으로 추적
• 메시지, 도구 호출, 응답을 한눈에 파악
• 세션 단위 분석을 통한 디버깅과 품질 개선
• LLM 기반 개발 환경에서 재현성과 관찰 가능성 확보

특히 CLI 환경에서 작업하는 개발자라면,
이 설정은 Claude Code를 단순한 대화 도구가 아닌 관찰 가능한 LLM 개발 워크플로우로 확장시켜 줍니다.

LangSmith와 Claude Code를 함께 사용하는 개발자라면,
이 트레이싱 설정은 선택이 아니라 필수에 가까운 기본 세팅이라고 볼 수 있습니다.

300x250

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

Trace Claude Code applications - Docs by LangChain