정성 연구를 위한 코드북 개발

연역적 코드와 귀납적 코드로 정성 코드북을 만들고, 포함 및 제외 기준을 쓰고, 팀과 함께 코드북을 시범 적용하고, 각 라운드의 버전을 관리합니다.

정성 코드북은 연구의 모든 코드를 나열하며, 각 항목에는 코드의 이름, 정의, 코드를 적용할 때와 적용하지 않을 때의 기준, 데이터에서 가져온 예시가 들어 있습니다. 팀은 보통 이론이나 연구 질문에서 가져온 연역적 코드로 시작하여 읽는 동안 발견한 귀납적 코드를 추가하고, 몇 건의 전사문으로 코드북을 시범 적용하며, 수정할 때마다 번호를 매깁니다. 각 코딩에 버전 번호를 기록해 두면 독자는 어떤 버전의 코드북으로 어떤 전사문을 코딩했는지 알 수 있습니다.

질적 연구에서 코딩은 인터뷰 전사문, 포커스 그룹, 현장 노트, 개방형 설문 응답의 발췌문에 코드라고 부르는 짧은 라벨을 붙입니다. 연역적 코드는 코딩이 시작되기 전에 이론, 선행 연구, 인터뷰 가이드에서 나오고, 귀납적 코드는 코딩하는 동안 데이터에서 나옵니다. 이 두 용어는 연역과 귀납 추론의 방향을 빌려 온 것입니다. 코더 간 신뢰도는 두 코더가 같은 발췌문에 같은 코드를 적용하는 빈도를 측정합니다. 미국 질병통제예방센터의 팀 코딩에 관해 쓰면서 MacQueen과 동료들(1998)은 구조화된 코드북을 텍스트의 역동적 분석을 위한 안정적인 틀이라고 설명합니다. MacQueen과 동료들이 설명하는 코드북 기능은 코더 간 일치도를 높이기 위해 선택된 것입니다.

아래 절은 사람 팀이 정성 분석에 적용하는 코드북을 다룹니다. 효과적인 어노테이션 지침 작성하기는 모델을 학습하거나 평가하는 어노테이션 작업의 라벨 규칙을, LLM이 따를 수 있는 코드북 작성하기는 언어 모델이 적용하는 코드북을 다룹니다. 정성 코딩을 위한 공유 코드북은 Potato의 코드북 기능을 옵션별로 문서화합니다.

연역적, 귀납적, 하이브리드 코드

연역적 코드북은 코딩이 시작되기 전에 작성하며, 코딩은 코드북의 범주가 참가자의 말을 얼마나 잘 설명하는지를 보여 줍니다. 귀납적 코드북은 읽는 동안 자랍니다. 어떤 코드에도 맞지 않는 구절은 후보 코드가 되고, 그 아이디어가 여러 참가자에게서 되풀이되면 후보에 항목이 부여됩니다. 주제 분석과 근거 이론은 모두 귀납적 코딩에 의존합니다.

많은 팀 프로젝트는 두 방향을 결합합니다. Fereday and Muir-Cochrane (2006)은 간호 분야 성과 피드백 연구에서 데이터 기반 코드와 이론 기반 코드를 통합한 하이브리드 과정을 설명합니다. DeCuir-Gunby, Marshall, and McCulloch (2011)는 인터뷰 데이터를 위한 이론 기반 및 데이터 기반 코드를 개발하고 다른 코더가 코드북을 적용하도록 훈련하는 단계를 제시합니다. Roberts, Dowell, and Nie (2019)는 연구 질문, 문헌, 같은 프로젝트의 설문, 인터뷰에 대한 첫 훑어보기로 예비 코드북을 만든 다음 코딩 중에 예상치 못한 주제를 들어오게 했습니다. 하이브리드 코드북에서는 각 항목이 코드의 기원을 기록합니다. 그러면 독자는 어떤 코드를 연구가 데이터에 가져왔고 어떤 코드를 데이터가 만들어 냈는지 알 수 있습니다.

코드 항목의 구성 요소

코드 항목은 그 코드를 만들 때 현장에 없었던 코더에게 코드를 적용하는 방법을 알려 줍니다. Roberts, Dowell, and Nie (2019)는 각 코드를 라벨, 정의, 설명, 조건 또는 제외 사항, 원 데이터의 예시로 작성했습니다. 아래 표는 그 형식을 포함 항목, 비전형적 예시, 반례, 코드의 기원으로 확장합니다. 예시는 교사들의 원격 수업 경험에 관한 연구에서 가져온 연역적 코드입니다.

부분	그 부분이 말하는 것	"Workload" 예시
이름	코드북에서 고유한 짧은 라벨	Workload
짧은 정의	코더가 전사문 중간에서도 확인할 수 있는 한 문장	The teacher describes the time or effort that remote teaching took.
전체 정의	경계를 쉬운 말로 그은 개념	Time or effort spent on planning, delivery, grading, and contact with students and families, compared with the teacher's classroom routine
포함 기준	해당되는 구절의 종류	Hours, preparation, grading, or messages that took longer than in a classroom
제외 기준	아슬아슬하게 빗나가는 경우이며, 있다면 대신 쓸 코드	Tiredness or stress with no task or time named
전형적 예시	데이터에서 가져온, 분명히 들어맞는 구절	"The lesson plans took twice as long because everything had to work on a phone."
비전형적 예시	들어맞지만 코더가 놓칠 수 있는 구절	"Once the district bought hotspots, I stopped spending my planning period driving to students' houses."
반례	들어맞는 것처럼 보이지만 그렇지 않은 구절	"I was exhausted all the time."
기원	연역적 또는 귀납적, 출처와 함께	Deductive, from question 3 of the interview guide

제외 기준은 두 코드가 가까이 있는 곳에서 가장 중요하며, 이웃 코드를 지명하는 제외 기준은 코더에게 두 코드 중 어느 것을 골라야 하는지 알려 줍니다. 예시는 식별 세부 정보를 제거한 자신의 전사문에서 가져오세요. 지어낸 예시에는 실제 발화의 곁가지와 미완성 문장이 빠져 있습니다.

상위 코드와 하위 코드

긴 코드북은 트리로 적용하면 더 쉽습니다. 상위 코드는 Workload 같은 넓은 범주를 지명하고, 하위 코드는 가족과의 업무 시간 외 연락처럼 연구에서 따로 세고 싶은 변형을 지명합니다. 각 하위 코드에는 별도의 항목이 필요합니다. 상위 코드의 항목은 코더가 상위 코드를 직접 적용하는지 하위 코드를 통해서만 적용하는지를 밝히는데, 둘 다 적용하는 코더는 상위 코드의 수를 두 배로 만들기 때문입니다. 하이브리드 코드북에서 귀납적 코드는 흔히 연역적 상위 코드의 하위 코드로 추가됩니다. 원격 수업 연구에서 시범 적용은 일이 가정생활로 번지는 구절을 찾아냈고, 팀은 Home and work boundary를 Workload의 하위 코드로 추가했습니다.

몇 건의 전사문으로 코드북 시범 적용하기

시범 적용은 주 코딩 라운드 전에 몇 건의 전사문에 코드북 초안을 적용합니다. 서로 다른 시범 전사문(예: 각 장소나 집단에서 한 명의 참가자)을 선택하고, 두 코더가 모든 발췌문을 독립적으로 코딩하게 하세요. 두 코딩을 발췌문별로 비교하고, 각 불일치에 대해 항목이 불분명했는지 발췌문이 모호했는지 결정하세요. 불분명한 항목은 더 선명한 정의, 새 제외 기준, 새 예시를 받습니다.

수정한 뒤에는 시범 전사문을 다시 코딩하지 말고 새 전사문을 코딩하세요. 시범 전사문에서 작성한 항목은 그 전사문에는 잘 맞으며, 같은 자료를 다시 코딩해서는 코드북이 새 인터뷰에서 어떻게 작동하는지 거의 알 수 없습니다. 시범 적용에서 계산한 계수는 코드북 초안을 설명하며, 서술에 보고하는 신뢰도는 이후 라운드에서 나옵니다. DeCuir-Gunby와 동료들은 코더를 훈련하는 동안 신뢰도를 확립하는 문제를 논의합니다. 팀이 최종 버전에 합의하면 코드북은 변경 없이는 코딩을 계속할 수 없는 곳에서만 바뀝니다. Roberts와 동료들은 최종 버전을 시험하는 동안 불일치를 기록하고 같은 규칙을 따랐습니다.

팀과 함께 코드 수정하기

팀의 수정에는 다음이 포함됩니다.

다듬기. 코더들이 항목을 다르게 읽으면 정의를 다시 쓰거나 제외 기준을 추가합니다.
추가. 데이터가 계속 만들어 내는 귀납적 코드의 항목을 씁니다.
병합. 코더들이 구분하지 못하는 두 코드를 하나로 합칩니다.
분할. 코더들이 서로 다른 두 아이디어에 사용한 코드를 나눕니다.
폐기. 아무도 적용하지 않은 코드를 제거하거나, 그 코드가 없다는 것이 발견인 경우 메모와 함께 유지합니다.

팀의 한 사람이 코드북을 편집하게 하고, 나머지 팀원은 전사문 작업 도중에 항목을 편집하는 대신 정기 회의에서 변경을 제안하게 하세요. 각 결정은 변경 내용, 이유, 동의한 사람이 담긴 날짜 붙은 한 줄로 변경 기록에 남습니다. 병합이나 분할은 이전 코딩의 의미를 바꾸므로, 기록에는 변경이 영향을 준 발췌문을 밝힙니다.

코드북 버전 관리

시범 초안은 1.0, 주 라운드가 사용하는 코드북은 2.0처럼 코드북의 각 버전에 번호와 날짜를 매기고 모든 버전을 보관하세요. 각 전사문의 코딩 옆에 버전을 기록하세요. 그러면 방법 절에서 어떤 코드북으로 어떤 전사문을 코딩했는지 말할 수 있습니다. 변경이 코드의 의미를 바꾸면 이전 버전으로 코딩한 전사문은 그 코드에 대해 다시 코딩하거나 이전 정의로 코딩한 것으로 보고합니다. 문구를 고치거나 예시를 추가하는 변경은 다시 코딩할 필요가 없습니다. 최종 버전과 변경 기록은 부록이나 보충 파일로 공개하세요.

Potato의 코드북

Potato 2.13.1은 코드북을 프로젝트의 데이터베이스에 저장하고 각 변경을 기록합니다. 아래 구성은 원격 수업 연구의 시범 라운드를 설정합니다. 두 코더 모두 모든 발췌문을 코딩하고, 코더는 읽는 동안 코드를 추가할 수 있으며, 사용자 lead가 판정자로서 정의를 편집하고 코드를 병합합니다.

yaml

annotation_task_name: Remote teaching interviews
task_dir: .
output_annotation_dir: annotation_output/
data_files:
  - data/excerpts.jsonl
item_properties:
  id_key: id
  text_key: text
user_config:
  allow_all_users: true
  users: []
 
# Pilot round: both coders code every excerpt of the pilot transcripts
num_annotators_per_item: 2
 
# Coders may add a code while they read; only the lead edits definitions or merges codes
codebook_mode: extensible
 
adjudication:
  enabled: true
  adjudicator_users: [lead]
 
annotation_schemes:
  - annotation_type: multiselect
    name: codes
    description: Which codes apply to this excerpt?
    codebook: true
    labels:
      - name: Workload
        description: The teacher describes the time or effort that remote teaching took.
      - name: Student engagement
        description: The teacher describes whether students took part, paid attention, or completed work.
      - name: Technology access
        description: The teacher describes devices, internet connections, or software that students or the teacher had or lacked.
      - name: School support
        description: The teacher describes help, guidance, or resources from the school or district, or the lack of them.

codebook: true는 스킴이 YAML 대신 코드북에서 코드를 읽게 합니다. 서버를 처음 시작할 때 Potato는 labels로 코드북을 시드하고, 각 라벨의 description이 코드의 짧은 정의가 됩니다. 그 이후에는 데이터베이스가 코드북을 보유하며 labels를 편집해도 아무것도 바뀌지 않습니다. 2.13.1 브라우저 인터페이스에서 코더는 최상위 코드를 추가하고 항목의 본문을 편집할 수 있으며, 코드의 이름 바꾸기, 이동, 삭제는 코드북 API를 거칩니다. 주 라운드에서는 codebook_mode: fixed로 설정하고 서버를 다시 시작하세요. fixed 모드에서는 누구도 코드를 추가, 이름 변경, 이동, 삭제할 수 없으며, 정의 편집은 관리자나 판정자가 승인하거나 거부하는 제안으로 대기열에 들어갑니다.

코드북 페이지에서 항목 작성하기

/codebook 페이지에서 각 코드의 항목은 유형이 있는 블록의 목록입니다. Markdown으로 작성한 항목을 붙여 넣고 코드를 고르면 Potato는 각 제목을 해당 블록 아래에 정리합니다.

markdown

### Short definition
 
The teacher describes the time or effort that remote teaching took.
 
### Use when
 
Hours, preparation, grading, or messages that took longer than in a classroom.
 
### Avoid when
 
Tiredness or stress with no task or time named.
 
### Examples
 
"The lesson plans took twice as long because everything had to work on a phone."
 
### Counter-examples
 
"I was exhausted all the time."

Use when은 포함 기준을, Avoid when은 제외 기준을 담습니다. ### Definition 블록은 전체 정의를 담고, ### Rationale 블록은 코드의 기원을 담을 수 있습니다. Potato에는 비전형적 예시를 위한 별도 블록이 없습니다. 비전형적 예시는 메모를 달아 Examples 아래에 넣으세요. 코더는 발췌문 옆의 Codebook 트레이에서 각 코드의 짧은 정의를 봅니다.

중첩 코드

트레이는 중첩 코드를 트리로 보여 주며, 2.13.1 트레이에는 코드를 중첩시키는 컨트롤이 없습니다. 2.13.1의 codebook과 qdpx 내보내기는 코드북 기반 스킴의 코드를 최상위에 나열하며, codebook.csv의 parent와 color 열은 비어 있습니다. Potato 밖으로 온전히 나가야 하는 트리는 내용 분석에 설명된 대로 CSV 파일에서 불러온 hierarchical_multiselect 스킴이 적합합니다. 그러면 코더는 코딩 중에 코드를 편집할 수 없습니다.

라운드 사이에 코드 추가하기

처음 시작한 뒤 labels에 추가한 연역적 코드는 코드북 CLI를 통해 코드북에 반영됩니다.

bash

potato codebook config.yaml

이 명령은 코드북에 없는 모든 YAML 라벨에 대해 코드를 만들며 이름만 복사합니다. 새 코드의 정의는 /codebook에서 작성하세요. CLI는 서버가 이미 시드한 코드북에서만 실행하세요. 빈 코드북에서는 CLI가 YAML 설명 없이 코드를 만들고, 서버는 시드를 건너뜁니다. 2.13.1의 potato codebook 진입점은 --dry-run 플래그를 무시하고 코드를 씁니다. 쓰지 않고 미리 보려면 python -m potato.codebook_cli config.yaml --dry-run을 실행하세요.

수정 번호와 변경 이력

코드를 추가, 이름 변경, 이동, 병합, 삭제하면 코드북의 수정 번호가 올라가며, Potato는 저장된 각 어노테이션에 적용 중이던 수정본을 표시합니다. 트레이의 Review 목록은 이후 수정 전에 코더가 저장한 발췌문을 각 코더에게 보여 줍니다. 항목의 본문을 편집해도 수정 번호는 바뀌지 않습니다. /admin/iaa의 일치도 페이지는 일치도 드리프트와 재보정 라운드에 설명된 대로 시간에 따른 일치도 표 아래에 코드북 수정본을 나열합니다.

2.13.1에서는 트레이에서 수행한 병합이나 분할이 코드북을 바꾸되 이미 저장된 코딩은 건드리지 않습니다. 병합된 코드로 코딩한 발췌문은 어노테이션 파일에 옛 코드의 이름을 그대로 유지합니다. 그러면 팀은 그 발췌문을 다시 코딩하거나 분석 중에 옛 이름을 새 이름에 매핑하고, 그 결정을 변경 기록에 남깁니다.

수정 스탬프는 프로젝트 데이터베이스에 남고 어노테이션 내보내기에는 들어가지 않습니다. 방법 절을 위해 코드북 버전을 고정하려면 각 라운드가 끝날 때 코드북을 내보내고 스냅숏을 찍으세요.

bash

python -m potato.export -c config.yaml -f codebook -o ./export/
potato snapshot create config.yaml --note "Codebook 2.0, after the pilot" --tag codebook-2.0

내보내기는 각 코드의 짧은 정의와 코더가 그 코드를 적용한 횟수가 담긴 codebook.csv를 씁니다. 포함 및 제외 기준과 예시는 /codebook과 프로젝트 데이터베이스에 남습니다. 스냅숏은 구성, 데이터, 어노테이션, 프로젝트 데이터베이스를 태그 codebook-2.0 아래 묶습니다. 스냅숏의 콘텐츠 해시는 구성, 데이터, 어노테이션을 포함하지만 데이터베이스는 포함하지 않습니다. 따라서 코드북만 바뀐 라운드는 해시가 그대로이며, potato snapshot create는 --force를 줄 때만 그 라운드를 저장합니다. 스냅숏 명령은 프로젝트 스냅숏이 다룹니다.

자주 묻는 질문

정성 코드북에는 무엇이 들어가야 하나요?

정성 코드북에는 모든 코드의 항목이 들어 있으며, 각 항목에는 이름, 짧은 정의와 전체 정의, 포함 및 제외 기준, 데이터에서 가져온 전형적, 비전형적, 반례 예시가 있습니다. 많은 팀은 각 코드의 기원과 상위 코드도 기록합니다. 코드북 전체에는 버전 번호, 날짜, 변경 기록이 있습니다.

코드북은 연역적 코드를 써야 하나요, 귀납적 코드를 써야 하나요?

많은 팀 코드북은 둘을 모두 사용하여, 이론, 선행 연구, 인터뷰 가이드에서 가져온 연역적 코드로 시작하고 시범 전사문이 만들어 내는 귀납적 코드를 추가합니다. 순수한 연역적 코드북은 이름이 정해진 범주를 검증하는 연구에 맞고, 순수한 귀납적 코드북은 근거 이론 같은 탐색적 작업에 맞습니다.

코드북 변경의 감사 추적은 어떻게 유지하나요?

코드북의 각 버전에 번호를 매기고, 모든 변경을 날짜, 이유, 동의한 사람과 함께 기록하며, 어떤 버전으로 각 전사문을 코딩했는지 기록해서 감사 추적을 유지하세요. Potato에서는 저장된 각 어노테이션이 적용 중이던 코드북 수정본을 기록하며, 각 라운드가 끝날 때 potato snapshot create config.yaml --tag codebook-2.0을 실행하면 코드북이 어노테이션과 함께 고정됩니다.

더 읽을거리

정성 코딩을 위한 공유 코드북, Potato의 모든 코드북 옵션
QDA 모드, 열린 코드북, 메모, 케이스로 한 분석가가 전체 말뭉치를 코딩하기
질적 연구의 코더 간 신뢰도
정성 코딩을 위한 인터뷰 전사문 준비하기
정성 코딩에 LLM을 사용하고 보고하는 방법
두 코더로 인터뷰 전사문을 코딩하고 알파 보고하기, 두 코더가 적용하는 코드북에서 Krippendorff의 알파와 QDPX 파일까지
효과적인 어노테이션 지침 작성하기
LLM이 따를 수 있는 코드북 작성하기
정성 데이터 분석 소프트웨어 비교
Potato의 정성 연구

참고문헌

DeCuir-Gunby, J. T., Marshall, P. L., & McCulloch, A. W. (2011). Developing and Using a Codebook for the Analysis of Interview Data: An Example from a Professional Development Research Project. Field Methods, 23(2), 136-155. https://doi.org/10.1177/1525822X10388468
Fereday, J., & Muir-Cochrane, E. (2006). Demonstrating Rigor Using Thematic Analysis: A Hybrid Approach of Inductive and Deductive Coding and Theme Development. International Journal of Qualitative Methods, 5(1), 80-92. https://doi.org/10.1177/160940690600500107
MacQueen, K. M., McLellan, E., Kay, K., & Milstein, B. (1998). Codebook Development for Team-Based Qualitative Analysis. CAM Journal (Cultural Anthropology Methods), 10(2), 31-36. https://doi.org/10.1177/1525822X980100020301
Roberts, K., Dowell, A., & Nie, J.-B. (2019). Attempting rigour and replicability in thematic analysis of qualitative research data; a case study of codebook development. BMC Medical Research Methodology, 19, 66. https://doi.org/10.1186/s12874-019-0707-y
Jurgens, D., Chen, M., & Iyer, L. (2026). Potato 2.0: A Comprehensive Annotation Platform with AI-in-the-Loop Support. Proceedings of the 64th Annual Meeting of the Association for Computational Linguistics (Volume 3: System Demonstrations), 374-386. https://aclanthology.org/2026.acl-demo.37/