harness-engineering

# Harness Engineering 学习档案

> 记录我学习「Harness Engineering」的完整过程：从概念理解到独立实践。
>
> 来源：[OpenAI — Harness Engineering: Harnessing Codex in an Agent-First World](https://openai.com/zh-Hans-CN/index/harness-engineering/)

## 仓库结构

| 目录 | 内容 | 说明 |
|------|------|------|
| `concepts/` | 概念笔记 | 原文核心概念的拆解与整理 |
| `thinking/` | 独立思考 | 自己的理解、质疑、延伸思考 |
| `practice/` | 动手实践 | 小项目实验，验证文章中的方法论 |
| `feedback/` | 反馈记录 | 实践中的踩坑、修正、迭代心得 |
| `works/` | 作品输出 | 可展示的成果（文章、工具、模板等） |
| `tools/` | 工具具像化 | 降低 6 维复杂度的杠杆库（带主张，不是 awesome-list） |
| `prompts/` | 提示词积累 | 学习过程中验证有效的提示词 |
| `references/` | 外部资源 | 相关文章、仓库、工具的索引 |

## 学习路线（进度）

- [x] Phase 1：理解核心概念（concepts/，8 篇）
- [x] Phase 2：形成自己的观点（thinking/，11 篇，持续中）
- [x] Phase 3：选一个小项目实践（practice/，1 个 Ralph Demo）
- [x] Phase 4：记录反馈迭代（feedback/，1 篇，持续中）
- [x] Phase 5：输出可展示的作品（works/，40 篇翻译 + 1 篇原创 + 2 篇外部中文收录）

> 进度详情以人类向 README.md 的"学习路线"段为准；本节是给智能体的快照。

## 导航

每个子目录都有自己的 AGENTS.md，说明该目录的用途、内容组织方式和写作约定。
从任何一个目录开始，都能找到下一步该看什么。

## 机械化检查

`scripts/check-consistency.sh` 守护"漂移"问题：

- **C1** — `references/articles.md` 编号 1..N 连续
- **C2** — N 与下游 4 处声明同步（README badge × 2、`prompts/deep-research-tracker.md` 头部、`references/AGENTS.md` 概览）。文件含独立行 `<!-- check-consistency: skip-count -->` 时豁免
- **C3** — `concepts/`、`thinking/`、`feedback/` 的 `*.md` 实际数与 README 中"X 篇"声明一致
- **C4** — `works/*-translation.md` 文件数 ≡ 翻译计数所有声明（badges、`<details>` 摘要、Phase 5 注释、本文件 Phase 5 快照、READMEs 表格行数）
- **C5** — README 结构树中 `concepts/` 子树的 item 行数 ≡ `concepts/*.md` 文件数（防止"计数对了但树漏了"）
- **C6** — `references/articles.md` 末尾"不计入 N 篇"中的 N ≡ C1 权威值
- **C7** — 三脉络 per-track 计数（脉络一/二/三）在 4 处下游声明保持一致：READMEs 资料库表、`references/AGENTS.md` 三脉络小标题、`prompts/deep-research-tracker.md` 三脉络明细
- **C8** — 翻译流水线本地守卫：`translate/<...>/sources/<slug>/source-full.md` 存在时，对应 `01-analysis.md` 不得再声称"仅摘要页 / 建议补抓全文"。`translate/` 已 gitignore，CI 与干净 clone 自动 SKIP，仅本地有过程稿时触发
- **C9** — `concepts/` / `thinking/` / `feedback/` 正文不得裸写文库计数（"N 篇文章 / N 篇翻译 / N 大概念"）；历史性提法须带"写作时点 / 当时 / 此前 / 首批 / 首轮 / 截至 / 快照"限定词，否则去数字改链 `references/articles.md`
- **C10** — 图片保真（纯本地、零网络）：每篇 `works/*-translation.md` 的 frontmatter 必须声明 `sourceFigureCount`（缺失即 FAIL；`null` = 原文不可得、未审计 → SKIP；数字 N → 正文嵌图数须 ≥ N），且所有本地嵌图路径（`imgs/...`）必须在磁盘上存在
- **C11** — markdown 表格形状：README ×2、`references/AGENTS.md`、`references/articles.md`、`works/AGENTS.md` 里每一行表格的单元格数须与表头一致
- **C12** — 条目字段完整性：`references/articles.md` 每个 `### N.` 编号条目必须带 **作者：** 与 **日期：** 字段
- **C13** — 零插图声明须留痕：C10 只能证伪"多报"（嵌图数 < 声明数才 FAIL），因此 `sourceFigureCount: 0` 在本地**永远无法被证伪**——不管你有没有真去核对原文，它都是绿的。2026-07-27 就是这个洞放行了一个假 0（原文实有 4 张配图）。C10 刻意零网络、无法回查原文，所以改为要求留痕：**声明 0 的译文必须同时带 `sourceFigureAudit` 字段，值里要有 `YYYY-MM-DD` 核对日期**，写清怎么核对的、结论是什么。`null` 仍然 SKIP——它本来就自陈未审计
- **C14** — 文档站防漂移：VitePress 站点（部署到 harness.dyu.sh）的侧边栏与首页统计一律由 `.vitepress/sidebar.mjs` 在构建时从文件系统生成，不手写。三条不变量：站点源码（`index.md`、`.vitepress/`）不得出现裸计数（"N 篇"），数字只能来自 `computeStats()`；每个一等内容文件必须在生成的侧边栏中恰好出现一次；仓库内禁止任何 symlink——Vite 会解引用 `public/` 下的软链、图片管线会读取链接目标，一条软链即可把仓库外文件带进公开产物（后两条经 `node .vitepress/sidebar.mjs --verify` 执行）。构建产物侧另有 `scripts/verify-dist.mjs` 断言页面与 `.md` 副本一一对应、副本链接可达、dist 无 symlink。站点脚手架不存在时 SKIP；node 不可用时 verify 半边 SKIP、裸计数 grep 照常执行

执行：`bash scripts/check-consistency.sh`（仓库根目录）
启用 pre-commit 阻断：`git config core.hooksPath .githooks`

**CI 兜底**：`.github/workflows/consistency.yml` 在每次 push / PR 时跑同一脚本（不做路径过滤，保证必需检查总能上报）。job 显示名固定为 `consistency / check`——分支保护按 check run 名匹配必需检查，改名会让所有 PR 重新被 "Expected" 卡住。
本地 hook 是开发反馈，CI 是合并门——两层独立，本地未启用 hook 不会绕过检查。

More agent context in deusyu/harness-engineering

9 other files this repository gives its agents.