# 编写指南

如何写出真正有用的领域文件——不只是结构正确，而是能改变 Agent 的判断。

## 快速开始

1. 复制 `templates/minimal-domain/` 到你的工作目录
2. 重命名为你的领域 ID（如 `my_domain`）
3. 编辑每个 JSON 文件——填入选角括号中的占位符
4. 验证：`npx kdna dev validate <你的领域目录>`
5. 测试：`kdna verify <你的领域目录>`

## 从窄开始

不要试图一次性编码整个行业。

**差：** `leadership`
**好：** `frontline_team_feedback`
**最好：** `feedback-delivery-first-time-manager`

窄领域迫使你写出真正能改变行为的公理。宽领域只能产出泛泛的建议。

## 写好的公理

公理是领域的核心判断原则。它们必须改变 Agent 的回应方式。

### 什么是好的公理

- **具体**：两位专家会同意它何时适用
- **可证伪**：你可以构造一个它不适用的场景
- **改变行为**：Agent 有它和没它会说出不同的答案

### 好与坏的对比

| 差（口号） | 好（可操作） |
|-----------|------------|
| "沟通很重要。" | "说话者的意图和听者的解读是不同的东西。判断差距，而非文字。" |
| "要以用户为中心。" | "当用户请求功能 X 时，先识别他们想达成的结果。功能是手段，结果是目的。" |
| "信任在销售中很重要。" | "价格异议是确定性不足，不是价格问题。降价处理症状，建立确定性处理原因。" |

## 写好的立场

立场是领域的默认姿态。"当不确定时，倾向这边。"

差的立场是口号（"要诚实。"）。好的立场是处方（"对不确定性的透明比对自信的错答更能建立信任。"）。

## 写好的误解识别

误解通常比定义更有用。

差的误解是稻草人（"沟通不重要。"——没有 Agent 会这样认为）。
好的误解是真实困惑（"如果对方不高兴，我应该先处理情绪。"——很多 Agent 默认如此，因为感觉更共情。但正确做法是：识别情绪背后的未满足需求。）

## 发布前检查清单

提交领域之前，确认：

- [ ] 每条公理在至少一个具体场景中改变了 Agent 行为
- [ ] 每个本体概念有真正的边界（不是"不是 X"）
- [ ] 每个立场是处方性的（会使 Agent 偏向不同答案）
- [ ] 每个误解描述了一个真实 Agent 可能持有的信念
- [ ] 每条自检是只对该领域有意义的 yes/no 问题
- [ ] 所有触发信号在文本中可观测
- [ ] `kdna-lint` 零警告通过
- [ ] `kdna-validate` 通过
- [ ] 无 KDNA vs 有 KDNA 的对比显示了判断变化，而不仅仅是词汇差异
