TL;DR

  1. 核心概念：Legible Knowledge（可读知识）= 仓库本地 + 版本化 + 结构化。对Agent而言，只有满足三条件的知识才”存在”；对人类可访问的Google Docs、Slack讨论、人脑经验，对Agent是黑箱。
  2. 关键机制：Harness工程的”无手写代码”约束强制知识显性化——架构决策、编码规范、流程约定、已知坑都必须写入代码仓库，并结构化维护。
  3. 实际效果：Agent得以理解系统；新员工与Agent同一起跑线；组织知识实现机构化，不再随人员流动流失。
  4. 延伸洞察：这不是技术选择，而是社会技术系统重构——知识管理本质是组织设计问题。

一个尖锐的观察

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

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

考虑一下你团队的日常：

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

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

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

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

什么是 Legible Knowledge

OpenAI 引入了一个关键概念：

Legible Knowledge（可读知识）

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

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

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

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

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

💡 Key Insight

知识对人类”存在”和对 Agent “存在”是两个完全不同的标准。Harness 工程迫使我们用 Agent 的视角重新审视知识的可访问性。

什么是 Legible Knowledge

可读性的光谱

Legible Knowledge 不是非此即彼的二元划分，而是一条从不可读到完全可读的光谱。大多数组织的知识散布在这条光谱的不同位置：

  • ❌ 完全不可读：存储在 Google Docs 中的架构文档、散落在 Slack 频道的历史讨论、老员工脑子里未文档化的经验判断、会议中口头做出的决策——这些对 Agent 是彻底的黑箱。
  • ⚠️ 半可读：写在 Confluence 但未版本化的文档、存放在 Notion 但结构混乱的知识库——Agent 能读取，但无法追踪演进历史，也无法确信内容时效性。
  • ✅ 完全可读：存入 Git 仓库、用 Markdown 结构化编写、有 git blame 可追溯每一条结论的来历——这就是 Legible Knowledge 的标准形态。

三个判断维度：仓库本地（不在外部系统）、版本化（有完整历史）、结构化（可被程序解析）。三条全部满足，才是 Harness 工程意义上的”知识存在”。

隐性知识的代价

为什么隐性知识是问题？

对 Agent：无法理解系统

Agent 无法：

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

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

对人类：Onboarding 的痛苦

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

新员工的典型困惑：

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

答案往往是：

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

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

对组织：知识的流失

当知识锁在员工脑子里：

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

💡 Key Insight

知识显性化的最大受益者不是 Agent，而是未来的人类员工和整个组织。Agent 只是一个推手，真正的价值在于组织知识体系的建立。

社会学意义上的范式转移

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

Harness 工程

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

传统软件工程

在大多数组织里，软件工程实践默认依赖隐性知识。架构决策通过 Zoom 会议讨论，会后没有书面记录；最佳实践在 Slack 频道里分享，两周后被数百条新消息淹没；代码审查的反馈只在 PR 评论里存在，随合并而消失；经验传承靠师徒制，知识随着老员工的离职而离开。这些做法对人类协作者来说勉强可以接受——通过参加会议、翻阅历史、面对面交流可以获取——但对 Agent 来说，它们根本不存在。Agent 无法参加会议、无法有效检索 Slack 历史、无法”耳濡目染”学习团队文化。传统软件工程的隐性知识依赖，在 Agent 时代暴露出了结构性缺陷：最关键的系统知识，恰恰是 Agent 最无法获取的知识。

Harness 工程

Harness 工程的本质是强制知识显性化：所有对系统有影响的决策——架构选择、编码规范、流程约定、已知的坑——都必须写入代码仓库，并以结构化的方式维护。这不是一种技术偏好，而是一种组织约束。它要求每个团队成员在做出重要决策时，强制回答一个问题：”这个决策的记录在哪里？”知识的载体从人的脑子、会议室、Slack 频道，迁移到代码仓库中的 Markdown、ADR、代码注释。版本化带来了历史追溯，结构化带来了可解析性，仓库本地带来了统一的访问入口——Legible Knowledge 的三个条件在这里同时满足。这为 Agent 的有效工作提供了前提，也让人类组织本身变得更可审计、更易传承。

💡 Key Insight

当我们说”知识入库”，本质是在重新设计组织的决策流程。技术只是载体，社会学才是本质。

具体转变

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

实践：如何推动知识入库

实践：如何推动知识入库

会议的文化转变

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

传统会议

传统会议的典型生命周期：会上讨论激烈，会后只留下一份模糊的参会人名单和几条宽泛的 Action Items。真正的决策背景——为什么选 A 不选 B、哪些方案被明确否决、谁在什么问题上投了反对票——全部存在与会者的个人记忆里。两周后开会的人自己都记不清了，六个月后这些决策就成了”历史遗留问题”的根源。知识的生命周期在会议结束时同步结束。

Harness 工程做法

Harness 工程的会议文化要求：会议结束后，必须有一个人负责将结论写入仓库，作为该次会议的正式产出物。这个产出物不是会议纪要的流水账，而是结构化的决策记录：结论是什么、依据是什么、谁同意了、谁有异议待定。写入仓库后，这条记录与代码、Issue、PR 形成交叉引用——未来任何人（无论是人类还是 Agent）想知道”这个决定是怎么做出的”，都有迹可循。决策不再是一次性事件，而成为可持续追溯的知识资产。

Code Review 的知识提取

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

💡 Key Insight

Code Review 的评论是团队最即时、最具体的知识来源——问题是它们和 PR 一起死。知识提取的本质，是把一次性讨论变成持续生效的规则。

Harness 工程做法

PR 评论中包含大量即时产生的具体知识：为什么这个变量名不好、这个边界条件漏了什么、这段逻辑在什么前提下才能成立——这些都是 reviewer 用经验换来的判断，最真实、最具体，但也最脆弱。Harness 工程的做法是：PR 合入之前，有价值的一行评论胜过一个模糊的’LGTM’；合入之后，负责合入的人有义务将评论中的实质性讨论提取成仓库级规则——可以是 Coding Guidelines 的一条注释、ADR 里的一个决策节点、或者团队 Wiki 里的一条已知问题记录。这样，一次 Code Review 的知识产出从”这次 PR 知道了”变成”团队永远知道了”。

传统会议

传统会议的典型生命周期：会上讨论激烈，会后只留下一份模糊的参会人名单和几条宽泛的 Action Items。真正的决策背景——为什么选 A 不选 B、哪些方案被明确否决、谁在什么问题上投了反对票——全部存在与会者的个人记忆里。两周后开会的人自己都记不清了，六个月后这些决策就成了”历史遗留问题”的根源。知识的生命周期在会议结束时同步结束。

Harness 工程做法

Harness 工程的会议文化要求：会议结束后，必须有一个人负责将结论写入仓库，作为该次会议的正式产出物。这个产出物不是会议纪要的流水账，而是结构化的决策记录：结论是什么、依据是什么、谁同意了、谁有异议待定。写入仓库后，这条记录与代码、Issue、PR 形成交叉引用——未来任何人（无论是人类还是 Agent）想知道”这个决定是怎么做出的”，都有迹可循。决策不再是一次性事件，而成为可持续追溯的知识资产。

渐进式显性化

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

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

💡 Key Insight

渐进式显性化的关键不是一次性完美，而是持续积累。每个 Sprint 留下一份文档，三个月后就是一部团队知识手册。

阻力与应对

“这太慢了”

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

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

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

“有些知识无法文档化”

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

区分：

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

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

“这改变了我们的文化”

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

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

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

💡 Key Insight

阻力往往来自对”知识即权力”的隐性信仰。把知识公开不是削弱某人的价值，而是让整个组织变得更有竞争力。

更深层的哲学

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

什么是组织的真正资产？

传统答案：

  • 代码
  • 产品
  • 品牌
  • 人才

Harness 工程提示的答案：

  • 知识系统

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

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

💡 Key Insight

知识管理不是技术问题，是组织设计问题。当知识成为基础设施，组织的运作方式就会发生根本性变化。

今日毒舌

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

想想你现在的团队：

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

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

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

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

结语

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

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

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

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

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

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

深度阅读时间：约 13 分钟

参考来源：

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

← 返回 AI-Native 工程系列