為質性研究編制碼本

質性碼本列出一項研究中的每個程式碼，每個條目給出程式碼的名稱、定義、何時使用與何時不使用該程式碼的標準，以及來自資料的示例。團隊通常先從理論或研究問題中取出演繹程式碼，在閱讀中加入發現的歸納程式碼，用幾份轉錄稿試編碼，併為每次修訂編號。每份編碼結果都記下版本號，讀者就能看出哪一版碼本編碼了哪一份轉錄稿。

在質性研究中，編碼是給訪談轉錄稿、焦點小組、田野筆記或開放式問卷回答的摘錄貼上簡短標籤的過程，這些標籤稱為程式碼。演繹程式碼在編碼開始前就來自理論、已有研究或訪談提綱，歸納程式碼則在編碼過程中來自資料。這兩個術語借用了演繹和歸納推理的方向。編碼者間信度衡量兩名編碼者對同一批摘錄使用相同程式碼的頻率。MacQueen 等人（1998）在論述美國疾病控制與預防中心的團隊編碼時，把結構化的碼本描述為文本動態分析的穩定框架。MacQueen 等人所描述的碼本特徵，是為了提高編碼者之間的一致性而選定的。

下面各節討論的是由一組人在質性分析中使用的碼本。撰寫有效的標註指南討論用於訓練或評估模型的標註任務中的標籤規則，編寫 LLM 能夠遵循的碼本討論由語言模型使用的碼本。質性編碼的共享碼本逐項說明 Potato 碼本功能的每個選項。

演繹程式碼、歸納程式碼與混合程式碼

演繹碼本在編碼開始前寫成，隨後的編碼會顯示碼本中的類別在多大程度上描述了參與者所說的內容。歸納碼本則在你閱讀的過程中逐步擴充。不符合任何程式碼的段落成為候選程式碼，當這個想法在多名參與者那裡反覆出現時，候選程式碼就獲得一個條目。主題分析和紮根理論都依賴歸納編碼。

許多團隊項目把兩個方向結合起來。Fereday 和 Muir-Cochrane（2006）在一項關於護理工作績效反饋的研究中，描述了一種把資料驅動程式碼與理論驅動程式碼整合起來的混合流程。DeCuir-Gunby、Marshall 和 McCulloch（2011）給出了為訪談資料開發理論驅動程式碼和資料驅動程式碼、並培訓其他編碼者使用碼本的步驟。Roberts、Dowell 和 Nie（2019）根據研究問題、文獻、同一項目中的一份問卷以及對訪談的初步瀏覽建立了初始碼本，隨後允許意料之外的主題在編碼過程中加入。在混合碼本中，每個條目都記錄程式碼的來源。讀者由此可以看出，哪些程式碼是研究帶到資料中的，哪些程式碼是資料產生的。

程式碼條目的組成部分

程式碼條目要告訴一位在程式碼被創造時並不在場的編碼者如何使用這個程式碼。Roberts、Dowell 和 Nie（2019）為每個程式碼寫出標籤、定義、描述、限定或排除條件，以及來自原始資料的示例。下表在這一形式上增加了納入標準、非典型示例、反例和程式碼來源。示例是一項關於教師遠端教學經歷的研究中的一個演繹程式碼：

當兩個程式碼捱得很近時，排除標準最為重要；點名相鄰程式碼的排除標準會告訴編碼者在兩個程式碼中選哪一個。示例要取自你自己的轉錄稿，並去除可識別身份的細節。編造的示例會漏掉真實口語中的離題和說到一半的句子。

父程式碼與子程式碼

較長的碼本做成樹形更便於使用。父程式碼命名一個寬泛的類別，例如 Workload，子程式碼命名研究希望分開計數的變體，例如下班後與家長的聯絡。每個子程式碼都需要單獨的條目。父程式碼的條目要說明編碼者是直接使用父程式碼，還是隻通過子程式碼使用，因為同時使用兩者的編碼者會讓父程式碼的計數翻倍。在混合碼本中，歸納程式碼常常作為演繹父程式碼的子程式碼加入。在遠端教學研究中，試編碼發現了一些關於工作侵入家庭生活的段落，團隊於是把 Home and work boundary（家庭與工作的邊界）新增為 Workload 的子程式碼。

用幾份轉錄稿試編碼

試編碼是在正式一輪編碼之前，把碼本草稿應用到幾份轉錄稿上。選擇彼此不同的試編碼轉錄稿（例如每個地點或群體各取一名參與者），並讓兩名編碼者各自獨立編碼每一條摘錄。逐條比較兩份編碼結果，並對每處分歧判斷是條目不清楚，還是摘錄本身有歧義。不清楚的條目需要更清晰的定義、新的排除標準或新的示例。

修訂之後，要編碼新的轉錄稿，而不是再次編碼試編碼用過的轉錄稿。根據試編碼轉錄稿寫出的條目與那些轉錄稿很契合，重新編碼同樣的材料，幾乎看不出碼本在新訪談上的表現。在試編碼上算出的係數描述的是碼本草稿，寫作中報告的信度來自之後的一輪。DeCuir-Gunby 等人討論了在培訓編碼者的過程中建立信度。團隊就最終版本達成一致後，只有在不修改就無法繼續編碼的地方才修改碼本。Roberts 等人在檢驗其最終版本時記錄了分歧，並遵循了同樣的規則。

團隊修訂程式碼

團隊修訂包括以下幾種：

• 細化。 當編碼者對條目的理解不同時，改寫定義或增加排除標準。
• 新增。 為資料不斷產生的歸納程式碼寫一個條目。
• 合併。 當編碼者分不清兩個程式碼時，把兩個程式碼併為一個。
• 拆分。 把編碼者用來表示兩種不同想法的程式碼分開。
• 停用。 刪除無人使用的程式碼；如果該程式碼的缺席本身就是一項發現，則保留該程式碼並加註說明。

由團隊中的一個人負責編輯碼本，其他成員在定期會議上提出修改，而不是在讀轉錄稿的中途直接編輯條目。每項決定都在修改日誌中記一行帶日期的記錄，寫明修改內容、理由以及同意的人。合併或拆分會改變早先編碼結果的含義，日誌要列出這次修改涉及的摘錄。

碼本的版本管理

為碼本的每個版本編上版本號和日期，例如試編碼草稿為 1.0，正式一輪使用的碼本為 2.0，並保留每一個版本。在每份轉錄稿的編碼結果旁記下版本號。方法部分由此可以說明哪一版碼本編碼了哪一份轉錄稿。當一次修改改變了某個程式碼的含義時，按早先版本編碼的轉錄稿要針對該程式碼重新編碼，或者報告為按早先定義編碼。只修正措辭或增加示例的修改不需要重新編碼。把最終版本和修改日誌作為附錄或補充檔案發表。

Potato 中的碼本

Potato 2.13.1 把碼本儲存在項目資料庫中，並記錄每一次修改。下面的配置設定了遠端教學研究的試編碼輪次。兩名編碼者都編碼每一條摘錄，編碼者可以在閱讀時新增程式碼，使用者 lead 作為裁定者編輯定義併合並程式碼：

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 就會把每個標題歸入匹配的塊：

### 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 進入碼本：

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 中，從側邊欄進行的合併或拆分只改變碼本，已經儲存的編碼結果保持不變。用被合併程式碼編碼過的摘錄，在標註檔案中仍保留舊程式碼的名稱。團隊隨後要麼重新編碼這些摘錄，要麼在分析時把舊名稱對應到新名稱，並在修改日誌中記錄這一決定。

修訂號標記儲存在項目資料庫中，不會出現在標註匯出裡。為了在方法部分固定某個碼本版本，請在每一輪結束時匯出碼本並建立快照：

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 並如實報告
• 由兩名編碼者編碼訪談轉錄稿並報告 alpha，介紹由兩名編碼者使用碼本，一直到 Krippendorff's alpha 和 QDPX 檔案的全過程
• 撰寫有效的標註指南
• 編寫 LLM 能夠遵循的碼本
• 質性資料分析軟體比較
• 用 Potato 做質性研究

參考文獻

1. 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
2. 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
3. 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
4. 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
5. 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/