---
title: "iaa-builder"
description: "CS 분류 라벨의 어노테이터 간 일치도(IAA)를 Cohen·Fleiss κ로 측정하는 스킬입니다. \"이 라벨링 일치도 재줘\", \"Cohen 카파 계산\", \"골드셋 만들어줘\", \"이 분류 운영에 써도 돼?\"처럼 말하면 됩니다. 골드셋 샘플링 → 2인 독립 라벨 → κ 산출 → 졸업 게이트 판정. aspect-sentiment·cs-intent의 운영 졸업 선행 관문."
pack: itda-data
slug: iaa-builder
status: experimental
tags: ["iaa", "kappa", "cohen", "fleiss", "agreement", "korean", "stdlib"]
---
# iaa-builder 사용 가이드

CS 분류 라벨(`aspect-sentiment` 측면, `cs-intent` 인텐트)이 운영에 써도 될 만큼 일관된지를 어노테이터 간 일치도(Cohen/Fleiss κ)로 측정합니다. κ는 Claude의 추정값이 아니라 실제 결정론 통계 연산 결과입니다.

이렇게 요청하면 됩니다.

```
/iaa-builder 이 라벨링 시트 두 사람 일치도 재줘
```

```
/iaa-builder Cohen 카파 계산해줘
```

```
/iaa-builder 상담 로그에서 골드셋 200건 뽑아줘. 인텐트별로 비례해서.
```

---

## 활용 시나리오

### 골드셋이 아직 없을 때 — 샘플링부터

CS 로그(JSONL/CSV)에서 라벨 빈칸 어노테이션 시트(CSV)를 만듭니다.

```
/iaa-builder 이 CS 로그에서 200건 골드셋 만들어줘. 인텐트별로 비례 배분해서.
```

생성된 시트의 `annotator_1`·`annotator_2` 컬럼을 두 사람이 서로 안 보고 독립으로 채웁니다.

⚠️ **cs-intent 출력을 시트에 바로 넣지 마세요**: cs-intent 출력에는 원문 본문이 포함되지 않습니다. 그대로 넣으면 어노테이터가 읽을 글이 없습니다(스킬이 경고를 띄웁니다). 원본 CS 로그에 cs-intent의 분류 결과를 합친 파일을 입력하거나, "원문 인용 발췌"를 본문으로 써서 측정하세요.

### 라벨이 채워진 시트가 있을 때 — κ 측정

```
/iaa-builder 이 어노테이션 시트 일치도 재줘. 합격선 0.61로.
```

2명이면 Cohen's κ + 카테고리별 κ + 불일치 목록, 3명 이상이면 Fleiss' κ가 나옵니다. 합격선을 말하지 않으면 기본 0.61(= Landis-Koch substantial 하한)이 적용됩니다. κ=0.60은 'moderate'(재측정 권고 등급)이라 졸업에 미달합니다.

### 어느 카테고리가 갈리는지 짚을 때

```
/iaa-builder 환불이랑 반품 카테고리가 자꾸 헷갈리는데 어디서 갈리는지 보여줘
```

카테고리별 κ 값으로 약한 카테고리를, 실제 갈린 사례 목록으로 경계 규칙을 다듬습니다. (카테고리별 분해는 2인 측정에서만 나옵니다 — 아래 팁 참고.)

---

## 샘플링 옵션

| 하고 싶은 것 | 이렇게 요청하세요 |
|---|---|
| 인텐트별 비례 배분 골드셋 | `/iaa-builder 인텐트 분포에 맞게 비례 배분해서 뽑아줘` |
| 3인 라벨 시트 만들기 | `/iaa-builder 라벨 컬럼 3개짜리 시트로 만들어줘` |
| 같은 샘플 다시 재현 | `/iaa-builder 같은 난수 시드로 다시 뽑아줘` |
| 본문 컬럼 이름이 다를 때 | `/iaa-builder 본문 컬럼이 'content'야, 식별자는 'id'고` |
| 시트 파일 이름 지정 | `/iaa-builder 결과를 review_sheet.csv로 저장해줘` |

---

## 측정 결과 읽기

리포트의 핵심 필드:

| 필드 | 설명 |
|---|---|
| `overall_kappa` / `interpretation` | 전체 κ + Landis-Koch 등급 |
| `graduation.passed` | 합격선 통과 여부 |
| `per_category_kappa` | 카테고리별 κ (2인 측정 한정) |
| `ambiguous_categories` | κ가 합격선 미만인 카테고리 = 정의 보강 1순위 (2인 한정) |
| `disagreements` | 실제 갈린 건 목록 |

리포트 정합성이 궁금하면 이렇게 요청하세요.

```
/iaa-builder 이 리포트가 스키마 기준으로 올바른지 검증해줘
```

---

## 팁

- **κ가 낮으면 라벨러가 아니라 정의를 고친다**: `ambiguous_categories`에 잡힌 카테고리의 정의를 보강하고 불일치 사례로 경계 규칙을 명확히 한 뒤 재라벨합니다. 합격선을 낮추는 건 측정을 무의미하게 만듭니다.
- **합격선 0.61의 의미**: 기본 졸업 합격선은 0.61(= substantial 하한)입니다. κ=0.60은 'moderate' 등급(재측정 권고)이라 졸업에 미달하므로, 합격선과 등급이 자기일관됩니다.
- **카테고리별 분해는 2인 측정 한정**: 카테고리별 κ와 모호 카테고리 목록은 2인(Cohen) 경로에서만 나옵니다. 3인 이상(Fleiss)에서는 전체 κ만 나옵니다. 카테고리별 약점을 보려면 2인 측정이 필요합니다.
- **2인 이상 독립 라벨이 전제**: 같은 골드셋을 2명+가 서로 모르게 라벨해야 일치도가 의미를 가집니다. 라벨러가 1명이면 스킬이 거부합니다.
- **다중 라벨 한계**: κ는 명목 단일 라벨 기준입니다. `secondary_intents` 같은 다중 라벨은 primary만 쓰거나 라벨별 이진 κ로 분해해야 합니다.
- **prevalence/bias paradox**: 한 카테고리가 압도적이면 κ가 낮게 나올 수 있어 리포트는 관측 일치(`po`)·우연 일치(`pe`)를 함께 표기합니다.
- **대표성은 별도**: κ가 높아도 골드셋 대표성이 무너지면 운영 일반화는 따로 확인해야 합니다. 골드셋 샘플링 시 인텐트별 비례 배분을 요청하면 대표성이 올라갑니다.
- **자매 스킬과의 관계**: `cs-intent`/`aspect-sentiment`가 라벨을 만들면, iaa-builder가 그 라벨의 신뢰성을 κ로 측정합니다.