Definition Harness: 让代码仓库对人和 AI 都更"可读"
> 来源: GitHub - CNBorn/definition-harness | POSITIONING.md | OpenAI Harness Engineering
> 日期: 2026-05-08
> 作者: CNBorn | 语言: Markdown 文档模板（语言无关）
> Star: 新项目 | 许可: 未标注
一句话版本
Definition Harness 是一套"仓库说明书"模板——教你怎么在项目里写文档、写规范、写测试，让人和 AI 都能看懂这个项目到底在干什么、为什么这么干、是不是在按预期跑。
它是什么？
Definition Harness 是一个仓库级的规范工具集，不是代码框架，不是提示词模板，而是一套文档结构和协作规则。它解决了一个所有 AI 辅助开发都会碰到的问题：
> 项目的意图存在哪里？在人脑子里、在聊天记录里、还是在代码里？
Definition Harness 的答案是：存在仓库里，用规范的文档结构存。
核心理念：三支柱独立
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 文档 │ │ 代码 │ │ 测试 │
│ (描述行为) │ │ (实现行为) │ │ (验证行为) │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
└────────────────────┼─────────────────────┘
│
三者相互校验
没有一个能替代另一个
关键约束：功能在代码里实现了 ≠ 这件事做完了。必须有文档描述它、有测试验证它。
文档层次
| 类型 | 作用 | 例子 |
|---|---|---|
| **原则 (Principles)** | 稳定的意图——为什么 | `documentation-principles.md` |
| **定义 (Definitions)** | 当前的、可测试的行为 | `authentication-definition.md` |
| **架构 (Architecture)** | 边界和所有权 | `architecture.md` |
| **开发流程 (Dev Flow)** | 工作如何执行和验证 | `development-flow.md` |
| **AGENTS.md** | 地图，不是大全 | 指向真正的信息来源 |
与"提示词工程"的区别
2023: Prompt Engineering
"怎么写提示词才能让 LLM 给出正确输出"
2024: Context Engineering
"怎么提供足够的上下文让任务可解"
2025-2026: Harness Engineering
"怎么设计仓库结构、工具链、质量门控，
让 AI Agent 可靠地工作"
Definition Harness 属于 Harness Engineering 的最佳实践之一——它不是教你怎么写提示词，而是教你怎么设计一个"AI 友好的"仓库。
模板系统
项目提供了 5 个模板文件：
| 模板 | 用途 |
|---|---|
| `system-definition.template.md` | 定义系统的行为、约束、接口 |
| `item-definition.template.md` | 定义工作项（workflow/feature） |
| `principles.template.md` | 记录设计原则和取舍 |
| `architecture.template.md` | 描述系统边界和依赖方向 |
| `README-docs-section.template.md` | 在 README 中添加文档指引段 |
为什么这值得关注
与 Jay 的项目直接相关
你已经在做的事情，Definition Harness 帮它"正规化"了：
| 你的文件 | 对应 Definition Harness | 状态 |
|---|---|---|
| `AGENTS.md` | AGENTS.md | ✅ 已在使用 |
| `SOUL.md` | 原则 (Principles) | ✅ 已在使用 |
| `MEMORY.md` | 长期知识层 | ✅ 已在使用 |
| `AGENTS.md` 中的流程 | 开发流程 (Dev Flow) | ✅ 已有 |
| 还没有的 | 系统定义 (System Definitions) | ❌ 可以加 |
| 还没有的 | 模板系统 | ❌ 可以借鉴 |
Definition Harness 对你最有价值的部分
1. 系统定义模板：给你的每个项目子系统（deep-research agent、build pipeline、cron 系统）写一份"定义文档"，描述它目前的行为边界
2. 渐进式采用策略：不需要一次性全改好，而是"先挑一个高风险子系统开始"
3. 三支柱校验：确保文档、代码、测试三者对齐——这个原则可以直接用
4. POSITIONING.md 的定位思路：明确告诉别人"这是什么 / 不是什么"
2026 年的行业趋势
搜索结果显示，"harness engineering" 已经成为 2026 年的热门话题：
- Martin Fowler 写了专门的文章
- OpenAI 正式提出了 "harness engineering" 概念
- Shopify 的 Tobi Lütke 讨论了从 prompt 到 context 到 harness 的演进
- 行业共识：prompt engineering → context engineering → harness engineering
OpenAI 原文："Agent = Model + Harness"
评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 思想价值 | ⭐⭐⭐⭐⭐ | 准确捕捉了 AI 时代的仓库知识管理问题 |
| 实用性 | ⭐⭐⭐⭐ | 模板直接可用，但需要根据项目调整 |
| 成熟度 | ⭐⭐⭐ | 新项目，还在迭代中 |
| 对你(jay)的适用性 | ⭐⭐⭐⭐⭐ | 你已经在使用核心概念，这套可以帮你体系化 |
| 独创性 | ⭐⭐⭐⭐ | 不是全新概念，但首次被系统化打包 |
一句话再总结
> "Definition Harness 告诉你：别把项目知识存在脑子里或聊天记录里——用一套规范的文档结构把它写进仓库，让人和 AI 都能看懂。"
建议：你可以考虑在你的 jaylab 项目中引入 system-definition.md 概念——特别是对于 deep-research agent、build pipeline、cron 系统这些核心子系统，写一份"行为定义文档"来描述它们当前该干什么、不该干什么。
报告生成时间: 2026-05-08 08:33 UTC