코딩 에이전트 관측과 기록: 무엇을 남기고 어떻게 되짚는지

🤔 사흘 전에 합친 변경이 왜 들어갔는지 아무도 모를 때

여러 에이전트를 돌리다 보면 며칠 뒤에 이상한 코드를 발견하는 일이 생깁니다. 누가 왜 이렇게 고쳤는지 찾으려고 보면, 커밋 메시지는 "수정"이 전부이고 어느 세션에서 만들었는지도 알 수 없습니다. 대화 기록이 어딘가 남아 있을 것 같지만 어느 파일인지 모르고, 찾더라도 수천 줄 속에서 해당 대목을 찾기 어렵습니다.

에이전트가 사람보다 빠르게 많은 변경을 만들수록 기록이 없으면 되짚을 방법이 사라집니다. 이 편에서는 도구가 자동으로 남기는 기록과 그 한계, 사람이 따로 남겨야 할 기록, 팀 단위로 기록을 모으는 방법을 정리합니다. 도구 설정은 클로드 코드를 기준으로 2026년 9월 28일 공식 문서에서 확인했습니다.

🔑 코딩 에이전트 관측의 정의

코딩 에이전트 관측은 에이전트가 무엇을 읽고 실행하고 바꿨는지, 얼마를 썼는지를 기록으로 남겨 나중에 되짚을 수 있게 하는 운영 방식입니다.

관측(observability)은 원래 시스템 운영에서 겉으로 드러난 기록만 보고 안에서 무슨 일이 있었는지 알아낼 수 있는 정도를 가리키는 말입니다. 비행기의 블랙박스를 떠올리면 가깝습니다. 사고가 난 뒤에야 쓸모가 드러나지만, 그때 가서 설치할 수는 없습니다.

🗃️ 도구가 자동으로 남기는 기록

클로드 코드가 따로 설정하지 않아도 남기는 기록은 두 가지입니다.

대화 기록: 세션마다 대화 전체를 JSONL 파일로 저장합니다. JSONL은 한 줄에 기록 하나를 적는 텍스트 형식입니다. 공식 문서 기준 위치는 ~/.claude/projects/<프로젝트>/<세션 ID>.jsonl이고, 세션을 다시 이어 가기 위해 기본 30일 동안 보관하며 cleanupPeriodDays 설정으로 기간을 바꿉니다. 문서는 이 기록이 평문으로 저장된다고 밝히고 있어서, 비밀 값이 대화에 오갔다면 이 파일에도 그대로 남습니다.

체크포인트: 프롬프트를 보낼 때마다 그 시점의 파일 상태를 저장합니다. /rewind나 입력창이 비어 있을 때 Esc를 두 번 누르면 코드와 대화를 함께 되돌리거나 둘 중 하나만 되돌릴 수 있습니다. 세션마다 최근 100개 체크포인트의 파일 스냅숏을 보관합니다.

체크포인트에는 분명한 한계가 있습니다.

문서도 체크포인트는 세션 안의 빠른 복구용이고 오래 남길 이력은 버전 관리를 계속 쓰라고 안내합니다. 여러 에이전트를 돌린다면 작업 하나가 끝날 때마다 커밋을 남기는 것이 가장 확실한 되돌리기 수단입니다.

📝 사람이 따로 남겨야 할 작업 기록

대화 기록에는 에이전트가 한 일이 모두 있지만, 무엇을 맡겼고 어떤 증거로 합쳤는지는 흩어져 있어서 찾기 어렵습니다. 그래서 작업마다 한 줄짜리 기록을 따로 남깁니다.

긴 작업이라면 진행 기록 파일을 저장소 안에 두는 방식이 쓸모 있습니다. 앤트로픽은 여러 세션에 걸친 긴 작업에서 에이전트들이 한 일을 기록하는 진행 파일과 깃 기록을 새 세션이 먼저 읽고 시작하게 했습니다. 기록이 대화가 아니라 파일에 있어야 세션이 바뀌어도 이어 갈 수 있습니다.

🔁 기록을 되짚는 방법

기록은 되짚을 수 있어야 쓸모가 생깁니다. 클로드 코드가 제공하는 방법은 이렇습니다.

• 세션 이름 붙이기와 다시 열기: /rename으로 세션에 이름을 붙이고 /resume으로 이름이나 ID를 골라 다시 엽니다
• 대화 내보내기: /export로 지금 대화를 평문으로 저장합니다. 검수자에게 넘기거나 기록에 붙일 때 씁니다
• 최근 세션 보고서: /insights는 최근 세션들을 분석한 HTML 보고서를 만듭니다
• 되돌리기: /rewind로 앞 시점의 코드나 대화로 돌아갑니다

실패를 조사할 때는 결과보다 과정을 봐야 합니다. 앤트로픽은 에이전트 평가 글에서 결과만 보지 말고 기록을 정기적으로 읽으라고 권합니다. 테스트를 고쳐 통과시킨 보상 해킹처럼 결과만으로는 정상과 구분되지 않는 실패가 기록에서 드러나기 때문입니다.

📡 자동화와 팀 단위로 기록을 모으는 방법

사람이 매번 적는 기록은 빠지기 쉽습니다. 반복되는 것은 도구에 맡깁니다.

비대화형 실행의 출력: claude -p에 --output-format json을 붙이면 결과와 세션 ID, 추정 비용이 모델별로 담긴 JSON이 나옵니다. stream-json은 진행 과정을 한 줄씩 내보내고 마지막 줄에 결과와 비용을 담습니다. 거부된 권한 요청도 목록으로 남습니다. 자동화 스크립트가 이 출력을 그대로 파일에 쌓으면 작업 기록이 저절로 만들어집니다.

훅: 정해진 시점에 명령을 돌리는 훅으로 기록을 남깁니다. 도구 호출이 끝난 뒤, 실패한 뒤, 응답이 끝났을 때, 서브에이전트가 끝났을 때, 요약 직전, 세션이 끝날 때가 모두 훅을 걸 수 있는 시점이고, 훅에는 대화 기록 파일의 경로도 함께 전달됩니다.

원격 측정: CLAUDE_CODE_ENABLE_TELEMETRY=1로 오픈텔레메트리 수집을 켜면 팀 전체의 기록을 한곳에 모읍니다. 오픈텔레메트리는 여러 프로그램의 기록을 같은 형식으로 모으는 공개 표준입니다.

기본값에서 기록되지 않는 것도 있습니다. 프롬프트 내용은 OTEL_LOG_USER_PROMPTS를 켜야 기록되고, 셸 명령이나 도구 인자 같은 세부는 OTEL_LOG_TOOL_DETAILS를 켜야 기록됩니다. 문서는 비용 지표가 근사값이며 공식 청구는 API 제공자의 콘솔을 보라고 적었습니다.

🔐 기록을 다룰 때의 주의

• 기록에도 비밀이 남습니다: 대화 기록은 평문 파일이라 대화에 붙여 넣은 키나 고객 정보가 그대로 저장됩니다. 비밀 값은 대화에 넣지 않고 환경 변수로 넘깁니다
• 프롬프트 수집은 팀과 합의합니다: 원격 측정에서 프롬프트 기록을 켜면 누가 무엇을 물었는지가 모입니다. 켜기 전에 무엇을 모으는지 팀에 알립니다
• 보관 기간을 정합니다: 기본 30일이 지나면 대화 기록이 지워집니다. 오래 남겨야 할 것은 작업 기록과 커밋으로 옮겨 둡니다

⚠️ 기록을 운영할 때 자주 하는 실수

• 체크포인트를 버전 관리로 착각합니다: 셸 명령과 서브에이전트의 변경은 되돌리지 못합니다. 작업마다 커밋합니다
• 세션에 이름을 붙이지 않습니다: 여러 세션을 오가면 어느 대화가 어느 작업이었는지 찾기 어렵습니다
• 결과만 기록합니다: 통과 여부만 남기면 어떤 증거로 합쳤는지, 무엇을 확인하지 못했는지를 되짚을 수 없습니다

❓ 자주 묻는 질문

대화 기록 파일을 직접 열어 봐도 되나요?

됩니다. 한 줄에 기록 하나가 담긴 텍스트 파일이라 편집기나 검색 명령으로 열 수 있습니다. 다만 양이 많아 통째로 읽기는 어려워서, 세션 이름과 작업 기록의 시각으로 먼저 범위를 좁히고 찾는 편이 빠릅니다.

코덱스나 다른 도구에도 같은 기록이 있나요?

도구마다 형식과 위치가 다릅니다. 이 편의 경로와 명령은 클로드 코드 기준이고, 다른 도구를 함께 쓴다면 도구마다 대화 기록 위치를 확인해 작업 기록에 함께 적어 둡니다. 도구가 달라도 작업 기록과 깃 커밋은 같은 형식으로 남길 수 있어서, 되짚는 기준은 이 두 가지로 두는 편이 낫습니다.

기록을 남기는 데 시간이 너무 들지 않나요?

사람이 매번 적으면 부담이 됩니다. 비대화형 실행의 JSON 출력과 훅, 커밋 메시지 규칙으로 대부분을 자동으로 남기고, 사람은 실패 유형과 판단 이유처럼 기계가 적을 수 없는 한두 줄만 더하는 편이 오래 유지됩니다.

📋 3줄 요약

1. 클로드 코드는 대화 기록을 ~/.claude/projects 아래에 JSONL 파일로 기본 30일 보관하고 프롬프트마다 체크포인트를 만들지만, 셸 명령으로 바뀐 파일은 체크포인트가 추적하지 않습니다.

2. 도구의 자동 기록만으로는 무엇을 맡겼고 어떤 증거로 합쳤는지가 남지 않으므로 작업마다 명세와 바꾼 파일, 완료 증거 출력, 비용, 실패 유형을 따로 적어 둡니다.

3. 팀 단위로 모을 때는 오픈텔레메트리로 세션 수와 토큰, 비용 추정치를 수집할 수 있고 프롬프트 내용과 도구 세부는 기본값에서 기록되지 않습니다.

📚 참고 자료

• 클로드 코드 문서, Sessions: https://code.claude.com/docs/en/sessions
• 클로드 코드 문서, Data usage: https://code.claude.com/docs/en/data-usage
• 클로드 코드 문서, Checkpointing: https://code.claude.com/docs/en/checkpointing
• 클로드 코드 문서, Monitoring usage: https://code.claude.com/docs/en/monitoring-usage
• 클로드 코드 문서, Headless mode: https://code.claude.com/docs/en/headless
• 클로드 코드 문서, Hooks reference: https://code.claude.com/docs/en/hooks
• 앤트로픽, Effective harnesses for long-running agents: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents