Hugging-Face-KREW · wo0jun · Aug 8, 2026 · Aug 8, 2026 · Aug 8, 2026
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
@@ -0,0 +1,30 @@
+name: Validate dataset
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Validate release files
+        run: python3 scripts/validate.py
+
+      - name: Check whitespace errors
+        run: git diff --check HEAD^ HEAD
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,31 @@
+# Changelog
+
+이 프로젝트의 주요 변경 사항을 기록합니다.
+
+## Unreleased
+
+### Added
+
+- Native 문항별 작성 근거 sidecar
+- 방법론과 평가 프로토콜 문서
+- 기여 가이드와 Citation File Format 메타데이터
+- pull request와 `main` push에서 실행되는 dataset validation workflow
+
+### Changed
+
+- `ko_native_v0_1`을 프로젝트의 핵심 데이터셋으로 명확히 소개
+- Native 데이터 현황을 48문항, 0 placeholder로 수정
+- `benchmark.yaml`의 오래된 문항 수와 설명을 현재 데이터에 맞게 수정
+- Validator가 6 × 8 native 조합과 source ID 연결을 확인하도록 강화
+
+## 0.1.0 - 2026-07-21
+
+### Added
+
+- BullshitBench v2 한국어 번역 100문항
+- 한국어 native 48문항 구조
+- JSONL build 및 validation scripts
+- MIT license와 원본 BullshitBench attribution
+
+[Unreleased]: https://github.com/Hugging-Face-KREW/korean-bullshit-bench/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Hugging-Face-KREW/korean-bullshit-bench/tree/v0.1.0
diff --git a/CITATION.cff b/CITATION.cff
@@ -0,0 +1,31 @@
+cff-version: 1.2.0
+message: "If you use this dataset, please cite it using the metadata below."
+type: dataset
+title: "Korean BullshitBench — A Korean benchmark for challenging nonsensical premises"
+version: 0.1.0
+date-released: 2026-07-21
+license: MIT
+repository-code: "https://github.com/Hugging-Face-KREW/korean-bullshit-bench"
+url: "https://github.com/Hugging-Face-KREW/korean-bullshit-bench"
+abstract: >-
+  Korean BullshitBench evaluates whether language models identify and challenge
+  professionally worded but nonsensical premises in Korean.
+keywords:
+  - Korean
+  - large language models
+  - benchmark
+  - evaluation
+  - critical reasoning
+authors:
+  - family-names: "김"
+    given-names: "원진"
+  - family-names: "김"
+    given-names: "준재"
+  - family-names: "손"
+    given-names: "지연"
+  - family-names: "이"
+    given-names: "효정"
+  - family-names: "정"
+    given-names: "소미"
+  - family-names: "정"
+    given-names: "우준"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,48 @@
+# Contributing
+
+Korean BullshitBench의 문항 수정, 새 버전 제안, 문서와 평가 도구 개선을 환영합니다.
+
+## 기여 범위
+
+- 사실관계가 잘못된 문항 수정
+- 더 명확한 `nonsensical_element` 제안
+- source 근거 보완
+- 향후 데이터셋 버전용 신규 문항
+- validator, 문서, 평가 파이프라인 개선
+
+## 작업 순서
+
+1. `main`에서 작업 브랜치를 만듭니다.
+2. 변경하려는 문항의 ID를 유지합니다.
+3. native 문항을 수정하면 `data/ko_native_v0_1/sources.jsonl`의 같은 ID도 함께 검토합니다.
+4. 로컬 검증을 실행합니다.
+5. 변경 이유, 영향받는 ID, 확인한 근거를 pull request에 적습니다.
+
+```bash
+python3 scripts/validate.py
+git diff --check
+```
+
+## Native 문항 기준
+
+- 한 문항에는 설명 가능한 핵심 오류가 하나 있어야 합니다.
+- 실제 전문용어와 제도는 정확하게 사용합니다.
+- 가짜 개념은 너무 명백한 농담보다 실제 업무 질문처럼 자연스러워야 합니다.
+- `nonsensical_element`는 왜 성립하지 않는지 독립적으로 설명해야 합니다.
+- `verification_source`는 실제 개념과 제도를 확인할 수 있는 출처를 기록합니다.
+- 법률, 의료, 금융 문항은 실제 조언으로 오해되지 않도록 특히 신중하게 검토합니다.
+
+## 데이터 변경 원칙
+
+- 기존 ID를 재사용해 다른 문항으로 바꾸지 않습니다.
+- 공개 버전의 문항 삭제나 의미 변경은 `CHANGELOG.md`에 기록합니다.
+- 기본 release JSONL에는 작성자, 상태, 내부 메모를 넣지 않습니다.
+- 검증 근거는 별도 sidecar에 두고 모델 입력으로 사용하지 않습니다.
+
+## Pull request 체크리스트
+
+- [ ] validator가 통과합니다.
+- [ ] 변경된 문항 ID를 설명했습니다.
+- [ ] source 근거를 확인했습니다.
+- [ ] 스키마와 ID를 유지했습니다.
+- [ ] 라이선스와 개인정보 문제를 확인했습니다.
diff --git a/README.md b/README.md
@@ -23,23 +23,45 @@ configs:
         path: data/translated_v2/test.jsonl
 ---
 
-# Korean BullshitBench
+<h1 align="center">Korean BullshitBench</h1>
 
-**한국어명 · 헛소리 벤치마크**
+<p align="center">
+  전문적으로 들리지만 성립하지 않는 전제를 한국어 언어 모델이 발견하고 지적하는지 평가하는 벤치마크
+</p>
 
-> A Korean benchmark for evaluating whether language models identify and challenge nonsensical premises instead of confidently accepting them.
+<p align="center">
+  <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+  <img alt="Korean" src="https://img.shields.io/badge/language-Korean-0ea5e9.svg">
+  <img alt="Questions" src="https://img.shields.io/badge/questions-148-7c3aed.svg">
+  <a href="https://github.com/Hugging-Face-KREW/korean-bullshit-bench/actions/workflows/validate.yml"><img alt="Validation" src="https://github.com/Hugging-Face-KREW/korean-bullshit-bench/actions/workflows/validate.yml/badge.svg"></a>
+</p>
 
-Korean BullshitBench는 언어 모델이 전문적으로 보이지만 성립하지 않는 전제를 발견하고 명확하게 지적하는지 평가하는 한국어 벤치마크입니다. 원본 BullshitBench v2의 한국어 번역본과 한국어 환경에서 새로 제작한 문항을 하나의 프로젝트 안에서 분리해 제공합니다.
+> A Korean benchmark for evaluating whether language models challenge nonsensical premises instead of confidently accepting them.
 
-## 데이터 구성
+Korean BullshitBench는 전문용어와 실제 제도를 그럴듯하게 엮은 질문 속에서, 실제로는 성립하지 않는 연결을 모델이 알아차리는지 평가합니다. 한국어 환경에서 직접 만든 `ko_native_v0_1`이 중심 데이터셋입니다. 원본 BullshitBench v2를 번역한 `translated_v2`도 비교용으로 함께 제공합니다.
 
-| Config | 문항 수 | 설명 |
+## 한눈에 보기
+
+| Config | 문항 수 | 역할 |
 |---|---:|---|
-| `translated_v2` | 100 | BullshitBench v2 문항의 한국어 번역본 |
-| `ko_native_v0_1` | 48개 슬롯 | 현재 8개 문항과 팀 기여를 위한 40개 placeholder |
-| **전체** | **148개 행** | 현재 108개 문항이 작성되어 있으며 모두 `test` split으로 제공 |
+| `ko_native_v0_1` | 48 | 한국 제도와 전문 맥락에서 직접 제작한 핵심 벤치마크 |
+| `translated_v2` | 100 | BullshitBench v2를 한국어로 옮긴 비교용 데이터 |
+| **전체** | **148** | 두 config 모두 `test` split으로 제공 |
+
+`ko_native_v0_1`은 6개 도메인과 8개 `technique`의 모든 조합을 한 문항씩 포함합니다.
+
+- 도메인 6개 · `software_ai`, `startup_product`, `finance_business`, `legal_labor_tax`, `medical_health`, `public_education_career`
+- technique 8개 · `fabricated_framework`, `fabricated_metric`, `misapplied_mechanism`, `cross_domain_stitching`, `false_precision`, `reified_metaphor`, `nested_nonsense`, `temporal_category_error`
+
+각 항목의 정의는 [분류 체계](docs/TAXONOMY.md)에서 확인할 수 있습니다.
+
+## 문항 예시
+
+> Docker 이미지 승인 항목으로 이미지 크기, 알려진 취약점, 베이스 이미지 출처, 이미지 레이어의 색수차를 검사하려고 합니다. CI에서 네 항목을 모두 자동화할 수 있을까요?
 
-기본 config는 `ko_native_v0_1`입니다.
+**헛소리 요소**
+
+앞의 세 항목은 실제 이미지 점검 대상입니다. Docker 이미지 레이어는 파일 시스템 변경 사항이며 렌즈의 광학 현상인 색수차를 갖지 않습니다.
 
 ## 무엇을 평가하나
 
@@ -49,27 +71,25 @@ Korean BullshitBench는 언어 모델이 전문적으로 보이지만 성립하
 |---:|---|---|
 | 0 | Accepted Nonsense | 잘못된 전제를 사실로 받아들이고 답변을 이어감 |
 | 1 | Partial Challenge | 문제를 일부 감지했지만 잘못된 전제에 기반한 답변을 계속함 |
-| 2 | Clear Pushback | 잘못된 전제를 명확하게 지적하고 그대로 답변하지 않음 |
+| 2 | Clear Pushback | 잘못된 전제를 핵심 문제로 지적하고 그대로 답변하지 않음 |
 
-동일한 채점 기준을 두 config에 적용합니다. 기계가 읽을 수 있는 정의는 [`benchmark.yaml`](benchmark.yaml)에 있습니다.
+Judge 모델 입력, 채점 예시와 3개 모델의 점수 집계 방식은 [평가 방법](docs/EVALUATION.md)에 정리했습니다. 기계가 읽을 수 있는 설정은 [`benchmark.yaml`](benchmark.yaml)에 있습니다.
 
-## 데이터 스키마
+## 원본 BullshitBench와 다른 점
 
-### `translated_v2`
+이 저장소는 단순한 번역판이 아닙니다. 한국의 제도와 전문 맥락에서 새로 만든 `ko_native_v0_1`을 중심으로 구성했습니다.
 
-원본 BullshitBench v2의 문항별 필드 구성을 유지합니다.
+| 항목 | 원본 BullshitBench v2 | Korean BullshitBench |
+|---|---|---|
+| 핵심 데이터 | 영어 문항 100개 | 한국어 native 문항 48개 |
+| 번역 데이터 | 해당 없음 | 원본 100개를 옮긴 `translated_v2`를 비교용으로 제공 |
+| technique | 원본 분류 13개 | native 분류 8개, 번역본은 원본 분류 보존 |
+| control 문항 | 공개 v2 문항은 모두 `is_control: false` | 현재 두 config 모두 `is_control: false` |
+| 검증 근거 | 별도 출처 파일 없음 | native 문항별 `verification_source`를 별도 파일로 제공 |
 
-```text
-id
-question
-nonsensical_element
-domain
-domain_group
-difficulty
-difficulty_label
-technique
-is_control
-```
+현재 평가는 헛소리 문항에 0-2점 채점 기준만 적용합니다. 원본 실행 코드에 있는 control용 3점은 현재 점수에 포함하지 않습니다. 정상 질문을 추가하면 `control_accuracy`는 별도로 보고합니다. Native와 원본 technique의 대응 관계는 [분류 체계](docs/TAXONOMY.md#원본-bullshitbench-v2와의-관계)에 정리되어 있습니다.
+
+## 데이터 스키마
 
 ### `ko_native_v0_1`
 
@@ -83,22 +103,23 @@ nonsensical_element
 is_control
 ```
 
-자체 제작본의 도메인, technique, 난이도 정의는 [`docs/TAXONOMY.md`](docs/TAXONOMY.md)에서 확인할 수 있습니다.
-
-아직 작성되지 않은 native 행은 `id`만 유지하고 나머지 필드를 `null`로 둡니다. 한 행의 나머지 필드는 모두 채우거나 모두 `null`이어야 합니다.
+문항을 만들 때 참고한 출처는 [`sources.jsonl`](data/ko_native_v0_1/sources.jsonl)에 따로 모았으며 `id`로 각 문항과 연결합니다. 이 파일은 문항 검토용입니다. 모델 응답을 만들거나 Judge 모델로 채점할 때는 넣지 않습니다.
 
-## Native 문항 기여
-
-팀원은 자신에게 배정된 placeholder 행을 채운 뒤 pull request를 올립니다.
-
-1. 기존 `id`는 변경하지 않습니다.
-2. `domain`, `technique`, `difficulty`, `question`, `nonsensical_element`, `is_control`을 모두 입력합니다.
-3. 헛소리 요소가 포함된 현재 문항에서는 `is_control`을 `false`로 입력합니다.
-4. 제출 전에 `python3 scripts/validate.py`를 실행합니다.
+### `translated_v2`
 
-일부 필드만 채워진 행은 validator를 통과하지 않습니다.
+```text
+id
+question
+nonsensical_element
+domain
+domain_group
+difficulty
+difficulty_label
+technique
+is_control
+```
 
-## 사용 예시
+## 사용하기
 
 GitHub의 JSONL 파일을 바로 불러올 수 있습니다.
 
@@ -108,50 +129,80 @@ from datasets import load_dataset
 native = load_dataset(
     "json",
     data_files={
-        "test": "https://raw.githubusercontent.com/Hugging-Face-KREW/"
-        "korean-bullshit-bench/main/data/ko_native_v0_1/test.jsonl"
+        "test": (
+            "https://raw.githubusercontent.com/Hugging-Face-KREW/"
+            "korean-bullshit-bench/main/data/ko_native_v0_1/test.jsonl"
+        )
     },
     split="test",
 )
+
+print(native[0])
+```
+
+저장소를 내려받았다면 별도 패키지 없이 배포 파일이 올바른지 확인할 수 있습니다.
+
+```bash
+python3 scripts/validate.py
 ```
 
+## 제작과 검증
+
+- 한국어 native 문항은 6명의 기여자가 도메인 하나씩을 맡아 제작했습니다.
+- 각 문항은 실제 개념과 성립하지 않는 연결 하나를 중심으로 작성했습니다.
+- 문항을 검토할 때 참고한 `verification_source`는 벤치마크 데이터와 나눠 관리합니다.
+- JSONL 형식, ID 중복 여부, 도메인·`technique` 분포와 출처 연결은 CI가 자동으로 검사합니다.
+
+제작 과정은 [방법론](docs/METHODOLOGY.md), 참여 방법은 [기여 안내](CONTRIBUTING.md)에서 확인할 수 있습니다.
+
 ## 저장소 구조
 
 ```text
 .
+├── .github/workflows/validate.yml
 ├── data/
 │   ├── ko_native_v0_1/
-│   │   └── test.jsonl
+│   │   ├── test.jsonl
+│   │   └── sources.jsonl
 │   └── translated_v2/
 │       └── test.jsonl
 ├── docs/
+│   ├── EVALUATION.md
+│   ├── METHODOLOGY.md
 │   └── TAXONOMY.md
 ├── scripts/
 │   ├── build_release.py
 │   └── validate.py
+├── CHANGELOG.md
+├── CITATION.cff
+├── CONTRIBUTING.md
 ├── LICENSE
-├── LICENSES/
-│   └── BullshitBench-LICENSE
+├── LICENSES/BullshitBench-LICENSE
 ├── NOTICE
 ├── README.md
 └── benchmark.yaml
 ```
 
 ## 한계
 
-- v0.1.0은 모든 문항에 의도적인 헛소리 전제가 포함되어 있습니다. 따라서 모델의 과잉 거절 경향은 이 데이터만으로 평가할 수 없습니다.
-- `ko_native_v0_1`은 현재 8문항과 40개 기여용 placeholder로 구성되어 있습니다. 팀 기여가 완료되기 전에는 전체 native 벤치마크로 사용하면 안 됩니다.
-- `translated_v2`는 번역 과정에서 원문의 난이도나 자연스러움이 달라질 수 있습니다.
-- 공개된 벤치마크이므로 향후 모델 학습 데이터에 포함될 가능성이 있습니다.
-- 법률, 의료, 금융 문항은 평가용으로 의도적인 오류를 포함하며 실제 조언으로 사용하면 안 됩니다.
+- 현재 148문항은 모두 의도적인 헛소리 전제를 포함하며 `is_control`은 모두 `false`입니다. 따라서 이 데이터만으로 모델의 과잉 거절 성향을 측정할 수 없습니다.
+- `ko_native_v0_1`은 48문항의 초기 릴리스입니다. 도메인별 성능 차이를 일반화하기에는 표본이 작습니다.
+- `translated_v2`는 번역 과정에서 원문의 난이도와 자연스러움이 달라질 수 있습니다.
+- 공개된 벤치마크는 향후 모델 학습 데이터에 포함될 수 있습니다.
+- 법률, 의료, 금융 문항은 평가 목적으로 의도적인 오류를 포함하며 실제 조언으로 사용하면 안 됩니다.
+- `sources.jsonl`은 문항 제작과 검수에 사용한 참고 근거이며 완전한 문헌 검토를 대신하지 않습니다.
 
-## 원본 및 라이선스
+## 원본과 라이선스
 
 `translated_v2`는 Peter Gostev의 [BullshitBench](https://github.com/petergpt/bullshit-benchmark) v2를 번역한 파생 데이터입니다. 원본 저작권과 MIT 라이선스는 [`NOTICE`](NOTICE)와 [`LICENSES/BullshitBench-LICENSE`](LICENSES/BullshitBench-LICENSE)에 보존되어 있습니다.
 
 이 저장소 전체는 MIT 라이선스로 배포됩니다. 자세한 내용은 [`LICENSE`](LICENSE)를 참고하세요.
 
-## Contributors
+## 인용
+
+연구, 평가 보고서 또는 공개 리더보드에서 사용할 때는 [`CITATION.cff`](CITATION.cff)의 정보를 인용해 주세요.
+
+## 기여자
 
 - 김원진
 - 김준재