AI 에이전트 관찰 가능성: 에이전트가 무엇을 했는지 파악하고 무엇을 기록할지

AI 에이전트 관찰 가능성이란 무엇인가

AI 에이전트의 관찰 가능성은 기억이나 에이전트의 말이 아니라 산출물을 근거로 세 가지 질문에 답할 수 있는 능력입니다. 에이전트가 무엇을 했는가, 왜 그렇게 했는가, 결과가 옳다는 것을 무엇으로 증명하는가입니다. 20분 작업 뒤 에이전트가 "완료했습니다. 다만 두 테스트가 실패하는데 타이밍 문제일 수 있습니다"라고 말하고, "어떤 경로가 바뀌었나요?"라는 질문에 "코드를 보여 주셔야 합니다"라고 답한다면, 관찰 가능성은 없는 것입니다. 에이전트가 멍청해서가 아니라, 제시할 증거가 없기 때문입니다.

문제는 구조적입니다. 같은 에이전트가 일주일 동안 열 번 "완료"라고 정직하게 말할 수 있는데, 그때마다 그 말의 의미가 다릅니다. 어떤 때는 모든 테스트를 돌렸고, 어떤 때는 하나만 돌렸으며, 어떤 때는 아무것도 돌리지 않았습니다. 프로젝트가 오래될수록 다음 세션은 시작부터 발굴 작업이 되어 더 비싸집니다.

두 개의 층: 실행과 프로세스

관찰 가능성은 로그와 혼동되기 쉽지만, 로그는 절반에 불과합니다.

실행 층만 있으면 무엇이 실패했는지는 보이지만 무엇을 목표로 했는지는 알 수 없습니다. 프로세스 층만 있으면 무엇을 원했는지는 알지만 왜 실패했는지는 보이지 않습니다. 둘 다 필요합니다.

에이전트가 스스로 하지 못하는 이유

"로그를 더 잘 남겨"라고 말하는 것만으로는 효과가 없습니다. 세 가지 이유가 있습니다.

• 자기가 모르는 것은 기록하지 못합니다. 중요성을 짐작하지 못한 신호는 에이전트가 기록하지 않습니다.
• 형식이 세션마다 달라집니다. 어떤 세션에서는 상세하게, 다른 세션에서는 한 줄로 씁니다. 그러면 세션끼리 비교하거나 집계를 낼 수 없습니다.
• 프로세스는 로그로 닫히지 않습니다. "왜 이렇게 했나"에 대한 답은 명령 출력이 아니라 작업 이전에 만든 문서에 있습니다.

그래서 관찰 가능성은 하네스, 즉 에이전트의 작업 환경에 설계해 넣습니다. 템플릿, 훅, 스크립트, 보고서 형식을 고정하는 것입니다.

무엇을 기록할지: 최소 세트

좋은 로그는 모든 것을 받아 적은 속기록이 아닙니다. 작업의 흐름을 되짚고 통계를 낼 수 있는 사실들의 모음입니다.

• 식별자: 세션 ID, 작업이나 기능의 ID, 에이전트 모델.
• 부작용이 있는 행동: 어떤 명령을 실행했고, 어떤 파일을 바꿨는지. 파일 읽기는 보통 기록하지 않아도 됩니다.
• 검증 결과: 어떤 검증 명령을, 종료 코드는 몇이었고, 테스트가 몇 개 통과하고 실패했는지.
• 재시도: 한 단계에 몇 번 시도했고, 시도끼리 무엇이 달랐는지.
• 비용: 도구가 제공한다면 토큰 수와 소요 시간.
• 결과: 작업이 수락되었는지, 거절되었는지, 중단되었는지, 그리고 그 이유.

기록하면 안 되는 것도 있습니다. 비밀 값, 액세스 토큰, 명령 출력에 섞인 개인정보입니다. 로그는 공유되거나 다시 모델의 컨텍스트로 들어갈 수 있습니다.

Claude Code 훅으로 행동 로그 남기기

Claude Code에서 행동 로그는 훅으로 남기는 것이 편합니다. 훅은 모델이 아니라 도구 자체가 실행하므로 항상 작동합니다. 훅은 stdin으로 세션 ID, 도구 이름, 매개변수 등을 담은 JSON을 받습니다. 다음은 Bash, Edit, Write 호출이 끝날 때마다 로그 파일에 한 줄을 추가하는 설정 예시입니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/log-action.sh" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/log-action.sh — 행동 한 건당 JSON 한 줄
mkdir -p .agent/logs
jq -c '{ts: (now | todate), session: .session_id, tool: .tool_name,
        cmd: .tool_input.command, file: .tool_input.file_path}' \
  >> .agent/logs/actions.jsonl || true

JSONL 형식(한 줄에 JSON 레코드 하나)은 jq로 걸러내기 쉽고, 어떤 분석 시스템에든 바로 넣을 수 있습니다. 또한 Claude Code는 전체 세션 기록을 ~/.claude/projects/ 디렉터리에 로컬로 저장합니다. 추론과 출력 전체를 보고 싶을 때는 이 기록을 열어 볼 수 있지만, 통계를 내기에는 직접 만든 간결한 로그가 더 편합니다.

트레이스: 세션당 트레이스, 작업당 span

에이전트가 많거나 일정에 따라 돌아갈 때는 텍스트 로그만으로는 부족하고 집계가 필요합니다. 이때는 일반적인 분산 트레이싱 도구와 OpenTelemetry 표준이 도움이 됩니다.

• 트레이스 — 에이전트의 세션 하나.
• Span — 세션 안의 작업 하나.
• 하위 span — 빌드, 테스트, e2e 같은 검증 단계.

span마다 최소한 기능 ID와 세션 ID, 모델, 검증 결과, 토큰 수, 재시도 횟수를 붙이세요. 이런 데이터는 Jaeger, Grafana Tempo, Honeycomb에서 읽을 수 있고, 한 세션만 봐서는 보이지 않는 질문에 답합니다. 어떤 유형의 작업이 재시도를 많이 필요로 하나, 에이전트가 토큰을 가장 많이 쓰는 곳은 어디인가, 하네스를 어떻게 바꾼 뒤 수락률이 떨어졌나 같은 것들입니다. Claude Code에는 OpenTelemetry를 통한 지표와 이벤트 내보내기 기능이 내장되어 있습니다. 환경 변수로 켜며, 자세한 내용은 도구의 문서에 있습니다.

커밋을 기록으로 쓰기

가장 저렴하고 믿을 만한 기록은 이미 가지고 있는 git입니다. 다만 읽기 쉽게 만들어야 합니다.

1. 커밋 하나에 작업 하나. 그러면 git log가 완료된 작업 목록과 일치하고, 작업을 되돌리는 것도 git revert 한 번이면 됩니다.
2. 메시지에 무엇을 했고 어떻게 검증했는지. "fix"가 아니라 "무엇을 왜 바꿨고, 어떤 명령으로 확인했는지"를 적으세요.
3. 검증이 초록일 때만 커밋. 그러면 히스토리의 모든 지점이 작동하는 상태가 되고, git bisect로 원인을 찾을 수 있습니다.

fix(payments): 할인 반올림을 코펙 단위로

할인을 float로 계산해서 999.99에서 1코펙이 사라졌습니다.
계산을 코펙 단위 int로 옮겼습니다.
검증: make test (142 passed), make e2e checkout — 통과.
범위 밖: 보고서의 반올림은 BACKLOG.md에 기록.

에이전트 보고서: 인상 대신 증거

에이전트의 마지막 메시지도 형식이 고정되어 있다면 관찰 가능성의 산출물이 됩니다. 템플릿을 AGENTS.md나 CLAUDE.md에 적어 두세요.

## 작업 종료 보고
- 무엇을 했나: 변경 목록(파일 — 내용)
- 어떻게 검증했나: 정확한 명령과 그 결과
- 검증하지 못한 것과 그 이유
- 작업 계약에서 벗어난 부분
- 사람에게 드리는 열린 질문

가장 중요한 규칙은 모든 주장이 증거를 가리켜야 한다는 것입니다. 파일과 줄, 테스트 출력, 로그 항목처럼요. "괜찮아 보입니다"나 "문제없을 것 같습니다"는 보고서로 인정되지 않습니다. "검증하지 못한 것" 항목은 특히 가치가 있습니다. 확신의 경계를 정직하게 보여 주기 때문입니다.

코드 전의 계약과 작업 후의 루브릭

프로세스 층은 작업 전에 시작됩니다. 짧은 작업 계약(sprint contract)은 범위, 수용 기준, "범위 밖" 항목, 사람이 결정할 열린 질문을 고정합니다. "범위 밖" 항목은 결과에 대한 논쟁의 절반을 미리 막아 줍니다.

작업이 끝나면 결과는 인상이 아니라 루브릭으로 평가합니다. 그렇지 않으면 숙련된 리뷰어 두 명이 서로 다른 판정을 내리고, 평가는 복권이 됩니다.

각 차원은 A/B/C/D로 평가하고, 근거 링크가 없는 평가는 무효입니다. 간단한 결정 규칙은 이렇습니다. D가 하나이거나 C가 둘이면, 무엇을 고쳐야 하는지 목록과 함께 거절합니다. 같은 루브릭을 별도의 검증 에이전트가 적용할 수도 있습니다.

에이전트가 세션 동안 무엇을 했는지 분석하는 법

보고서가 없거나 보고서를 믿을 수 없다면, 다음 순서로 산출물을 살펴보세요.

1. 작업 트리 상태: git status로 커밋되지 않은 것과 쓰레기 파일이 있는지 봅니다.
2. 히스토리: 세션 시작 이후의 git log --stat로 어떤 커밋과 파일이 있는지 봅니다.
3. 변경 규모: git diff --stat main...HEAD로 전체를 보고, 중요한 파일은 전체 diff를 봅니다.
4. 행동 로그: 어떤 명령이 실행됐고, 검증이 무엇을 돌려줬는지 봅니다.
5. 재검증: 빌드와 테스트를 직접 실행합니다. 보고서가 아니라 명령의 출력을 믿으세요.

# 마지막 세션에서 에이전트가 실행한 명령
jq -r 'select(.tool=="Bash") | .cmd' .agent/logs/actions.jsonl | tail -n 30
# 가장 자주 수정된 파일
jq -r '.file // empty' .agent/logs/actions.jsonl | sort | uniq -c | sort -rn | head

흔한 실수

• 모든 것을 기록하기. 기가바이트 단위의 속기록은 아무도 읽지 않습니다. 부작용이 있는 행동과 검증 결과만 기록하세요.
• 자유로운 형식. 로그 형식을 에이전트가 정하면 집계가 나오지 않습니다. 형식은 하네스가 정해야 합니다.
• 명령 출력 없이 보고서를 믿기. "테스트가 초록입니다"라는 말에 출력이 없다면 그것은 의견입니다.
• 맹목적인 재시도. 실패 원인 없이 에이전트는 엉뚱한 곳을 고칩니다. 먼저 로그를 근거로 진단을 요구하고, 그다음 수정하게 하세요.
• "나중에 정리하지". 디버그 파일과 커밋되지 않은 변경은 다음 세션을 혼란스럽게 합니다. 임시 것과 의도된 것을 구분할 수 없게 되기 때문입니다.

요약

AI 에이전트의 관찰 가능성은 두 개의 층으로 이루어집니다. 실행 층은 훅으로 남기는 행동 로그, 트레이스, 커밋에 적힌 검증 기록입니다. 프로세스 층은 코드 전에 쓰는 작업 계약, 루브릭, 증거가 붙은 보고서입니다. 이 둘이 갖춰지면 "완료"라는 말은 세션마다 같은 의미를 가지고, 작업 분석은 몇 분이면 끝납니다. 이 주제는 harness engineering 과정에서 실제 결제 백엔드 프로젝트를 예로 들어 실습합니다.