为质性研究编制码本

质性码本列出一项研究中的每个代码，每个条目给出代码的名称、定义、何时使用与何时不使用该代码的标准，以及来自数据的示例。团队通常先从理论或研究问题中取出演绎代码，在阅读中加入发现的归纳代码，用几份转录稿试编码，并为每次修订编号。每份编码结果都记下版本号，读者就能看出哪一版码本编码了哪一份转录稿。

在质性研究中，编码是给访谈转录稿、焦点小组、田野笔记或开放式问卷回答的摘录贴上简短标签的过程，这些标签称为代码。演绎代码在编码开始前就来自理论、已有研究或访谈提纲，归纳代码则在编码过程中来自数据。这两个术语借用了演绎和归纳推理的方向。编码者间信度衡量两名编码者对同一批摘录使用相同代码的频率。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/