很多人第一次给 AI 写项目规则，会把所有背景、所有流程、所有偏好都塞进一个超长文件。短期看似完整，长期却会变成上下文噪音。Harness Engineering 提倡“地图而非手册”：入口文件负责指路，细节文件负责解释。
为什么地图更好
AI Agent 的上下文是有限资源。入口文件越长，越容易挤占真正任务需要的代码、错误输出和验证结果。更好的做法是让 AGENTS.md 保持短小，按任务指向对应文档。
文内插图：把源仓库文档转化为教程、清单和可验证学习路径。| 写法 | 优点 | 风险 |
|---|
| 巨型说明书 | 信息看似齐全 | 上下文拥挤、难维护、难验证 |
| 地图式入口 | 轻量、清晰、可扩展 | 需要维护文档链接 |
| 脚本和检查配套 | 能自动发现漂移 | 需要投入一点工程化成本 |
AGENTS.mddocs/PROJECT.mddocs/ARCHITECTURE.mddocs/OPERATIONS.mdtests / scripts
入口文件只告诉 Agent 哪些文档是下一层上下文。一个好入口应包含什么
- 项目一句话定位。
- 重要目录和真相源。
- 常用验证命令。
- 高风险边界，例如生产、数据库、凭证、发布流程。
- 遇到不同任务时应该继续读哪些文档。
源文档学习快照
这一节由当前 GitHub 源文档生成，用来保证教程正文能跟随仓库变化刷新。当前主源文档：concepts/00-overview.md。
核心概念一句话定义六大核心概念1. 仓库即记录系统（Repo as System of Record）2. 地图而非手册（Map, Not Manual）3. 机械化执行（Mechanical Enforcement）
当源仓库文档更新后，这里的结构和摘要会在同步任务中重新生成。| 当前源文档 | 读者应关注 | 同步含义 |
|---|
| concepts/00-overview.md | 来源：OpenAI 2026-02-11，作者 Ryan Lopopolo 背景：3人团队用 Codex 从空仓库到100万行代码，5个月，零… | 源文档 SHA 会写入文章 meta，正文快照会随同步任务刷新。 |
- 一句话定义
- 六大核心概念
- 1. 仓库即记录系统（Repo as System of Record）
- 2. 地图而非手册（Map, Not Manual）
- 3. 机械化执行（Mechanical Enforcement）
GitHub Markdown：concepts/00-overview.md
Harness Engineering 概念总览
来源：OpenAI 2026-02-11，作者 Ryan Lopopolo 背景：3人团队用 Codex 从空仓库到100万行代码，5个月，零手写代码
一句话定义
Harness Engineering = 工程师不再写代码，而是设计环境、明确意图、构建反馈回路，让 AI 智能体可靠地完成工作。
六大核心概念
1. 仓库即记录系统（Repo as System of Record）
- 不在仓库里的东西，对智能体来说不存在
- Slack 讨论、Google Docs、脑子里的知识 = 对智能体不可见
- 一切决策、规范、计划都必须以版本化工件提交到仓库
2. 地图而非手册（Map, Not Manual）
- AGENTS.md ≈ 目录页（~100行），不是百科全书
- 渐进式披露：从小入口点开始，指向更深层的文档
- 巨型指令文件的三个死因：挤占上下文、无法维护、无法机械验证
3. 机械化执行（Mechanical Enforcement）
- 文档会腐烂，lint 规则不会
- 自定义 linter + 结构测试 = 不变量的守护者
- lint 错误信息里内嵌修复指令，智能体可以自我纠正
4. 智能体可读性（Agent Readability）
- 优先选择"无聊"技术（API 稳定、训练集覆盖好）
- 有时重新实现子集比包装不透明的上游行为更划算
- 让应用可以按 git worktree 启动，智能体可以启动隔离实例
5. 熵管理 = 垃圾回收（Entropy & Garbage Collection）
- 智能体会复现仓库中已有的模式——包括坏模式
- "黄金规则"编码进仓库，定期后台任务扫描偏差
- 技术债 = 高息贷款，小额持续偿还
6. 人类掌舵，智能体执行（Humans Steer, Agents Execute）
- 人类时间是最稀缺的资源
- 出问题时，答案不是"更努力"，而是"缺什么上下文/工具/约束"
- 工程师的新角色：设计环境 → 拆解任务 → 提示智能体 → 验证结果
架构模型
每个业务域内的固定分层：
Types → Config → Repo → Service → Runtime → UI
横切关注点通过 Providers 进入（auth, telemetry, feature flags）
依赖只能向前流动，由 linter 强制执行
关键数据点
- 3人团队 → 5个月 → ~100万行代码 → ~1500个 PR
- 人均每天 3.5 个 PR，扩展到 7 人后吞吐量还在增长
- 单次 Codex 运行可持续 6+ 小时（通常在人类睡眠时间）
- 估算：约为手工编写的 1/10 时间
