랭스미스에서 클로드 코드 트레이싱하기: 플러그인 설치와 설정 파일 가이드

핵심 메시지

• 클로드 코드로 에이전트를 만들다 보면 예상치 못한 동작의 원인을 추적하기 어려운데, 랭스미스 트레이싱으로 모든 메시지·툴 호출·서브에이전트 실행을 들여다볼 수 있다.
• 설정에는 클로드 코드 CLI, Node.js, 랭스미스 API 키 세 가지만 있으면 되고, 전체 과정은 몇 분이면 끝난다.
• 마켓플레이스 플러그인을 추가하고 트레이싱 플러그인을 설치한 뒤 플러그인을 리로드하면 설치가 완료된다.
• 프로젝트 폴더에 .claude/settings.local.json 파일을 만들어 traceToLangSmith, API 키, 프로젝트명을 지정하면 트레이스 전송 위치가 정해진다.
• 랭스미스에서는 메시지마다 개별 트레이스가 생성되고, 스레드 탭에서 같은 세션의 모든 대화가 하나로 묶여 전체 흐름을 따라갈 수 있다.

쉽게 이해하기

랭체인 제품팀의 에이미가 소개하는 이 튜토리얼은 클로드 코드(Claude Code) 애플리케이션을 랭스미스(LangSmith)에서 추적하는 방법을 다룬다. 클로드 코드로 에이전트를 만들다 보면 에이전트가 예상 밖의 동작을 했는데 어떤 툴 호출이 이를 유발했는지, 서브에이전트가 실제로 무엇을 반환했는지 알 수 없어 막막했던 경험이 있기 마련이다. 트레이싱은 이런 순간에 세션 내부를 들여다보게 해 준다.

시작 전 준비물은 세 가지다. 클로드 코드 CLI 설치, Node.js 설치, 그리고 랭스미스 API 키다. API 키가 없다면 랭스미스 설정에서 발급받을 수 있다. 이 준비만 되면 곧바로 진행할 수 있다.

설치는 클로드 코드에서 세 개의 명령으로 이뤄진다. 먼저 마켓플레이스 플러그인을 추가하고, 트레이싱 플러그인을 설치한 뒤, 플러그인을 리로드해 반영한다. 이후 업그레이드가 필요하면 마켓플레이스 업데이트 명령과 플러그인 리로드 명령을 다시 실행하면 된다.

다음으로 트레이스를 어디로 보낼지 지정한다. 가장 깔끔한 방법은 프로젝트 디렉터리에 .claude/settings.local.json 설정 파일을 만드는 것이다. traceToLangSmith 값으로 해당 프로젝트의 트레이싱을 켜고 끌 수 있으며, API 키 항목에는 발급받은 키를, 프로젝트명 항목에는 랭스미스에서 트레이스가 표시될 프로젝트 이름을 넣는다.

설정을 마치면 클로드 코드를 평소처럼 사용하면 된다. 작업을 시키고 응답이 끝난 뒤 랭스미스로 넘어가면, 보낸 메시지마다 하나의 트레이스가 생기고 그 안에서 사용자 메시지, 클로드가 호출한 모든 툴, 토큰 사용량, 서브에이전트 실행, 최종 응답까지 전체 그림을 볼 수 있다. 스레드 탭으로 가면 같은 세션의 모든 대화가 하나의 스레드로 묶여, 단일 메시지가 아니라 대화 전체 흐름을 따라갈 수 있다.

주요 인사이트

• 에이전트 디버깅의 핵심은 '결과'가 아니라 '과정'을 보는 것이다. 어떤 툴 호출과 서브에이전트 반환이 특정 동작을 유발했는지 보이면 원인 추적이 쉬워진다.
• 트레이싱 활성화는 설정 파일의 불리언 값 하나로 켜고 끌 수 있어, 필요할 때만 관찰하도록 유연하게 조절할 수 있다.
• 메시지 단위 트레이스와 세션 단위 스레드가 함께 제공돼, 개별 요청과 대화 전체라는 두 층위를 오가며 분석할 수 있다.
• 토큰 사용량까지 트레이스에 함께 기록되므로, 동작 검증뿐 아니라 비용 관찰에도 활용할 수 있다.
• 발표자는 같은 설정을 코덱스(Codex)와 커서(Cursor)용으로도 촬영할 예정이라고 밝혀, 동일한 관찰 방식이 다른 코딩 에이전트로도 확장될 수 있음을 시사한다.

자주 묻는 질문

관련 AI 소식