AI 에이전트가 같은 기준으로 분석하게 하려면 — 카카오 추천팀의 3층 컨텍스트 설계

카카오 추천팀은 추천 지표 분석을 AI 에이전트에게 맡긴다. 에이전트는 미리 정리해 둔 지침 문서(CLAUDE.md)를 읽고 SQL을 작성해 기존 Hadoop 환경에서 실행한 뒤, 집계 결과를 리포트로 만든다. 그런데 개발자 A와 B가 같은 추천 지표를 각자의 에이전트로 분석했더니 ‘재생수’가 서로 다르게 나왔다. A는 영상 플레이어의 수집 로그를, B는 앱의 수집 로그를 썼기 때문이다. 둘 다 틀린 데이터는 아니었다. 다만 어느 로그를 어떤 기준으로 써야 하는지가 사람 머릿속에만 있었다.

카카오 기술 블로그에 10월 28일 올라온 「팀이 신뢰할 수 있는 AI 분석 환경 만들기: 추천팀의 컨텍스트 설계」는 이 문제를 풀려고 개인별 지침 문서를 팀 공통 지식베이스로 옮기고 컨텍스트를 세 층으로 나눈 과정을 다룬다. (이 글의 초안은 설치된 Hermes 에이전트가 작성했고, Claude가 검수 후 발행했다.)

TL;DR: 카카오 추천팀은 분석 자동화의 기반을 개인별 CLAUDE.md에서 팀 공통 AI Data Workspace로 옮겼다. 컨텍스트는 Data Catalog(What: 데이터 암묵지와 집계 규칙), Analyst Persona(How: 분석 절차·해석 원칙·리포트 문체), Task Context(Why: Jira 이슈로 받는 과제 브리핑) 세 층으로 나눴다. 앞의 둘은 Git 저장소에 두고 마지막 하나는 Jira에 둔 채 연결 도구(Skill)로 읽힌다. 이제 누가 분석하든 같은 로그, 같은 집계 규칙, 같은 검증 절차에서 출발한다. 사람의 일은 반복 추출과 정합성 확인에서 문제 정의와 판단 쪽으로 옮겨 갔다.

개인별 CLAUDE.md로는 부족했던 이유

원문 필자는 지난 글에서 데이터 엔지니어와 분석가만 알던 로그 접근 방법과 분석 기준을 AI로 조회하는 사례를 소개했다. 이 환경을 팀 전체가 함께 쓰자 한계가 세 가지 드러났다.

1. 데이터의 암묵지: 어떤 로그를 고르고 어떤 기준을 적용할지는 분석 담당자가 경험으로 메워 오던 부분이었다. 에이전트에게 맡기려면 이 기준을 명시해야 하는데, 팀 공통 기준이 없었다.
2. 분석의 방법: 과제마다 결과를 내는 방식과 비교 대상이 달랐다. 어떤 LLM을 쓰느냐에 따라 리포트의 내용, 구성, 문체까지 달라졌다.
3. 분석의 배경: 왜 이 분석을 하는지, 어떤 가설을 세웠는지에 따라 봐야 할 지표가 달라진다. 그런데 과제의 맥락은 사람 머릿속에만 있었다.

그러다 보니 리포트 수치를 사람이 다시 맞춰 보고 분석이 적절했는지 재확인해야 했다. 팀은 개인 지침 문서에 지식을 쌓는 대신, 팀이 함께 관리하는 지식베이스와 과제 맥락으로 방식을 바꿨다.

세 층의 컨텍스트: What / How / Why

에이전트가 분석 전에 읽는 정보를 세 가지 질문으로 나눴다.

세 층으로 나눈 까닭은 정보마다 재사용 범위와 갱신 이유가 다르기 때문이다. 지표 정의는 여러 분석이 함께 쓰고 비교·검증 방법도 과제에 맞춰 되풀이해 적용한다. 특정 실험에서 무엇을 확인했고 다음에 무엇을 판단할지는 과제가 진행되면서 계속 바뀐다.

작업공간 구조

원문이 공개한 AI Data Workspace의 구성은 다음과 같다. Data Catalog와 Analyst Persona를 관리하고 분석에 쓴 SQL·결과·근거·리포트를 함께 보관한다.

AI Data Workspace
├── CLAUDE.md                           # 진입점. 읽을 순서와 금지 사항만 적는다
├── data_sources/
│   └── <db>/<table>.md                 # [What] Data Catalog. 테이블 하나에 문서 하나
├── .claude/
│   ├── references/
│   │   └── analyst-persona.md          # [How] Analyst Persona. 분석 절차·해석 원칙
│   ├── commands/                       # [How] 정형 분석 Command. weekly-metric · ab-test · add-data-source
│   └── skills/
│       ├── html-report/                # [How] 리포트 외형·차트
│       └── pangyo-analyst-voice/       # [How] 리포트 문장의 문체
└── analyses/
    └── <category>/<date>_<topic>/      # 분석 산출물. README · queries/ · results/ · report.html

(Jira 이슈 · 댓글)                      # [Why] Task Context. 저장소 밖에서 연결 도구로 읽는다

CLAUDE.md에는 읽을 순서와 금지 사항만 적는다. 실제 지식은 data_sources/와 .claude/ 아래에 흩어 두고 과제 맥락은 저장소 밖 Jira에 남긴다. 에이전트는 Jira 연결 도구(Skill)로 이 맥락을 브리핑받는다.

Data Catalog: 테이블 단위 문서로 암묵지를 옮긴다

Data Catalog는 로그 테이블의 스키마 바깥에 있던 팀의 사용 기준을 문서로 옮긴 것이다. 팀은 Google Cloud가 데이터와 시스템 주변 지식을 Markdown 문서로 표현하자며 내놓은 Open Knowledge Format(OKF) 가이드에서 착안했다.

• 단위: 테이블 하나에 문서 하나(data_sources/<db>/<table>.md)
• 구조: 테이블의 성격 → 메타 정보 → 주의할 컬럼 → 집계 규칙 → 데이터에서 확인한 사실
• 내용: 전체 스키마를 옮기지 않는다. 그 테이블을 쓸 때 헷갈리기 쉬운 점과 집계 규칙만 적고 실제 컬럼과 타입은 분석을 시작할 때 다시 조회한다.
• 작성 원칙: 스키마·파티션·값 분포 같은 사실은 LLM 분석 결과로 채우고 유효재생 기준처럼 정책에 해당하는 정의는 사람이 쓴다.

플레이어 로그와 앱 로그 중 무엇을 쓸지, cold 사용자를 ‘최근 N일 동안 유효재생이 없는 사용자’로 볼지는 스키마에 없는 팀의 논리적 정의다. 원천 데이터 구조는 손대지 않고 그 위에 조직이 합의한 지표와 해석 규칙을 얹는다는 점에서, 원문은 이 카탈로그를 semantic layer에 가깝다고 설명한다.

원문의 재생 로그 카탈로그 예시는 다음과 같다(일부 생략).

# play_log

사용자-콘텐츠 시청 로그. 주간 지표·A/B 테스트·전후 비교의 기본 데이터 소스.
집계·파생 지표·필터 규칙의 정의는 이 문서가 기준.

- 테이블 타입: EXTERNAL (Parquet)
- 파티션: date_id(YYYY-MM-DD) + hour_id(HH). 복합 파티션 → 반드시 필터
- 보유 기간: 2025-11 ~ (2026-07-16 실측)

## 컬럼 정보
| 컬럼 | 타입 | 주의사항 |
|---|---|---|
| user_id | string | 원본 식별자. 보고용 산출물에 노출 금지 |
| watch_length | double | 시청 시간, 단위 = 초. `>= y` 로 y초 재생 판정 |
| watch_percentage | double | 1.0 초과 가능 → cap 필수 |
| valid_view | boolean | 유효재생(x초 이상). 서비스 공식 기준 필드 |
| valid_view_flag | boolean | 스키마엔 있으나 미사용 → 아래 절 |
| action_name | string | 분석은 `play_end` 만 |
| reco_type | string | `reco` 가 추천 성능 집계의 기본 모수. 그 외 값은 제외 |

## 집계 규칙
| 지표 | 수식 |
|---|---|
| VVR(유효재생률) | valid_views / total_views |
| y초 재생률 | SUM(watch_length >= y) / total_views |
| 인당 재생수 | total_views / COUNT(DISTINCT user_id) |

## 데이터에서 확인한 사실
- valid_view_flag 는 전 행 false (2026-06-10 확인) → 유효재생 판정은 valid_view 를 쓴다

맨 처음의 재생수 문제는 이 문서 첫 줄에서 풀린다. 카탈로그가 이 로그를 ‘주간 지표·A/B 테스트·전후 비교의 기본 데이터 소스’로 못 박고 CLAUDE.md는 분석을 시작할 때 카탈로그부터 읽게 한다. 그래서 A와 B가 같은 요청을 하면 에이전트는 같은 로그에서 출발한다. 다른 목적에 쓰는 로그는 해당 테이블 문서 첫 줄에 용도가 적혀 있으니, 어느 로그를 고를지도 문서에 남는다.

Analyst Persona: 분석 패턴을 하나로 맞춘다

분석 패턴은 과거 분석 사례에서 원칙을 뽑아 만든 지침 analyst-persona.md로 통일했다.

• 목표: 누가 분석하든 같은 수준의 검증 절차에서 출발하게 한다.
• 절차 6단계: 분석 유형 분류 → 분석 설계 → 함정 점검 → 분석 → 해석 → 리포트 작성
• 함정 점검: 이상 신호를 행동 변화로 단정하기 전에 로그 수집이나 서비스 변경의 영향부터 확인한다.
• 리포트 구성: 핵심 결론을 먼저 쓰고 비교 조건·근거·SQL을 뒤에 붙이며 확인된 사실과 추정을 구분한다.

눈여겨볼 대목은 분석 패턴은 쓰되 과거 분석 히스토리는 참고하지 않는다는 원칙이다. 과제마다 목표와 성공 지표가 다르기 때문이다. 어떤 과제는 시청시간을, 다른 과제는 소비한 영상 수를 주요 지표로 삼는다. ‘시청시간이 늘었으니 좋은 변화’라는 과거 결론을 그대로 가져오면 그때의 목표가 지금의 판단 기준이 돼 버린다.

Task Context: Jira 이슈가 브리핑 자료가 된다

Task Context는 과제의 맥락을 에이전트에게 브리핑하는 층이다. 과제가 진행되는 Jira 이슈를 에이전트가 직접 읽는다.

• 브리핑 자료: Jira 이슈의 본문과 댓글
• 기록 방식: 관찰 → 가설 → 검증 결과 → 기각된 가설 → 다음 질문을 댓글로 이어 남긴다.
• 읽는 시점: 에이전트가 분석 전에 읽고 과제의 목적과 경과, 지금 답해야 할 질문을 파악한다.

적용 사례: 영상 임베딩 피처 A/B 실험

원문은 실제 과제 하나를 따라가며 세 컨텍스트가 함께 쓰이는 모습을 보여 준다. 수치와 식별 정보를 뺀 가상 사례로 재구성한 것이다.

추천 모델에 영상 임베딩(영상 내용을 숫자 벡터로 표현한 값)을 새 입력 피처로 넣었을 때 추천 성능이 나아지는지 확인하는 과제였다. 온라인 A/B 실험이 시작된 뒤, 같은 Jira 이슈에 질문 두 개가 댓글로 달렸다. 지금까지의 결과로 볼 때 실험을 계속할 가치가 있는지, 조정이 필요한지였다.

에이전트는 다음 순서로 움직였다.

1. CLAUDE.md의 순서대로 관련 카탈로그 문서를 읽고 현재 스키마를 다시 조회한다.
2. Persona의 분류에 따라 과제를 ‘A/B 효과’ 유형으로 잡는다. 설계 단계에서 주요 지표와 보조 지표를 나누고 완전히 관측된 날만 분석 기간으로 삼고, 실험 전 기간 데이터로 사용자 간 편차를 보정한다.
3. 함정 점검에서 연휴, 대조군 모델 교체, 이상치, 극단 사용자, 실험군 배분 등을 확인한다. 소수의 이상치 행을 뺀 것 말고는 비교 조건을 바꿀 요인이 없었다.
4. 지표별로 SQL·계산·노트를 나눠 분석하고 모듈마다 결과를 다시 검증한다.

중간 결론은 “관측한 범위에서 손해는 확인되지 않았지만, 이득도 확정하지 못했다”였다. 에이전트는 관측 기간을 늘린 뒤 미리 정한 규칙으로 판정하자고 제안했고 아직 답하지 못한 질문도 따로 적었다. 사람이 검토한 분석 결과는 에이전트가 Jira 댓글로 과제에 남긴다.

[중간점검] 판정 아님
① 계속할 가치: 관측 범위에서 손해 신호 없음. 이득은 미확정
② 조정 필요: 설계 유지. 관측 기간 연장 권장
근거: 완전 관측일만 사용 · 실험 전 기간으로 편차 보정 · 함정 점검 5항목 이상 없음
다음 질문: 연장 관측 후 같은 규칙으로 재판정. 아직 답하지 못한 항목은 README에 정리
판정 규칙(안): 주요 지표 차이가 합의 기준 이상 · 보조 지표 손해 없음 → 롤아웃 검토 (기준값은 팀 합의)

후속 분석은 규칙을 그대로 둔 채 관측 기간만 늘려 진행했다. 이슈 댓글에서 “이득 미확정, 같은 규칙으로 추가 관찰”이라는 현재 상태를 브리핑받아 출발했고 마지막 분석에서 규칙상 ‘실험로직 적용’ 조건을 충족했다. 실제 적용 여부는 기대 효과와 전환에 드는 운영·학습 비용을 견줘 사람이 따로 판단했다.

사람의 역할은 어떻게 바뀌었나

우리 환경에 적용한다면

원문은 팀 분석 자동화에 적용하려면 세 컨텍스트를 어떻게 구성할지부터 생각해 보라고 권한다. 원문 구조를 바탕으로 바로 가져다 쓸 수 있는 지점을 정리하면 이렇다.

1. CLAUDE.md는 얇게 둔다. 읽을 순서와 금지 사항만 적고 지식 본체는 테이블별 문서·페르소나·커맨드·스킬로 쪼갠다. 갱신 주기와 공유 범위가 다른 정보를 한 파일에 섞지 않는다.
2. 카탈로그는 스키마 사본이 아니라 정책 레이어다. “이 테이블은 어떤 분석의 기본 소스인가”를 첫 줄에 쓰고 헷갈리는 컬럼·집계 수식·실측으로 확인한 사실(날짜 포함)을 남긴다. 사실은 LLM이 채우고 정책 정의는 사람이 쓴다는 분업도 그대로 따라 할 만하다.
3. 페르소나에는 절차와 검증만 넣는다. 과거 결론을 지식처럼 넣으면 그때의 목표가 지금의 판단 기준이 된다.
4. 과제 맥락은 이슈 트래커에 쌓는다. 관찰 → 가설 → 검증 결과 → 기각된 가설 → 다음 질문을 댓글로 이어 쓰고 에이전트가 분석 전에 읽게 한다. 에이전트의 결과도 사람이 검토한 뒤 같은 이슈에 댓글로 남긴다.
5. 판정 규칙은 미리 정해 둔다. 중간 분석에서 결론을 서두르지 않고 “같은 규칙으로 재판정”하게 하면, 후속 분석이 현재 상태를 이어받아 출발할 수 있다.

같은 카카오 기술 블로그에서 데이터 분석 에이전트의 시스템 프롬프트·도구 명세서·메시지 배열 설계를 다룬 글은 카카오 테크 — 데이터 분석 에이전트를 만들며 배운 컨텍스트 설계에 정리해 두었다. 그 글이 에이전트 한 개의 컨텍스트 설계를 다룬다면, 이 글은 여러 사람이 같은 에이전트 환경을 공유할 때 무엇을 표준화해야 하는지를 다룬다.

참고

• 팀이 신뢰할 수 있는 AI 분석 환경 만들기: 추천팀의 컨텍스트 설계 — tech.kakao.com
• 타이틀 사진: Unsplash