知识必须入库：Harness 工程的社会学维度

TL;DR

那个在 Slack 上对齐架构模式的团队讨论？如果 Agent 无法发现，它对系统就是不可读的——就像对新员工是未知的一样。

OpenAI 的 Harness 工程实践揭示了一个残酷真相：大多数组织的知识，对 AI Agent 来说实际上不存在。Google Docs、聊天线程、人脑中的经验——这些对人类可访问的知识，对 Agent 是黑箱。Harness 工程的强制性约束意外地推动了一场组织变革：知识必须从隐性走向显性，从临时走向制度化。这不仅让 Agent 能工作，也让人类组织更健康。

📋 本文结构

一个尖锐的观察 —— 大多数知识对 Agent 不存在
什么是 Legible Knowledge —— 可读 vs 不可读
隐性知识的代价 —— 对 Agent、对新员工、对组织
社会学意义上的范式转移 —— 从同步到异步，从口头到书面
实践：如何推动知识入库 —— 决策、会议、Code Review 的转变
阻力与应对 —— “这太慢了”背后的真相
更深层的哲学 —— 知识即基础设施
今日毒舌 —— 关于文档的残酷真相
结语 —— 隐性知识的时代正在结束

一个尖锐的观察

OpenAI 在 Harness 工程实践中，得出了一个令人不安的结论：

大多数组织的知识，对 AI Agent 来说，实际上不存在。

考虑一下你团队的日常：

架构决策在 Zoom 会议中讨论，会后没有记录
最佳实践在 Slack 线程中分享，两周后被淹没
代码审查的反馈在 PR 评论中散落，随合并而消失
关键背景信息在老员工的脑子里，离职时带走

这些知识对人类是可访问的——通过参加会议、阅读历史、面对面交流。但对 Agent 来说，它们是黑箱。

Harness 工程的强制性约束——”没有手写代码”——意外地揭示了一个长期被忽视的组织问题：

我们对隐性知识的依赖，已经到了危险的程度。

什么是 Legible Knowledge

OpenAI 引入了一个关键概念：

Legible Knowledge（可读知识）

从 Agent 的视角看，只有满足以下条件的信息才”存在”：

✅ 仓库本地：存储在代码库中，而非外部系统
✅ 版本化：有完整的历史记录
✅ 结构化：可以被机械化解析

对应的，Illegible Knowledge（不可读知识）包括：

❌ Google Docs 中的设计文档
❌ Slack 中的讨论线程
❌ 人脑中的经验和直觉
❌ 会议中的口头决策

这不是说这些知识没有价值。而是说，它们对 Agent 不可见，因此在 Harness 工程语境下，它们对系统是不可靠的。

可读性的光谱

完全可读                    完全不可读
    |                           |
    v                           v
┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐
│ 代码    │  │ 结构化  │  │ 非结构化│  │ 人脑    │
│         │  │ 文档    │  │ 文档    │  │ 经验    │
└─────────┘  └─────────┘  └─────────┘  └─────────┘
   Agent        Agent        人类         人类
   可读写      可读          可读         可读

隐性知识的代价

为什么隐性知识是问题？

对 Agent：无法理解系统

Agent 无法：

参加会议
阅读 Slack 历史
“耳濡目染”学习团队文化

如果关键知识只存在于人类对话中，Agent 就无法做出符合系统整体利益的决策。

对人类：Onboarding 的痛苦

隐性知识的问题不只影响 Agent。

新员工的典型困惑：

“这个设计为什么是这样的？”
“我们应该遵循什么模式？”
“谁做这个决定？”
“这段代码有什么坑？”

答案往往是：

“去问问老王”
“翻翻 Slack 历史”
“当时我们讨论过…”

Harness 工程的要求意外地解决了这个问题：当所有知识必须入库，新员工和 Agent 站在了同一起跑线。

对组织：知识的流失

当知识锁在员工脑子里：

员工 A 离职
    ↓
知识 A 消失
    ↓
团队效率下降
    ↓
新员工重复踩坑
    ↓
周期 restart

Harness 工程通过强制要求知识显性化，意外地实现了组织知识的机构化。

社会学意义上的范式转移

Harness 工程的要求，本质上是在推动一种组织知识的显性化。

传统软件工程

知识分布：
├── 代码（显性）
├── 文档（部分显性，常过时）
├── 会议/聊天（隐性，临时）
└── 人脑（隐性，易流失）

协作模式：同步沟通为主
├── 站会同步进度
├── 会议讨论决策
└── 私聊解决问题

Harness 工程

知识分布：
├── 代码（显性，机器可读）
├── 结构化文档（显性，机器可验证）
├── 执行计划（显性，版本化）
└── 人脑（最小化，仅创造性决策）

协作模式：异步文档为主
├── AGENTS.md 作为入口
├── 计划作为一等公民
└── 讨论结果必须入库

这不是技术选择，而是社会技术系统的重构。

具体转变

传统做法	Harness 工程做法
会议讨论 → 口头决策	会议讨论 → 写入仓库 → 决策
Slack 讨论 → 遗忘	Slack 讨论 → 总结入库
Code Review → 评论	Code Review → 规则入库
经验传承 → 师徒制	经验传承 → 文档化

实践：如何推动知识入库

1. 从决策开始

每当团队做出重要决策，强制追问：

“这个决策的记录在哪里？”

不是”我们记得讨论过”，而是：

# docs/decisions/2026-03-15-use-graphql.md

## 背景
REST API 在复杂查询场景下效率低下

## 考虑的选项
1. REST + 自定义查询参数
2. GraphQL
3. tRPC

## 决策
选择 GraphQL

## 理由
- 前端团队已有经验
- 生态成熟
- 第三方集成友好

## 影响
- 需要重写 API 层
- 前端需要学习 GraphQL

## 日期
2026-03-15

## 参与者
@alice, @bob, @carol

2. 会议的文化转变

传统会议：

讨论 → 决策 → 执行 → （两周后遗忘为什么这样决定）

Harness 工程会议：

讨论 → 记录到仓库 → 决策 → 执行 → （永久可查阅）

会议结束后，必须有人将结论写入仓库。这不是官僚主义，而是让决策可执行。

3. Code Review 的知识提取

PR 评论中的有价值的讨论，往往随 PR 合并而消失。

Harness 工程做法：

审查中发现的问题
    ↓
  是否重复出现？
    ↓
  是 → 转化为 linter 规则
    ↓
  否 → 记录到 troubleshooting 文档

示例：

# 从 PR 评论中提取的规则

# ❌ 之前：每次 Review 都要提醒
# Reviewer: "这里应该用依赖注入，不要直接实例化"

# ✅ 之后：自动化检查
# .pylintrc
[DESIGN]
disable=
    direct-instantiation,  # 必须使用依赖注入
    
# 自定义 linter 规则
class DependencyInjectionChecker(BaseChecker):
    """检查是否使用了依赖注入"""
    def visit_call(self, node):
        if self.is_direct_instantiation(node):
            self.add_message("direct-instantiation", node=node)

4. 渐进式显性化

不要试图一次性重构所有知识。采用渐进策略：

Week 1-2：新建模块强制知识入库 Week 3-4：关键决策必须记录 Week 5-8：逐步迁移核心文档 Month 3+：老模块重构时补充文档

阻力与应对

“这太慢了”

反驳：短期看确实增加了文档工作。但长期看：

减少了重复解释的时间
加速了新人 onboarding
让 Agent 可以承担更多工作

数据：Netflix 研究发现，良好的文档可以将新员工生产力提升时间缩短 30-50%。

“有些知识无法文档化”

承认：确实存在难以形式化的隐性知识——审美直觉、经验判断、创造性洞察。

区分：

可以显性的：架构决策、编码规范、流程步骤、已知问题
必须隐性的：战略判断、创新方向、人际协调、审美直觉

Harness 工程的目标不是消除所有隐性知识，而是最小化对隐性知识的依赖。

“这改变了我们的文化”

接受：是的，这确实是一种文化变革。

从”我们聊聊”到”我们写进仓库”，这是一种根本性的转变。

但也许，这种转变是必要的——不仅为了 Agent，也为了人类自己的协作效率。

更深层的哲学

Harness 工程的社会学维度，触及了一个更深层的问题：

什么是组织的真正资产？

传统答案：

代码
产品
品牌
人才

Harness 工程提示的答案：

知识系统

当知识被正确结构化、版本化、可验证，它就成为了一种基础设施——可以被人类和机器共同使用，可以跨时间传承，可以规模化扩展。

这不是对人类的贬低。相反，这是把人类从”知识搬运工”的角色中解放出来，专注于创造新知识和做出判断——这些是目前 Agent 还无法替代的能力。

今日毒舌

“知识必须入库”听起来像是一个技术约束。但它实际上是一面照妖镜，照出了大多数团队的知识管理有多混乱。

想想你现在的团队：

有多少决策只有参加会议的人知道？
有多少”潜规则”只能靠踩坑学习？
有多少文档已经过期但没人敢删？
有多少知识随着离职员工一起消失了？

Harness 工程只是给了我们一个借口——不，一个理由——去正视这些问题。

但说实话，如果没有 Agent 的强制约束，有多少团队会主动改变？

也许这就是为什么我们需要 AI：不是为了取代人类，而是为了强迫人类做早就该做的事。

结语

“知识必须入库”不是一个技术约束，而是一个组织变革的催化剂。

当 OpenAI 说”那个 Slack 讨论如果不在仓库里，对 Agent 就是不可读的”，他们不仅仅是在谈论 Agent。他们也在谈论：

一个月后忘记决策背景的自己
刚加入团队一头雾水的新员工
离职后带走关键知识的同事

Harness 工程的要求，意外地击中了现代软件工程的一个痛点：我们对隐性知识的过度依赖。

解决这个问题的过程，不仅是让 Agent 能有效工作，更是让人类组织本身变得更健康、更可持续。

这才是 Harness 工程最深刻的社会学意义。

参考来源：

OpenAI: Harness engineering: leveraging Codex in an agent-first world
George: Harness 工程就是控制论

← 返回 AI-Native 工程系列